# Architecture ## Overview Protocol v2 introduces TSS (Threshold Signature Scheme) based cross-chain infrastructure, enabling secure asset transfers across heterogeneous chains including Bitcoin. This document describes the overall architecture and component interactions. ## System Architecture ``` ┌─────────────────────────────────────────────────────────────────────────────┐ │ User/DApp │ └─────────────────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────────────────┐ │ Source Chain │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ Gateway │ │ Vault │ │ Cross-chain │ │ │ │ Contract │───▶│ Address │───▶│ Events │ │ │ └─────────────┘ └─────────────┘ └─────────────┘ │ └─────────────────────────────────────────────────────────────────────────────┘ │ │ Observer Monitoring ▼ ┌─────────────────────────────────────────────────────────────────────────────┐ │ Maintainer Network │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ Maintainer │ │ Maintainer │ │ Maintainer │ │ Maintainer │ │ │ │ A │◀──▶│ B │◀──▶│ C │◀──▶│ D │ │ │ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │ │ │ │ │ │ │ │ └──────────────────┴──────────────────┴──────────────────┘ │ │ │ │ │ P2P Network Communication │ │ TSS KeyGen / KeySign │ └─────────────────────────────────────────────────────────────────────────────┘ │ │ Submit Observations/Votes ▼ ┌─────────────────────────────────────────────────────────────────────────────┐ │ MAP Relay Chain │ │ │ │ ┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐ │ │ │ Maintainer │ │ TSS │ │ Relay │ │ │ │ Manager │ │ Manager │ │ │ │ │ │ Register/Elect/ │ │ TSS Generation/ │ │ Cross-chain │ │ │ │ Incentive/Slash │ │ Switching │ │ Flow Management │ │ │ └──────────────────┘ └──────────────────┘ └──────────────────┘ │ │ │ │ ┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐ │ │ │ Vault │ │ Registry │ │ Gas │ │ │ │ Manager │ │ │ │ Service │ │ │ │ State Transition/│ │ Chain/Token/ │ │ Fee Recording/ │ │ │ │ Asset Recording │ │ Alias Registry │ │ Updating │ │ │ └──────────────────┘ └──────────────────┘ └──────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────────────────┘ │ ┌──────────────────┴──────────────────┐ │ │ ▼ ▼ ┌────────────────────────────────┐ ┌────────────────────────────────┐ │ Contract Chains (EVM/Solana) │ │ Non-contract Chains (Bitcoin) │ │ │ │ │ │ TSS signature submitted to │ │ TSS builds and signs tx │ │ Relay Chain │ │ │ │ │ │ │ │ ▼ │ │ ▼ │ │ Broadcast to target chain │ │ Relayer/Anyone submits sig │ │ │ │ │ │ │ │ ▼ │ │ ▼ │ │ ┌─────────────┐ │ │ ┌─────────────┐ │ │ │ Vault │ │ │ │ Gateway │ │ │ │ Address │ │ │ │ Verify sig │ │ │ │ (TSS) │ │ │ │ Execute │ │ │ └─────────────┘ │ │ │ TSS Switch │ │ │ │ │ └─────────────┘ │ │ │ └────────────────────────────────┘ └────────────────────────────────┘ ``` ## Component Details ### On-Chain Components (MAP Relay Chain) #### Maintainer Manager Manages the lifecycle of Maintainers: * **Registration**: Validators can register as Maintainers * **Election**: Periodic election of active Maintainer set * **Incentives**: Distribution of cross-chain fee rewards * **Slashing**: Penalty for malicious or offline behavior #### TSS Manager Manages TSS key generation and switching: * **KeyGen Coordination**: Triggers and monitors KeyGen process * **Vault Registration**: Records new Vault addresses * **Churn Process**: Coordinates TSS switching during Maintainer set changes #### Vault Manager Manages Vault state across all chains: * **State Tracking**: Active, Retiring, Retired states * **Asset Recording**: Tracks assets in each Vault * **Migration**: Coordinates asset migration during Churn #### Relay Manages cross-chain transaction flow: * **TxIn Processing**: Records inbound cross-chain transactions * **TxOut Scheduling**: Queues outbound transactions for signing * **Status Tracking**: Monitors transaction completion #### Registry Central registry for protocol configuration: * **Chain Registry**: Supported chains and their parameters * **Token Registry**: Supported tokens and mappings * **Alias Registry**: Human-readable names for addresses #### Gas Service Manages cross-chain gas fees: * **Fee Calculation**: Determines fees for each chain * **Fee Updates**: Allows dynamic fee adjustment * **Fee Collection**: Records collected fees ### On-Chain Components (Other Chains) #### Gateway Entry/exit point for cross-chain operations: * **Deposit Handling**: Receives user deposits * **Signature Verification**: Verifies TSS signatures * **Withdrawal Execution**: Releases assets on valid signature * **TSS Key Update**: Updates TSS public key during Churn #### Vault Address TSS-controlled address for asset custody: * **Multi-chain**: Same TSS key generates addresses for all chains * **No Private Key**: No single entity holds the private key * **Threshold Control**: Requires 2/3 Maintainers to sign ### Off-Chain Components (Maintainer Node) #### Observer Monitors cross-chain events: * **Event Detection**: Watches for deposits, withdrawals * **Data Parsing**: Extracts cross-chain parameters * **Submission**: Reports observations to MAP Relay Chain #### Signer Participates in TSS operations: * **KeyGen**: Generates key share during TSS setup * **KeySign**: Participates in transaction signing * **Key Storage**: Securely stores local key share #### P2P Network Communication layer between Maintainers: * **Discovery**: Finds other Maintainer nodes * **Messaging**: Exchanges TSS protocol messages * **Consensus**: Coordinates signing sessions ## Data Flow ### Inbound Transaction (TxIn) ``` 1. User deposits to Vault on Source Chain 2. Observers detect deposit event 3. Observers submit observation to MAP Relay Chain 4. When 2/3+ observations match, TxIn is confirmed 5. Relay contract records the inbound transaction 6. User's balance is credited on target representation ``` ### Outbound Transaction (TxOut) ``` 1. User requests withdrawal on MAP Relay Chain 2. Relay contract creates TxOut record 3. Maintainers receive signing request 4. TSS KeySign produces signature 5. For contract chains: signature submitted to Gateway 6. For Bitcoin: signed transaction broadcast to network 7. Assets released from Vault to user ``` ## Security Architecture ### Threshold Security * **2/3 Threshold**: Requires 2/3 of Maintainers for any operation * **No Single Point of Failure**: No individual can control assets * **Byzantine Fault Tolerance**: System continues with up to 1/3 malicious nodes ### Slashing Conditions | Violation | Penalty | | -------------------------------- | ------------------------- | | Double signing | Severe slash + jail | | Offline during KeySign | Slash points accumulation | | Invalid observation | Slash points | | Failure to participate in KeyGen | Jail | ### Key Rotation (Churn) Regular key rotation ensures: * Removal of compromised Maintainers * Addition of new Maintainers * Fresh key material ## Integration with Light Client Protocol v2 can optionally integrate light client verification: ``` ┌─────────────────────────────────────────────────────────────────┐ │ Enhanced Verification │ │ │ │ 1. TSS signature provides fast finality │ │ 2. Light client provides additional cryptographic proof │ │ 3. Either can be used independently or combined │ │ │ └─────────────────────────────────────────────────────────────────┘ ``` This hybrid approach offers: * **Speed**: TSS signature for fast confirmation * **Security**: Light client for trustless verification * **Flexibility**: Choose based on use case requirements --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://mapo.gitbook.io/dev-docs/protocol-2.0/architecture.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.