Replace some native token with bridge in docs (#1017)

Author: LGLO

changelog.md

@@ -10,25 +10,22 @@ This changelog is based on [Keep A Changelog](https://keepachangelog.com/en/1.1.
   Possibility to interact with smart-contracts used by earlier versions is lost.
   Governance authority will have to establish new partner chain on Cardano.
   All initialization and candidates registrations have to be repeated.
-* Switched from `polkadot-stable2503-07` to `polkadot-stable2506`. `type RuntimeEvent` became deprecated in polkadot-sdk. It has been removed from the toolkit crates. To update to this version of PC toolkit, please remove definition of `type RuntimeEvent` when wiring in runtime.
+* Updated from `polkadot-stable2503-07` to `polkadot-stable2506-2`. `type RuntimeEvent` became deprecated in polkadot-sdk. It has been removed from the toolkit crates. To update to this version of PC toolkit, please remove definition of `type RuntimeEvent` when wiring in runtime.
 * Added extra constant burn fee in `pallet-address-association` to discourage attacks on pallet storage.
-* Fixed panic when running `ariadne-parameters`, `registration-status` and `sidechain-params` subcommands when chain spec without initial authorities is used.
 * Wizards don't require `generate-keys` for `prepare-configuration`. Altered recommended order of `create-chain-spec` and `setup-main-chain-state`.
 * `MainchainAddress` is now serialized as plain String instead of hexstring of its bytes
 * Wizards use optional env vars: PC_CHAIN_CONFIG_FILE and PC_RESOURCES_CONFIG_FILE env variables to
 locate the chain config and resources config files
 * `pallet-block-producer-metadata` is updated with a configurable fee for inserting the metadata, to make attacks on unbounded storage economically infeasible
-* Removed redundant `RawPermissionedCandidateData` type.
 * Added `valid_before` argument to the signed message and all extrinsics in `pallet_block_producer_metadata`. This is to
 prevent unauthorized re-submission of metadata updates. The `sign-block-producer-metadata` command was updated to
 match this change.
-* `partner-chain-cli` (wizards) does not execute `<pc-node> build-spec` but creates the chain-spec.json file directly with a code injected into the command.
+* Removed redundant `RawPermissionedCandidateData` type.
 * Debug strings generated by `byte-string-derive` crate now fully pad output hex with zeros
 * `authority-selection-inherents` crate now exports all its public members from the crate root
 * `select_authorities` in `authority-selection-inherents` crate now returns a `BoundedVec` of `CommitteeMembers`. Projects that used the old version no longer
 need to transform the data in their own runtime code
-* Updates Rust dependency to v1.88, changes WASM target to 'wasm32v1-none'
-* Backward compatible Encode and Decode for legacy chains that operate with AURA and Grandpa keys as session keys.
+* Updated Rust toolchain to v1.90, changed WASM target to 'wasm32v1-none'
 * Macro `observed_async_trait` in `partner-chains-db-sync-data-sources` crate has been made non-public.
 
 ## Added
@@ -47,11 +44,11 @@ In SCALE encoding of inherent data custom implementations of `Encode` and `Decod
 
 `getAriadneParameters` and `getRegistrations` RPC results format has changed, `auraPubKey` and `grandpaPubKey` are replaced by `"keys": {"aura": "...", "gran": "..."}`.
 
-### Unidirectional Token Bridge (Work-in-progress)
+### Unidirectional Token Bridge
 
 A set of modules implementing observability layer, runtime pallet and offchain commands for a trustless token bridge moving tokens from Cardano to the Partner Chain.
 
-This bridge feature works by monitoring an *illiquid supply validator address* on Cardano for new UTXOs. These UTXOs are interpreted as being either user-initiated
+This bridge feature works by monitoring an *illiquid circulation supply validator address* on Cardano for new UTXOs. These UTXOs are interpreted as being either user-initiated
 transfers sent to a specified address on the Partner Chain, or reserve transfers made as part of the chain's operations for the purposes of distributing them as
 block producer rewards on-chain. Handling of the transfers is left to the chain builders themselves to implement according to their business needs and ledger structure.
 
@@ -67,6 +64,7 @@ The data sources will automatically detect this option on startup and adjust the
 
 * `smart-contracts` governance actions were failing due too redundant signature when initiated by non-governance wallet
 * Wizards using 'sidechain' in command line parameters are changed to use 'partner-chain' instead
+* Fixed panic when running `ariadne-parameters`, `registration-status` and `sidechain-params` subcommands when chain spec without initial authorities is used.
 
 ## Removed
 

docs/developer-guides/native-token-reserve-management.md renamed to docs/developer-guides/bridge-and-reserve.md

@@ -1,20 +1,30 @@
-# Native token reserve management
+# Native token bridge and reserve management
 
 ## Overview
 
+The bridge functionality allows to register movement of designated native token (minting policy of it is controlled by users) to the bridge (also called Illiquid Circulation Supply Validator).
+The Illiquid Circulation Supply Validator locks native tokens and prevents moving them out of the bridge.
+For operational reasons (coin selection problem), the system allows setting a minimum number of UTXOs that should always be present at the bridge address, by creating UTXOs that contain a special token. The validator ensures that this token can not be moved out of the address and any UTXOs there can only contain one token each.
+
+Additionally to the bridge there is the Reserve mechanism.
+Reserve is set up by the governance authority with some amount of designated native tokens.
+More tokens can be deposited to the reserve later.
+Any user can release tokens from the reserve to the bridge - conceptually this should be observed at partner chain and some kind of rewards pool should be increased there.
+Release can be done only with the amount that is bounded by so-called `V-function` (release schedule function).
+
 This guide covers the following tasks:
 
 1. **On Cardano:**
 
-- Creating your new token and setting up rules for how tokens are released over time
-- This involves setting up and managing a token management contract on the Cardano blockchain, enabling proper observability on your partner chain.
+- Creating your new token, and optionally setting up rules for how tokens can be released from the reserve over time
+- This involves setting up and managing a bridge and reserve contracts on the Cardano blockchain, enabling proper observability on your partner chain.
 
 2. **On your partner chain:**
 
 - Connecting your partner chain to track the token and enable token operations across both chains
 - This involves following a step-by-step process for interacting with both the Cardano blockchain and your partner chain.
 
-After you complete the steps in this guide, you will have a fully functioning token system that works across Cardano and your partner chain.
+After you complete the steps in this guide, you will have fully functioning bridge and reserve systems that work across Cardano and your Partner Chain.
 
 ![Native token management contract](native-token-mgt-contract.png "Native token management contract")
 
@@ -34,7 +44,7 @@ Please note that rewards schemes for token release is the responsibility of the
 
 # Initialization
 
-Initialization includes creating the native token on Cardano, writing the `VFunction`, running the commands `smart-contracts reserve init` and `smart-contracts reserve create` at the `partner-chains-node` side.
+Initialization includes creating the native token on Cardano, writing the `VFunction`, running the commands `smart-contracts bridge init` and `smart-contracts reserve create-utxos`, `smart-contracts reserve init`, and `smart-contracts reserve create` at the `partner-chains-node` side.
 
 ## 1. Setting up your token on Cardano
 
@@ -60,26 +70,17 @@ Generally speaking, however, the process includes these steps:
 
 ### 1.2 Configuring the token release schedule
 
+The release schedule is only required if the reserve feature is used.
+
 #### 1.2.1 Implementing V(t) release function
 
 **Understanding the `VFunction`:**
 
 - The `VFunction` policy defines the schedule of allowed reserve token movement from the reserve supply to the circulating supply over time
 
-- `VFunction` is a minting policy that has to accept 2 parameters (or more if you like)
-
-   - The first parameter is the `VFunction` Redeemer (which can be anything)
-   - The second parameter is the `ScriptContext` (every smart contract takes this as parameter)
-
-- The Validity interval is to be present and equal to `[T, infinity]`, where `T` is time in the recent past, close to the current time
+- `VFunction` is a minting policy. Offchain code will apply `ScriptContext` with the validity interval start of `T`, where `T` is the timestamp of currently observed chain tip.
 
-- The Transaction input with ReserveAuthPolicy token is to be present
-
-- The `VFunction` should be able to mint X tokens and be invoked repeatedly, each time minting X new tokens. The value of X should grow in time and represent the total number of tokens to be released from the reserve to IlliquidCirculationSupply up to the current moment in time
-
-- Smart contracts do not pass anything to each other directly. However, each smart contract in a given single transaction has access to the context of the whole transaction, including input UTXOs, datums, etc
-
-- Implementers of the `VFunction` should expect the validity interval to be correctly set up by the offchain release command.
+- The `VFunction` should allow to mint at most the maximum number of tokens that are allowed to be released from the reserve until `T`.
 
 **User responsibility:**
 
@@ -129,6 +130,38 @@ cardano-cli conway transaction submit --tx-file tx.signed --testnet-magic 2
 
 5. Find and note the hash#id for the transaction that has the `VFunction` script attached.
 
+### 1.3 Initializing bridge scripts
+
+Objective: Initialize the bridge scripts for your partner chain.
+
+#### 1.3.1 Run the `bridge init` command
+
+Command template:
+
+```bash
+./partner-chains-node smart-contracts bridge init \
+  --genesis-utxo <GENESIS_UTXO> \
+  --ogmios-url <OGMIOS_URL> \
+  --payment-key-file <PAYMENT_KEY_FILE>
+```
+
+The command is idempotent. If it fails at first attempt it is safe to repeat execution.
+The command is a governance action, so it might not submit transactions but instead output the transactions to sign.
+
+#### 1.3.2 Run the `bridge create-utxos` command
+
+Command template:
+
+```bash
+./partner-chains-node smart-contracts bridge create-utxos \
+  --genesis-utxo <GENESIS_UTXO> \
+  --ogmios-url <OGMIOS_URL> \
+  --payment-key-file <PAYMENT_KEY_FILE> \
+  --amount <AMOUNT>
+```
+
+The command is a governance action, so it might not submit transactions but instead output the transactions to sign.
+
 ### 1.3 Initializing token reserve controls
 
 Objective: Initialize the reserve management system for your token.
@@ -207,9 +240,9 @@ Usage includes the `reserve release` and `reserve handover` commands.
 - `reserve handover` &ndash; a command for finishing the flow (either there is nothing to release or the governance authority user wants to finish the flow)
 - `reserve release` &ndash; a command to "move" the flow until the end.
 
-## 2. Releasing tokens from reserve to circulation
+## 2. Releasing tokens from Cardano Reserve to bridge
 
-Objective: Release available reserve tokens (defined by the `VFunction`).
+Objective: Release available reserve tokens (maximum amount is bounded by `VFunction`)
 
 ### 2.1 Run the `reserve release` command
 
@@ -301,23 +334,27 @@ Objective: increase the pool of reserve tokens.
 
 # Configuration
 
-Configuration includes `reserve update-settings` commands used to either change token in reserve or `VFunction`.
+Configuration includes `reserve update-settings` commands used to change the `VFunction`.
 
 <!-- Only "initialize", "create" and "update settings" are related to configuration.  -->
 
 ## 4. Connecting your token to your partner chain
 
 ### 4.1 Gathering required token parameters
 
-Objective: Collect the essential parameters needed to configure the native token management contract on the partner chain.
+Objective: Collect the essential parameters needed to configure the bridge pallet on the partner chain.
 
 #### Required parameters
 
-- NATIVE_TOKEN_POLICY_ID - the policy ID from Step 1.1
+- tokenPolicyId - the policy ID from Step 1.1
+
+- tokenAssetName - the asset name from Step 1.1
+
+- IlliquidCirculationSupplyValidatorAddress - can be obtained from the output of the `get-scripts` command (see below).
 
-- NATIVE_TOKEN_ASSET_NAME - the asset name from Step 1.1
+- dataCheckpoint - it is the lower bound of observability. Chain Genesis UTXO is a good candidate,
+but it can be any UTXO on Cardano, created before the first bridge transfer that should be registered by the Partner Chain
 
-- ILLIQUID_SUPPLY_VALIDATOR_ADDRESS - can be obtained from the output of the `get-scripts` command (see below).
 
 #### 4.1.1 Retrieving the validator address
 
@@ -341,13 +378,13 @@ Locate the validator address in the command output:
 }
 ```
 
-### 4.2 Following the native token migration guide
+### 4.2 Following the bridge migration guide
 
 Objective: Migrate and synchronize the token state between Cardano and the partner chain.
 
 #### Steps
 
-1. Open the [native token migration guide](https://github.com/input-output-hk/partner-chains/blob/master/docs/developer-guides/native-token-migration-guide.md).
+1. Open the [bridge migration guide](https://github.com/input-output-hk/partner-chains/blob/master/docs/developer-guides/bridge-migration-guide.md).
 
 2. Follow each step outlined in the guide.
 
@@ -361,13 +398,13 @@ Objective: Update native token configuration if migration has already happened.
 
 **Warning:** The following steps need to be executed by the governance authority from the sudo account in the Polkadot UI.
 
-1. Run `set_main_chain_scripts` extrinsic on the nativeTokenManagement pallet via the Polkadot UI portal to set the native token `policy ID`, `asset name`, and `illiquid supply validator address`.
+1. Run `set_main_chain_scripts` extrinsic on the bridge pallet via the Polkadot UI portal to set the native token `tokenPolicyId`, `tokenAssetName`, `IlliquidCirculationSupplyValidatorAddress`, and `dataCheckpoint`.
 
 ![Polkadot UI portal](Polkadot-UI-portal-native-token-mgt.png)
 
 2. After submitting a transaction, the native token configuration can be checked via the Polkadot UI portal: developer → chain state
 
-   - `selected state query`: nativeTokenManagement → mainchainScriptsConfiguration
+   - `selected state query`: bridge → mainchainScriptsConfiguration
 
 Example native token configuration:
 

docs/developer-guides/native-token-migration-guide.md renamed to docs/developer-guides/bridge-migration-guide.md

@@ -1,22 +1,22 @@
-# Native Token Management - Migration Guide
+# Bridge - Migration Guide
 
 ## About
 
-This document describes how to add the Native Token Management features to an already running
+This document describes how to add the Bridge features to an already running
 partner chain and how to remove it.
 
 ## Context
 
-The Native Token Management feature in the Partner Chain Toolkit consists of the pallet,
+The Bridge feature in the Partner Chain Toolkit consists of the pallet,
 the primitives crate, and the supporting DB-Sync data source. It complements the main chain component by providing its observability.
 
 Care must be taken when adding this feature to a running chain, because the data source and inherent
 data provider require runtime data for operation.
 
 ## Obtaining the main chain scripts
 
-The native token management observability is configured using the following parameters:
-* `illiquid supply validator address` - this is the address to which the native tokens are sent on the 
+The bridge observability is configured using the following parameters:
+* `illiquid supply validator address` - this is the address to which the native tokens are sent on the
 main chain to lock them so that they can be unlocked on the partner chain. This address is derived
 from the sidechain params and is present in the output of the `addresses` command of the
 `partner-chains-smart-contracts` CLI under `addresses/IlliquidCirculationSupplyValidator`.
@@ -26,16 +26,18 @@ used to represent the partner chain's token on the main chain. Because each nati
 different logic in its minting policy, development and creation of the asset is left for each
 partner chain builder.
 When using the `partner-chains-cli` wizard, these can be set up in the `prepare-configuration` step.
+* `data checkpoint` - this is the UTXO that determines the oldest transaction that observability will take into account,
+chain genesis UTXO is a safe value to use.
 
 ## Migration Steps - adding the feature
 
 ```mermaid
 flowchart TB
-    id1["Obtain native token parameters from configuration"] --> id2["Update partner chain source code"] --> id3["Build new partner chain version"] --> id4["Deploy new partner chain version"] --> id5["Upgrade runtime"] --> id6["Set native token parameters"]
+    id1["Obtain native token parameters from configuration"] --> id2["Update partner chain source code"] --> id3["Build new partner chain version"] --> id4["Deploy new partner chain version"] --> id5["Upgrade runtime"] --> id6["Set native token and data checkpoint parameters"]
 ```
 
 ### Preparing changes
-1. Add the `native-token-management` pallet into the runtime. This requires implementing the trait `TokenTransferHandler`, which
+1. Add the `bridge` pallet into the runtime. This requires implementing the trait `TransferHandler`, which
 is left for the developers of each particular partner chain to implement according to their needs and
 ledger structure. Consult the implementation in `runtime/src/lib.rs` for an example with a mocked handler.
 2. Wire the data source into the node.
@@ -51,13 +53,13 @@ The following steps need to be performed in order:
 1. Upgrade the nodes running the chain to the new node version containing the inherent data provider.
 2. Perform a [runtime upgrade](https://docs.substrate.io/maintain/runtime-upgrades/) (using `sudo` or other governance feature) to the new runtime version containing the pallet.
 3. Invoke the `set_main_chain_scripts` extrinsic on the newly added pallet, using the governance mechanism,
-to set the native token `policy ID` and `asset name`, and the `illiquid supply validator address`. After
+to set the `tokenPolicyId`, `tokenAssetName`, `IlliquidCirculationSupplyValidatorAddress`, and `dataCheckpoint`. After
 this step all information necessary is present, and the native token data provider will start producing
-the inherent data based on observed native token transfers, triggering the pallet's inherent when necessary. 
+the inherent data based on observed native token transfers, triggering the pallet's inherent when necessary.
 
 ## Migration Steps - removing the feature
 
-1. Remove the pallet completely from the runtime. The `TokenTransferHandler` can be removed as well. To support syncing and validating historical blocks, the data source and inherent data provider *must* not be removed from the node.
+1. Remove the pallet completely from the runtime. The `TransferHandler` can be removed as well. To support syncing and validating historical blocks, the data source and inherent data provider *must* not be removed from the node.
 2. Perform [runtime upgrade](https://docs.substrate.io/maintain/runtime-upgrades/).
 
 After this step _no further native token movement will be observed, even if performed on the main chain_.

docs/developer-guides/sdk-update-v1.7-to-v1.8.0.md

@@ -60,3 +60,7 @@ fn current_time() -> u64 {
 	pallet_timestamp::Now::<Runtime>::get() / 1000
 }
 ```
+
+## Bridge
+
+For the bridge please read documents specific to this feature: [operational guide](./bridge-and-reserve.md) and [migration guide](./bridge-migration-guide.md)