From 68589383bb3c40ff5b7a20e8ec81d73bebe02833 Mon Sep 17 00:00:00 2001 From: Andrei Baltariu Date: Mon, 8 Dec 2025 10:59:01 +0200 Subject: [PATCH 01/11] Added repo readme --- README.md | 43 ++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 42 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 96456d87e..f41089a64 100644 --- a/README.md +++ b/README.md @@ -1 +1,42 @@ -Sovereign Bridge SCs +# Sovereign Bridge Smart Contracts + +Contracts that deploy and run a validator-signed bridge between MultiversX and a Sovereign chain. The focus below is on how the on-chain pieces collaborate; shared helper crates sit alongside these contracts but are not described here. + +## Contract Roles + +- `sovereign-forge/`: entry point for sovereign creators; walks through a four-phase deployment to mint a new chain ID and request contract instances from a Chain Factory. +- `chain-factory/`: factory that clones the contract templates for each sovereign (Chain Config, Header Verifier, MultiversX ESDT Safe, Fee Market) and wires ownership to the correct controller. +- `chain-config/`: stores the sovereign’s configuration and validator set (BLS keys). Handles validator registration during the genesis phase and later updates triggered from signed bridge operations. +- `header-verifier/`: keeps the current validator set and verifies BLS-aggregated signatures for bundles of bridge operations (`hashOfHashes`). It gates execution by marking operation hashes as registered/locked/executed. +- `mvx-esdt-safe/`: MultiversX-side vault. Accepts deposits destined for the sovereign chain (burns or escrows tokens based on the chosen mechanism), emits bridge events, and executes incoming signed operations to mint/unlock tokens or perform contract calls. +- `mvx-fee-market/`: manages bridge fees and whitelists on the MultiversX side. Fee changes and whitelist updates are themselves bridge operations that must be signed and registered by the Header Verifier. +- `sov-esdt-safe/`: sovereign-side vault. Burns incoming tokens, emits the events that validators sign, and exposes admin endpoints for updating its configuration and fee sink address. +- `sov-fee-market/`: sovereign-side fee configuration; owners can set/remove fees, distribute balances, and maintain a fee whitelist. +- `interactor/`: chain-simulator flows for end-to-end tests; see `interactor/HowToRun.md`. +- `testing-sc/`: scenario test contract and fixtures. + +## How the Pieces Interact + +- **Bootstrapping a sovereign:** A creator calls `sovereign-forge` in four phases. The forge asks a `chain-factory` (per shard) to deploy Chain Config, MultiversX ESDT Safe, Fee Market, then Header Verifier. When everything is live, `chain-factory::completeSetupPhase` finalizes the Chain Config setup, then transfers ownership of the MultiversX-side contracts to the Header Verifier so all bridge operations are signature-gated. +- **Validator set lifecycle:** During the genesis phase, validators register BLS keys in `chain-config`. The Header Verifier pulls this set on `completeSetupPhase`. Future rotations happen through `header-verifier::changeValidatorSet`, which requires a signed operation hash from the previous epoch and the list of new validator key IDs stored in Chain Config. +- **Sovereign → MultiversX transfers:** Users deposit into `sov-esdt-safe`, which burns the tokens and emits a deposit event. Sovereign validators batch those events into a list of operations, sign the resulting `hashOfHashes`, and the Sovereign Bridge Service calls `header-verifier::registerBridgeOperations` on MultiversX. Each operation is executed through `mvx-esdt-safe::executeBridgeOps`, which locks the operation hash in the Header Verifier, mints/unlocks the needed tokens (or performs a contract call), and then signals completion so the hash is cleared. +- **MultiversX → Sovereign transfers:** Users call `mvx-esdt-safe::deposit`. The contract enforces whitelists/blacklists and fee collection, then either burns wrapped tokens or escrows native ones before emitting a deposit event. Sovereign validators observe these events and mint/unlock the corresponding assets on the sovereign chain according to their local logic. +- **Token mechanics:** `mvx-esdt-safe` supports two modes per token: burn (requires local mint/burn roles and the token to be trusted) or lock (escrow on MultiversX, unlock on return). Registering new sovereign-minted tokens on MultiversX (`registerToken`) issues a new ESDT with the sovereign prefix and maps it to the sovereign identifier; `registerNativeToken` bootstraps the sovereign chain’s own native asset. +- **Fee handling:** Deposits can require an upfront fee payment that is forwarded to `mvx-fee-market::subtractFee`. The MultiversX fee market also exposes bridge-controlled operations to set/remove fees, distribute balances, and manage a whitelist; these paths are guarded by the Header Verifier just like token transfers. +- **Pause and safeguards:** Both safes can be paused; setup phases must be completed before normal bridge operations proceed; hash locking in the Header Verifier prevents duplicate execution and enforces operation nonces. + +> For more details about the Cross-Chain Execution, please take a look at the [official documentation](https://docs.multiversx.com/sovereign/cross-chain-execution). + +## Development + +- Build all contracts: `sc-meta all build` +- Run contract tests from the repo root or within a contract crate: `sc-meta test` +- Simulator E2E flows: follow `interactor/HowToRun.md` (start `sc-meta cs`, delete stale `state.toml`, run the `always_deploy_setup_first` test to seed state, then execute specific tests). + +## Repository Map + +- `sovereign-forge/`, `chain-factory/`: deployment orchestration +- `chain-config/`, `header-verifier/`: validator management and signature verification +- `mvx-esdt-safe/`, `mvx-fee-market/`: MultiversX bridge vault and fee logic +- `sov-esdt-safe/`, `sov-fee-market/`: sovereign-side vault and fee logic +- `interactor/`, `testing-sc/`: integration and scenario tests From 29416ca4d90c901c92184e50f39226db47294694 Mon Sep 17 00:00:00 2001 From: Andrei Baltariu Date: Mon, 8 Dec 2025 11:01:56 +0200 Subject: [PATCH 02/11] Added siren diagram --- README.md | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/README.md b/README.md index f41089a64..f0d0393e8 100644 --- a/README.md +++ b/README.md @@ -25,6 +25,29 @@ Contracts that deploy and run a validator-signed bridge between MultiversX and a - **Fee handling:** Deposits can require an upfront fee payment that is forwarded to `mvx-fee-market::subtractFee`. The MultiversX fee market also exposes bridge-controlled operations to set/remove fees, distribute balances, and manage a whitelist; these paths are guarded by the Header Verifier just like token transfers. - **Pause and safeguards:** Both safes can be paused; setup phases must be completed before normal bridge operations proceed; hash locking in the Header Verifier prevents duplicate execution and enforces operation nonces. +## Siren Diagram + +``` +Sovereign Creator + | + v deploy phases +sovereign-forge -> chain-factory ----------------------+ + | | | + | +--> chain-config (validators) | + | +--> mvx-esdt-safe (vault) | + | +--> mvx-fee-market (fees) | + | +--> header-verifier (owner) <--+ + | +Sovereign Chain MultiversX +------------------ ------------------- + sov-esdt-safe (burn & emit) ----> Validators sign ----> header-verifier + | | + sov-fee-market (fees) <---- fee lookups ----- mvx-esdt-safe -- mvx-fee-market + | + executeBridgeOps <-----+ + (mint/unlock/SC calls) +``` + > For more details about the Cross-Chain Execution, please take a look at the [official documentation](https://docs.multiversx.com/sovereign/cross-chain-execution). ## Development From b28ca28db47d5f5cf6c52fffa35b11892c08946e Mon Sep 17 00:00:00 2001 From: Andrei Baltariu Date: Mon, 8 Dec 2025 11:07:56 +0200 Subject: [PATCH 03/11] Added chain-config readme --- chain-config/README.md | 9 +++++++++ 1 file changed, 9 insertions(+) create mode 100644 chain-config/README.md diff --git a/chain-config/README.md b/chain-config/README.md new file mode 100644 index 000000000..432eb175c --- /dev/null +++ b/chain-config/README.md @@ -0,0 +1,9 @@ +# Chain Config Contract + +Maintains the validator set and sovereign chain configuration. Genesis registration happens here before the bridge is opened, and later updates come through signed bridge operations. + +- **Initialization:** `init` accepts an optional `SovereignConfig` (min/max validators, stakes, limits). Defaults are applied if none is provided. +- **Validator lifecycle:** Validators register/unregister during the setup phase via `register` / `unregister`. After setup, updates flow through bridge-controlled endpoints `registerBlsKey` and `unregisterBlsKey` (operation hashes are locked through the Header Verifier). +- **Configuration updates:** Owners can adjust the sovereign config during setup with `updateSovereignConfigSetupPhase`; after setup the signed path `updateSovereignConfig` is used. +- **Completing setup:** `completeSetupPhase` finalizes genesis once the minimum validator count is present. The Header Verifier then mirrors the validator set for signature checks. +- **Interactions:** The Header Verifier reads the BLS key map stored here to verify bridge bundles. Sovereign Forge deploys this contract first, and Chain Factory clones it from a template when spinning up a new sovereign. From abf5596b7d79173aec829328c57e93e9e059bba4 Mon Sep 17 00:00:00 2001 From: Andrei Baltariu Date: Mon, 8 Dec 2025 11:09:59 +0200 Subject: [PATCH 04/11] Added chain-factory readme --- chain-factory/README.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) create mode 100644 chain-factory/README.md diff --git a/chain-factory/README.md b/chain-factory/README.md new file mode 100644 index 000000000..25507b52c --- /dev/null +++ b/chain-factory/README.md @@ -0,0 +1,13 @@ +# Chain Factory Contract + +Factory that clones the sovereign contract templates on MultiversX and wires ownership to the correct controllers. + +- **Initialization:** `init` receives the Sovereign Forge address plus template addresses for Chain Config, Header Verifier, MultiversX ESDT Safe, and Fee Market. Templates are required to be valid smart contract addresses. +- **Deploying per sovereign:** Only admins (typically the Sovereign Forge) may call: + - `deploySovereignChainConfigContract(opt_config)` + - `deployEsdtSafe(sovereign_owner, sov_prefix, opt_config)` + - `deployFeeMarket(esdt_safe_address, fee)` + - `deployHeaderVerifier(sovereign_contracts)` + Each returns the fresh contract address. +- **Completing setup:** `completeSetupPhase` calls `completeSetupPhase` on Chain Config, then transfers ownership of Chain Config, MultiversX ESDT Safe, and Fee Market to the Header Verifier, and finally completes their setup phases. This makes the Header Verifier the gatekeeper for bridge operations. +- **Interactions:** Sovereign Forge drives deployments through this factory. After phase four, the factory’s setup completion hooks finish wiring the sovereign’s contract suite. From bde263f3c7bc8fbf8ce67e800035111c37892509 Mon Sep 17 00:00:00 2001 From: Andrei Baltariu Date: Mon, 8 Dec 2025 11:15:02 +0200 Subject: [PATCH 05/11] Added header-verifier readme --- header-verifier/README.md | 9 +++++++++ 1 file changed, 9 insertions(+) create mode 100644 header-verifier/README.md diff --git a/header-verifier/README.md b/header-verifier/README.md new file mode 100644 index 000000000..86d2f886d --- /dev/null +++ b/header-verifier/README.md @@ -0,0 +1,9 @@ +# Header Verifier Contract + +Holds the active validator set and verifies BLS-aggregated signatures for bridge operation bundles (`hashOfHashes`). It locks operation hashes to prevent double execution and signals completion back to the calling contracts. + +- **Setup:** `completeSetupPhase` fetches the genesis validator set from Chain Config and marks setup done. Only proceeds once Chain Config completed its own setup. +- **Registering batches:** `registerBridgeOperations(signature, hashOfHashes, bitmap, epoch, operations)` checks setup, validates the signature against the current epoch’s validator keys, ensures the bundle hash matches, and marks each operation hash as `NotLocked`. +- **Validator rotation:** `changeValidatorSet` uses the previous epoch’s signatures to register a new validator key set (by IDs stored in Chain Config). Older epochs are pruned as `MAX_STORED_EPOCHS` is exceeded. +- **Execution locking:** `lockOperationHash(hashOfHashes, opHash, nonce)` marks an operation as `Locked` (enforcing the expected nonce). `removeExecutedHash` clears the status after completion; calling contracts typically use the wrapper in `complete_operation`. +- **Callers:** The contract expects to be the owner of MultiversX ESDT Safe and Fee Market so it can authorize bridge operations. Sovereign Forge arranges this via Chain Factory during setup. From a375589c63fde782cdb7ad1564e4e6d7ea4c1513 Mon Sep 17 00:00:00 2001 From: Andrei Baltariu Date: Mon, 8 Dec 2025 11:16:33 +0200 Subject: [PATCH 06/11] Added mvx-esdt-safe readme --- mvx-esdt-safe/README.md | 10 ++++++++++ 1 file changed, 10 insertions(+) create mode 100644 mvx-esdt-safe/README.md diff --git a/mvx-esdt-safe/README.md b/mvx-esdt-safe/README.md new file mode 100644 index 000000000..bc11e0bf1 --- /dev/null +++ b/mvx-esdt-safe/README.md @@ -0,0 +1,10 @@ +# MultiversX ESDT Safe + +MultiversX-side vault for the bridge. It accepts deposits heading to the sovereign chain, executes signed operations coming from the sovereign side, and manages token registration plus burn/lock mechanics. + +- **Initialization:** `init(sovereign_owner, sovereign_forge_address, sov_token_prefix, opt_config)` sets the sovereign owner/admin, validates the sovereign token prefix, stores config (whitelist/blacklist, gas limits, max amounts), and starts paused. +- **Deposits (MultiversX → Sovereign):** `deposit(to, optTransferData)` enforces pause/blacklists/whitelists, charges bridge fees via the Fee Market, then burns or locks tokens based on the configured mechanism before emitting a deposit event. +- **Execution (Sovereign → MultiversX):** `executeBridgeOps(hashOfHashes, operation)` is called after validators register the bundle in the Header Verifier. It locks the operation hash, mints/unlocks tokens (or performs a contract call), and emits completion. Refunds are handled if execution fails. +- **Token management:** `registerToken` issues a wrapped ESDT for a sovereign token ID (requires fee payment). `registerNativeToken` issues the sovereign chain’s native token during setup. Burn/lock mechanism can be toggled via `setTokenBurnMechanism*` and `setTokenLockMechanism*`. +- **Configuration & safety:** Config updates (`updateEsdtSafeConfig*`), pause control (`pauseContract`), and fee market address are gated by setup checks. `completeSetupPhase` unpauses, ensures native token and fee market are set, and hands off control to the Header Verifier. +- **Interactions:** Owned by the Header Verifier after setup. Calls the Fee Market to subtract fees and the Header Verifier to lock/clear operation hashes. From 5a35e0f8c91884bfb1d1fec97a247ce1b4e4ee31 Mon Sep 17 00:00:00 2001 From: Andrei Baltariu Date: Mon, 8 Dec 2025 11:17:21 +0200 Subject: [PATCH 07/11] Added mvx-fee-market sc --- mvx-fee-market/README.md | 9 +++++++++ 1 file changed, 9 insertions(+) create mode 100644 mvx-fee-market/README.md diff --git a/mvx-fee-market/README.md b/mvx-fee-market/README.md new file mode 100644 index 000000000..db676235e --- /dev/null +++ b/mvx-fee-market/README.md @@ -0,0 +1,9 @@ +# MultiversX Fee Market + +Manages bridge fees and whitelists on the MultiversX side. After setup, fee changes must be authorized through the Header Verifier. + +- **Initialization:** `init(esdt_safe_address, fee)` stores the linked ESDT Safe and optional initial fee schedule. +- **Setup phase paths (owner-only):** `setFeeDuringSetupPhase`, `removeFeeDuringSetupPhase`, `addUsersToWhitelistSetupPhase`, `removeUsersFromWhitelistSetupPhase` allow configuring fees and whitelists before the bridge is opened. +- **Bridge-controlled paths:** `setFee`, `removeFee`, `distributeFees`, `addUsersToWhitelist`, `removeUsersFromWhitelist` are executed via signed operations. Each locks the operation hash in the Header Verifier before applying the change. +- **Completion:** `completeSetupPhase` marks the contract ready for bridge-controlled changes. +- **Interactions:** The ESDT Safe calls `subtractFee` (from shared endpoints) during deposits. The Header Verifier owns this contract after setup to gate operations. From 412084c7ad359211fca4514a6b743e90ac93b813 Mon Sep 17 00:00:00 2001 From: Andrei Baltariu Date: Mon, 8 Dec 2025 11:17:52 +0200 Subject: [PATCH 08/11] Added sov-esdt-safe sc --- sov-esdt-safe/README.md | 9 +++++++++ 1 file changed, 9 insertions(+) create mode 100644 sov-esdt-safe/README.md diff --git a/sov-esdt-safe/README.md b/sov-esdt-safe/README.md new file mode 100644 index 000000000..d32ad6a74 --- /dev/null +++ b/sov-esdt-safe/README.md @@ -0,0 +1,9 @@ +# Sovereign ESDT Safe + +Sovereign-side vault. It burns incoming assets to emit bridge events, lets admins adjust configuration, and anchors fee collection to the sovereign fee market. + +- **Initialization:** `init(fee_market_address, opt_config)` stores the linked fee market, applies config defaults if omitted, and starts paused. +- **Deposits (Sovereign → MultiversX):** `deposit(to, optTransferData)` burns the provided tokens and emits a deposit event containing the transfer data for validators to sign. +- **Registering assets:** `registerToken` issues a sovereign-wrapped token ID (requires the standard issue cost in EGLD). Tokens must carry the sovereign prefix. The call burns the payment and emits a registration event. +- **Configuration:** `updateConfiguration` updates the ESDT Safe config (whitelist/blacklist, gas limits, caps). `setFeeMarketAddress` retargets the fee sink. +- **Interactions:** The Fee Market on the sovereign side is the fee controller. Events emitted here are batched and signed by validators; matching operations are later executed on MultiversX by the Header Verifier + MultiversX ESDT Safe. From c3a1d5085f0ef07202f46975dd6b7f073936da7f Mon Sep 17 00:00:00 2001 From: Andrei Baltariu Date: Mon, 8 Dec 2025 11:18:19 +0200 Subject: [PATCH 09/11] Added sov-fee-market readme --- sov-fee-market/README.md | 7 +++++++ 1 file changed, 7 insertions(+) create mode 100644 sov-fee-market/README.md diff --git a/sov-fee-market/README.md b/sov-fee-market/README.md new file mode 100644 index 000000000..bab6da827 --- /dev/null +++ b/sov-fee-market/README.md @@ -0,0 +1,7 @@ +# Sovereign Fee Market + +Simple fee controller on the sovereign chain. Owners configure fees, distribute balances, and maintain a whitelist. + +- **Initialization:** `init(esdt_safe_address, fee)` links the sovereign ESDT Safe and optionally seeds an initial fee. +- **Operations (owner-only):** `setFee`, `removeFee`, `distributeFees`, `addUsersToWhitelist`, `removeUsersFromWhitelist`. +- **Interactions:** The sovereign ESDT Safe references this contract for fee lookups when processing deposits destined for MultiversX. From 23d62aeea46ee05b5ae2dccacb55edfbe7bcb43b Mon Sep 17 00:00:00 2001 From: Andrei Baltariu Date: Mon, 8 Dec 2025 11:19:22 +0200 Subject: [PATCH 10/11] Added sovereign-forge readme --- sovereign-forge/README.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) create mode 100644 sovereign-forge/README.md diff --git a/sovereign-forge/README.md b/sovereign-forge/README.md new file mode 100644 index 000000000..dd567f434 --- /dev/null +++ b/sovereign-forge/README.md @@ -0,0 +1,13 @@ +# Sovereign Forge + +Orchestrates the four-phase deployment of a sovereign’s MultiversX-side contracts via Chain Factory and tracks chain IDs per creator. + +- **Initialization:** `init(opt_deploy_cost)` sets the required EGLD deposit for deployments and pauses the contract. +- **Registering factory/trusted tokens:** `registerChainFactory(shard_id, address)` wires a Chain Factory per shard. `registerTrustedToken` stores token IDs allowed for burn/lock mechanics downstream. +- **Deployment phases (caller = sovereign creator):** + - `deployPhaseOne(opt_preferred_chain_id, config)` → deploy Chain Config and reserve a chain ID. + - `deployPhaseTwo(opt_config)` → deploy MultiversX ESDT Safe with the reserved prefix. + - `deployPhaseThree(fee)` → deploy MultiversX Fee Market linked to the ESDT Safe. + - `deployPhaseFour()` → deploy Header Verifier with references to the other contracts. +- **Finishing setup:** `completeSetupPhase` triggers Chain Factory to run the per-contract `completeSetupPhase` calls and transfer ownership to the Header Verifier. Marks the sovereign as setup-complete. +- **Interactions:** Drives Chain Factory to clone templates. Validators and the Header Verifier rely on the chain ID generated here to namespace token IDs and contract lookups. From 59a3a9d2d206508a02ab78c16d6930c3e2e76d94 Mon Sep 17 00:00:00 2001 From: Andrei Baltariu Date: Mon, 8 Dec 2025 14:37:55 +0200 Subject: [PATCH 11/11] Fixes after review --- README.md | 4 ++-- chain-config/README.md | 2 +- header-verifier/README.md | 2 +- mvx-esdt-safe/README.md | 2 +- 4 files changed, 5 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index f0d0393e8..c028d7cb6 100644 --- a/README.md +++ b/README.md @@ -19,13 +19,13 @@ Contracts that deploy and run a validator-signed bridge between MultiversX and a - **Bootstrapping a sovereign:** A creator calls `sovereign-forge` in four phases. The forge asks a `chain-factory` (per shard) to deploy Chain Config, MultiversX ESDT Safe, Fee Market, then Header Verifier. When everything is live, `chain-factory::completeSetupPhase` finalizes the Chain Config setup, then transfers ownership of the MultiversX-side contracts to the Header Verifier so all bridge operations are signature-gated. - **Validator set lifecycle:** During the genesis phase, validators register BLS keys in `chain-config`. The Header Verifier pulls this set on `completeSetupPhase`. Future rotations happen through `header-verifier::changeValidatorSet`, which requires a signed operation hash from the previous epoch and the list of new validator key IDs stored in Chain Config. -- **Sovereign → MultiversX transfers:** Users deposit into `sov-esdt-safe`, which burns the tokens and emits a deposit event. Sovereign validators batch those events into a list of operations, sign the resulting `hashOfHashes`, and the Sovereign Bridge Service calls `header-verifier::registerBridgeOperations` on MultiversX. Each operation is executed through `mvx-esdt-safe::executeBridgeOps`, which locks the operation hash in the Header Verifier, mints/unlocks the needed tokens (or performs a contract call), and then signals completion so the hash is cleared. +- **Sovereign → MultiversX transfers:** Users deposit into `sov-esdt-safe`, which burns the tokens and emits a deposit event. Sovereign validators batch those events into a list of operations, sign the resulting `hashOfHashes`, and the Sovereign Bridge Service calls `header-verifier::registerBridgeOps` on MultiversX. Each operation is executed through `mvx-esdt-safe::executeBridgeOps`, which locks the operation hash in the Header Verifier, mints/unlocks the needed tokens (or performs a contract call), and then signals completion so the hash is cleared. - **MultiversX → Sovereign transfers:** Users call `mvx-esdt-safe::deposit`. The contract enforces whitelists/blacklists and fee collection, then either burns wrapped tokens or escrows native ones before emitting a deposit event. Sovereign validators observe these events and mint/unlock the corresponding assets on the sovereign chain according to their local logic. - **Token mechanics:** `mvx-esdt-safe` supports two modes per token: burn (requires local mint/burn roles and the token to be trusted) or lock (escrow on MultiversX, unlock on return). Registering new sovereign-minted tokens on MultiversX (`registerToken`) issues a new ESDT with the sovereign prefix and maps it to the sovereign identifier; `registerNativeToken` bootstraps the sovereign chain’s own native asset. - **Fee handling:** Deposits can require an upfront fee payment that is forwarded to `mvx-fee-market::subtractFee`. The MultiversX fee market also exposes bridge-controlled operations to set/remove fees, distribute balances, and manage a whitelist; these paths are guarded by the Header Verifier just like token transfers. - **Pause and safeguards:** Both safes can be paused; setup phases must be completed before normal bridge operations proceed; hash locking in the Header Verifier prevents duplicate execution and enforces operation nonces. -## Siren Diagram +## System Diagram ``` Sovereign Creator diff --git a/chain-config/README.md b/chain-config/README.md index 432eb175c..d96ccc6b0 100644 --- a/chain-config/README.md +++ b/chain-config/README.md @@ -6,4 +6,4 @@ Maintains the validator set and sovereign chain configuration. Genesis registrat - **Validator lifecycle:** Validators register/unregister during the setup phase via `register` / `unregister`. After setup, updates flow through bridge-controlled endpoints `registerBlsKey` and `unregisterBlsKey` (operation hashes are locked through the Header Verifier). - **Configuration updates:** Owners can adjust the sovereign config during setup with `updateSovereignConfigSetupPhase`; after setup the signed path `updateSovereignConfig` is used. - **Completing setup:** `completeSetupPhase` finalizes genesis once the minimum validator count is present. The Header Verifier then mirrors the validator set for signature checks. -- **Interactions:** The Header Verifier reads the BLS key map stored here to verify bridge bundles. Sovereign Forge deploys this contract first, and Chain Factory clones it from a template when spinning up a new sovereign. +- **Interactions:** The Header Verifier reads the BLS key map stored here to verify bridge operations. Sovereign Forge deploys this contract first, and Chain Factory clones it from a template when spinning up a new sovereign. diff --git a/header-verifier/README.md b/header-verifier/README.md index 86d2f886d..0e8829677 100644 --- a/header-verifier/README.md +++ b/header-verifier/README.md @@ -3,7 +3,7 @@ Holds the active validator set and verifies BLS-aggregated signatures for bridge operation bundles (`hashOfHashes`). It locks operation hashes to prevent double execution and signals completion back to the calling contracts. - **Setup:** `completeSetupPhase` fetches the genesis validator set from Chain Config and marks setup done. Only proceeds once Chain Config completed its own setup. -- **Registering batches:** `registerBridgeOperations(signature, hashOfHashes, bitmap, epoch, operations)` checks setup, validates the signature against the current epoch’s validator keys, ensures the bundle hash matches, and marks each operation hash as `NotLocked`. +- **Registering operations:** `registerBridgeOps(signature, hashOfHashes, bitmap, epoch, operations)` checks setup, validates the signature against the current epoch’s validator keys, ensures the bundle hash matches, and marks each operation hash as `NotLocked`. - **Validator rotation:** `changeValidatorSet` uses the previous epoch’s signatures to register a new validator key set (by IDs stored in Chain Config). Older epochs are pruned as `MAX_STORED_EPOCHS` is exceeded. - **Execution locking:** `lockOperationHash(hashOfHashes, opHash, nonce)` marks an operation as `Locked` (enforcing the expected nonce). `removeExecutedHash` clears the status after completion; calling contracts typically use the wrapper in `complete_operation`. - **Callers:** The contract expects to be the owner of MultiversX ESDT Safe and Fee Market so it can authorize bridge operations. Sovereign Forge arranges this via Chain Factory during setup. diff --git a/mvx-esdt-safe/README.md b/mvx-esdt-safe/README.md index bc11e0bf1..d107a8817 100644 --- a/mvx-esdt-safe/README.md +++ b/mvx-esdt-safe/README.md @@ -4,7 +4,7 @@ MultiversX-side vault for the bridge. It accepts deposits heading to the soverei - **Initialization:** `init(sovereign_owner, sovereign_forge_address, sov_token_prefix, opt_config)` sets the sovereign owner/admin, validates the sovereign token prefix, stores config (whitelist/blacklist, gas limits, max amounts), and starts paused. - **Deposits (MultiversX → Sovereign):** `deposit(to, optTransferData)` enforces pause/blacklists/whitelists, charges bridge fees via the Fee Market, then burns or locks tokens based on the configured mechanism before emitting a deposit event. -- **Execution (Sovereign → MultiversX):** `executeBridgeOps(hashOfHashes, operation)` is called after validators register the bundle in the Header Verifier. It locks the operation hash, mints/unlocks tokens (or performs a contract call), and emits completion. Refunds are handled if execution fails. +- **Execution (Sovereign → MultiversX):** `executeBridgeOps(hashOfHashes, operation)` is called after validators register the operation in the Header Verifier. It locks the operation hash, mints/unlocks tokens (or performs a contract call), and emits completion. Refunds are handled if execution fails. - **Token management:** `registerToken` issues a wrapped ESDT for a sovereign token ID (requires fee payment). `registerNativeToken` issues the sovereign chain’s native token during setup. Burn/lock mechanism can be toggled via `setTokenBurnMechanism*` and `setTokenLockMechanism*`. - **Configuration & safety:** Config updates (`updateEsdtSafeConfig*`), pause control (`pauseContract`), and fee market address are gated by setup checks. `completeSetupPhase` unpauses, ensures native token and fee market are set, and hands off control to the Header Verifier. - **Interactions:** Owned by the Header Verifier after setup. Calls the Fee Market to subtract fees and the Header Verifier to lock/clear operation hashes.