# Overview Welcome to the MAP Protocol documentation. This guide helps users, node operators, and application developers get started with MAP Protocol. ## What is MAP Protocol? MAP Protocol is a peer-to-peer cross-chain infrastructure enabling secure interoperability between different blockchains. It supports: * Cross-chain asset transfers * Cross-chain messaging * Omnichain application development ## Getting Started ### For Users Learn about MAP Protocol and how to use cross-chain services. * [Introduction](/learn/introduction) * [Architecture Overview](/learn/architecture/overview) ### For Node Operators Run nodes and participate in the network. * [Run Node](/run-node/overview) * [Become Validator](/validator/become-validator) * [Run Compass-TSS (v2)](/compass-tss-crossx/overview) ### For Developers Build cross-chain applications on MAP Protocol. * [Development Guide](/develop/overview) * [Cross-chain Application](/develop/cross-chain-application/overview) * [API & SDK](/api-and-sdk/json-rpc/standard-rpc) ## Documentation Structure | Section | Description | | ---------------------------------------------------------------------------------- | -------------------------------- | | [Learn](/learn/introduction) | Understand MAP Protocol concepts | | [Network](/network/relay-chain) | Network and contract information | | [Run Node](/run-node/overview) | Node operation guides | | [Validator](/validator/become-validator) | Validator guides | | [Compass-TSS](/compass-tss-crossx/overview) | Compass-TSS (v2) operation | | [Develop](/develop/overview) | Application development | | [API & SDK](/api-and-sdk/json-rpc/standard-rpc) | API reference and SDK | | [Resources](https://github.com/mapprotocol/docs/blob/master/resources/glossary.md) | Glossary and links | ## Network Information ### Mainnet * Chain ID: 22776 * RPC: * Explorer: ### Testnet (Makalu) * Chain ID: 212 * RPC: * Explorer: ## For Advanced Developers For protocol design details, contract specifications, and chain integration guides, see the [Developer Documentation](https://github.com/mapprotocol/docs/blob/master/developer-docs/README.md). ## Resources * [GitHub](https://github.com/mapprotocol) * [Website](https://mapprotocol.io) * [Discord](https://discord.gg/mapprotocol) * [Twitter](https://twitter.com/mapprotocol) ## Support * GitHub Issues: Report bugs and request features * Discord: Community support and discussions # Introduction MAP Protocol is an omnichain infrastructure for BTC, stablecoins, and tokenized assets swap. It provides the essential omnichain infrastructure for achieving interoperability among blockchain-based assets, storage, and computing across EVM and non-EVM chains. ## Key Features * **Security-Finality**: Guarantee blockchain-level security through an independent self-verification network formed by light clients on every public blockchain. * **All-Chain Coverage**: Embed heterogeneous chains' signing and hashing algorithm into the EVM layer of the MAP Relay Chain to ensure seamless communication between all chains. * **Instant Confirmation**: Inter-chain communication programs and on-chain smart contracts work together efficiently to ensure that speed is only related to each chain's block time. * **Minimum Cost**: MAP Protocol only charges the gas fee of MAP Relay Chain and other related chains with no additional cost. * **Developer-Ready**: Through MAP Omnichain Service (MOS) deployed on and between public chains, dApps can share the liquidity of MOS's Vaults on different chains. ## Unique Characteristics * **Omnichain Interoperability**: MAP Protocol allows point-to-point cross-chain interoperability between EVM and non-EVM chains. * **Security Enhanced by Bitcoin Network**: The MAP Protocol leverages the security mechanisms of the Bitcoin network to protect the relay chain, using light client self-verification features to secure cross-chain transactions. * **Distributed Trust**: MAP Protocol is decentralized, with no single entity in control, and all participants rely on the code for operations. * **Flexibility**: The protocol allows the integration of different types of blockchains, including those with different signature schemes, hash algorithms, and Merkle proofs. ## Roadmap ### **2026 Q4** * **Intent-based cross-chain mainnet launch:** Officially launch intent-based cross-chain services and open formal access for solver providers. * **Cross-chain data report:** Publish an annual report covering cross-chain volume, TVL growth, and user activity. * **Tokenized asset exploration:** Explore frameworks and roadmap planning for tokenized assets and RWA cross-chain support. ### **2026 Q3** * **Intent-based cross-chain development completed:** Finalize intent-based execution and expand solver participation in routing and liquidity support. * **Advanced LP tooling for solvers:** Launch solver-oriented LP APIs and tools, with incentive parameters adjustable via DAO governance. * **Governance execution milestone:** Conduct the first multi-dimensional DAO votes and publish a mid-year governance report. ### **2026 Q2** * **Intent-based cross-chain architecture design:** Complete the design of intent-based execution with solver mode and plan integrations for additional heterogeneous and popular chains. * **Liquidity as a Service (LaaS) upgrade:** Enhance LP incentives with dynamic APY adjustments and impermanent loss mitigation mechanisms. * **DAO governance expansion:** Extend MAPO governance to multi-dimensional voting covering fees, revenue distribution, and development priorities. ### **2026 Q1** * **Native BTC, DOGE, and XRP cross-chain mainnet launch:** Enable peer-to-peer cross-chain swaps across BTC, Dogecoin, and XRP using MPC-TSS execution and light-client verification. * **Public liquidity pools opened:** Open existing LP pools to the public with asset-specific APY parameters. ### 2025 Q4 * Launch a universal cross-chain standard specification MStack based on heterogeneous chains ### 2025 Q3 * M-Star Plan: MAP Protocol mainnet mechanism upgrade is officially launched and open source * Launch Multi-Party Engagement Mechanism of Liquidity Provider * Liquidity Provider incentive model upgrade ### 2025 Q2 * M-Star Plan: MAP Protocol mainnet mechanism upgrade test release * Introduce a new cross-chain verification node crossX to participate in the mainnet cross-chain multi-party security verification * Introduce a new incentive mechanism based on transaction fees ### 2025 Q1 * Officially launch cross-chain services for BTC, Dogecoin, and XRP * Officially launch cross-chain interoperability support for Solana and Ton ### 2024 Q4 * Launch and open-source Omnichain Development SDK V2 ### 2024 Q3 * The release of the 'Refactored Light Client Verification with ZK-Proof' module as open source * Launch Omnichain Development SDK V1 * Implement cross-chain interoperability support for Linea, Scroll, Solana, and Ton ### 2024 Q2 * Test the "Refactored Light Client Verification with ZK-Proof" module * Officially release cross-chain interoperability with Tron, Optimism, Mantle, Arbitrum, and zkSync Era ### 2024 Q1 * Officially release the extended cross-chain connections to Tron and Conflux * Test and open the MRC20 Omnichain issuance tool ### 2023 Q4 * Extend cross-chain connections to Tron and Conflux and conduct testing * Officially upgrade to become a Bitcoin layer 2 for peer-to-peer cross-chain interoperability * Release the upgraded official website and technical documentation * Launch a support plan for the BRC20 ecosystem ### 2023 Q3 * Extend cross-chain connectivity to more EVM-compatible and non-EVM-compatible chains * Release a variety of SDKs, from chain development to cross-chain components ### 2023 Q1 * Extend cross-chain connectivity to popular EVM-compatible chains * Extend MOS chain-wide services to support cross-chain data and NFT * Provide Omnichain scanning to show all cross-chain transactions and DApps ### 2022 Q4 * Extend cross-chain connectivity to Ethereum (PoS) * Extend cross-chain connectivity to mainstream EVM-compatible chains: BNB Chain, Polygon, etc. * Provide MOS SDK for developing personal MOS * Support cross-chain bridges and swap DApps ### 2022 Q3 * Extend cross-chain connectivity to Ethereum (EVM PoW) and Near (non-EVM PoS) * Launch MAP OmniChain Service, which supports cross-chain fungible tokens and provides a shared vault ### 2022 Q2 * Launch MAP relay chain with support for more signatures, hashing, mining and Merkle proof-of-computation precompiled contracts * Launch maposcan and PoS DApp * Provide SDK for interacting with the MAP relay chain ### 2022 Q1 * Support decentralised cross-chain for more chains * MOS supports cross-chain between Ethereum, Polygon, BNB chain and MAP Makalu * Invite more DeFi projects to join the Makalu test network ### 2021 Q3 * Launch MAP Relay Chain Makalu Test Network to start light client verification cross-chain between MAP Makalu and Ethereum * Start MAP Omnichain Service (MOS) for the test network * Start maintainer mining and invite users to participate in maintainer testing ### 2019 Q3 - 2020 Q4 * Release MAP Protocol version 1.0, enabling a cross-chain solution using light-client authentication ## Learn More * [Architecture Overview](/learn/architecture/overview) - Detailed three-layer architecture * [v1 Light Client Solution](/learn/architecture/v1-light-client) - Trustless verification approach * [v2 TSS Solution](/learn/architecture/v2-tss) - Threshold signature approach * [Tokenomics](/learn/tokenomics) - MAPO token details # Architecture # Overview ## Introduction MAP Protocol is a peer-to-peer cross-chain infrastructure enabling secure interoperability between heterogeneous blockchains. The architecture is built on a three-layer design that separates concerns and provides flexibility. ## Three-Layer Architecture ``` ┌─────────────────────────────────────────────────────────────────────────┐ │ Application Layer │ │ │ │ Cross-chain DApps │ Bridges │ Omnichain Services │ └─────────────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────────────┐ │ MOS (MAP Omnichain Service) Layer │ │ │ │ Message Passing │ Asset Transfer │ Verification │ └─────────────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────────────┐ │ Protocol Layer │ │ │ │ MAP Relay Chain │ Light Clients / TSS │ Maintainers │ └─────────────────────────────────────────────────────────────────────────┘ ``` ### Layer 1: Protocol Layer The foundation providing core cross-chain verification and consensus. | Component | Function | | --------------- | -------------------------------------------------- | | MAP Relay Chain | Central relay hub and verification center | | Light Clients | On-chain verification of other chains (v1) | | TSS Network | Threshold signature for decentralized custody (v2) | | Maintainers | Network participants maintaining cross-chain state | ### Layer 2: MOS Layer The service layer providing cross-chain capabilities to applications. | Component | Function | | ----------------- | --------------------------------------- | | Message Protocol | Standardized cross-chain message format | | Messenger/Relayer | Off-chain services delivering messages | | Vault/Gateway | Asset custody and verification | ### Layer 3: Application Layer Where developers build omnichain applications. **Examples:** * Cross-chain DEX * Omnichain NFT platforms * Multi-chain lending protocols * Cross-chain governance ## MAP Relay Chain MAP Relay Chain (Atlas) is an EVM-compatible blockchain at the core of the protocol. ### Key Features | Feature | Description | | ------------- | ---------------------------------------------- | | Consensus | Istanbul BFT with \~5 second blocks | | Compatibility | Fully EVM compatible | | Native Token | MAPO for gas and staking | | Finality | Instant finality with 2/3+ validator agreement | ### Functions 1. **Relay Hub**: Routes cross-chain messages 2. **Verification Center**: Hosts light clients and TSS contracts 3. **Governance**: Manages validators and protocol parameters ## Two Cross-Chain Solutions MAP Protocol offers two complementary solutions: ### v1: Light Client Solution Uses on-chain light clients for trustless verification. ``` Source Chain → Light Client → MAP Relay Chain → Light Client → Target Chain ``` **Best for:** * Maximum trustlessness * EVM-to-EVM communication * Message passing [Learn more about v1](/learn/architecture/v1-light-client) ### v2: TSS Solution Uses threshold signatures for decentralized custody. ``` Source Chain → Vault → Maintainer Network (TSS) → Gateway → Target Chain ``` **Best for:** * Bitcoin integration * Fast asset transfers * Lower gas costs [Learn more about v2](/learn/architecture/v2-tss) ## Network Participants | Role | Responsibility | | ---------------- | ---------------------------------------------------- | | **Validators** | Produce blocks on MAP Relay Chain | | **Maintainers** | Update light clients (v1) or participate in TSS (v2) | | **Messengers** | Relay cross-chain messages (v1) | | **Relayers** | Submit signatures to target chains (v2) | | **LP Providers** | Provide liquidity to Vaults (v2) | ## Supported Chains MAP Protocol supports various blockchain types: | Chain Type | Examples | v1 Support | v2 Support | | ---------- | ---------------------- | ---------- | ---------- | | EVM | Ethereum, BSC, Polygon | ✅ | ✅ | | Non-EVM | Near, Solana | ✅ | ✅ | | Bitcoin | BTC | ❌ | ✅ | ## Security Model ### Decentralization * No single point of failure * Distributed validation and signing * Permissionless participation (v1) or staked participation (v2) ### Cryptographic Security * Light client proofs based on source chain consensus * TSS threshold signatures with 2/3 fault tolerance * On-chain verification ### Economic Security * Staking requirements * Slashing for misbehavior * Incentive alignment ## Getting Started Depending on your role: | Role | Getting Started | | ---------- | --------------------------------------------------- | | User | Use cross-chain bridges built on MAP Protocol | | Developer | [Build cross-chain apps](/develop/overview) | | Validator | [Run a validator node](/validator/become-validator) | | Maintainer | [Run Compass-TSS](/compass-tss-crossx/overview) | # MAP Protocol 2.0 ## Overview Protocol 2.0 introduces TSS (Threshold Signature Scheme) based cross-chain infrastructure. It enables secure asset transfers across all chains, including Bitcoin, through decentralized threshold signatures. ## How It Works ``` Source Chain Maintainer Network Target Chain │ │ │ │ 1. User deposits │ │ │ to Vault │ │ │ │ │ │ 2. Maintainers │ │ │ observe ────────────►│ │ │ │ │ │ 3. TSS KeySign │ │ │ │ │ │ 4. Signature submitted │ │ ├──────────────────────────►│ │ │ │ │ │ 5. Gateway verifies │ │ │ and releases assets │ │ │ │ ``` ### Step-by-Step Process 1. **Deposit**: User deposits assets to Vault address on source chain 2. **Observe**: Maintainers detect and confirm the deposit 3. **Sign**: Maintainers collaboratively sign withdrawal transaction via TSS 4. **Submit**: Signature is submitted to target chain 5. **Release**: Gateway contract verifies signature and releases assets ## Key Components ### TSS (Threshold Signature Scheme) Cryptographic technology that allows multiple parties to jointly sign without any single party holding the full key. * **2/3 Threshold**: Requires 2/3 of Maintainers to sign * **No Single Point of Failure**: No one can sign alone * **Single Signature Output**: Looks like a normal signature on-chain ### Vault TSS-controlled address that holds cross-chain assets. * Managed by Maintainer network * No single entity controls the funds * Supports multiple chains including Bitcoin ### Gateway Smart contract on each chain for signature verification. * Verifies TSS signatures * Executes withdrawals * Handles TSS key updates ### Maintainer Network participant that observes events and participates in signing. * Must be a registered Validator * Participates in KeyGen and KeySign * Earns rewards for participation ## Security Model ### Threshold Security * **2/3 Byzantine Fault Tolerance**: System remains secure with up to 1/3 malicious nodes * **Distributed Custody**: Assets are never controlled by a single entity * **Slashing**: Malicious behavior is penalized ### Why It's Secure * **No Private Key Exposure**: Full key never exists in one place * **Decentralized Signing**: Multiple independent parties required * **Economic Security**: Maintainers stake assets at risk ## Supported Chains * **Bitcoin**: Full support via TSS Vault * **Ethereum & EVM Chains**: Gateway contract verification * **Solana**: secp256k1 verification via Gateway * **Any Chain**: Can support any chain that verifies signatures ## Advantages over v1 | Aspect | v1 (Light Client) | v2 (TSS) | | --------------- | ---------------------------- | ------------------------------ | | Bitcoin Support | ❌ | ✅ | | Gas Cost | Higher (proof verification) | Lower (signature verification) | | Implementation | Need light client per chain | Universal TSS | | Speed | Depends on light client sync | Fast threshold signing | ## Fusion with Light Client Protocol v2 can integrate light client verification for enhanced security: * TSS provides fast finality * Light client provides additional trustless verification * Best of both worlds ## Use Cases * **Bitcoin Cross-chain**: Bridge BTC to EVM chains * **Asset Transfers**: Fast and secure token transfers * **LP-based Liquidity**: Liquidity providers earn fees * **Multi-chain DeFi**: Access liquidity across chains ## Getting Started * **Become Maintainer**: See [Compass-TSS Guide](/compass-tss-crossx/overview) * **Provide Liquidity**: Deposit assets to Vault * **Use Cross-chain**: Interact with Gateway contracts ## Roles in v2 | Role | Responsibility | Reward | | ----------- | ----------------------------------- | ---------------- | | Validator | Block production on MAP Relay Chain | Block rewards | | Maintainer | TSS signing & observation | Cross-chain fees | | Relayer | Submit signatures to target chains | Transaction fees | | LP Provider | Provide liquidity to Vaults | Fee sharing | # MAP Protocol 1.0 ## Overview Protocol 1.0 is MAP Protocol's light client-based cross-chain solution. It enables trustless cross-chain communication by verifying transactions through on-chain light clients. ## How It Works ``` Source Chain MAP Relay Chain Target Chain │ │ │ │ 1. User initiates │ │ │ cross-chain tx │ │ │ │ │ │ 2. Maintainer updates │ │ │ light client ───────►│ │ │ │ │ │ 3. Messenger relays │ │ │ message + proof ─────┼──────────────────────────►│ │ │ │ │ │ 4. Light client verifies │ │ │ and executes │ │ │ │ ``` ### Step-by-Step Process 1. **Initiate**: User sends cross-chain transaction on source chain 2. **Update**: Maintainer updates light client with latest block headers 3. **Relay**: Messenger relays the message with Merkle proof to target chain 4. **Verify**: Target chain's light client verifies the proof and executes ## Key Components ### Light Client A smart contract that stores minimal blockchain state (block headers) to verify transactions from another chain. * Deployed on each connected chain * Verifies Merkle proofs * Provides trustless verification To validate the cryptographic proof for cross-chain messages, a trusted root is required. Normally the cryptographic proof is the existence Merkle proof of a specific value in a Merkle tree (e.g., the Merkle Patricia Tree in Ethereum). The trusted root is the Merkle root included in block headers. #### Light Client for PoW Chains For Nakamoto consensus-like chains (e.g., Ethereum), new block headers can be easily verified following the consensus rules such as hash links and accumulated work. If the network won't re-org more than n blocks, then a light client only needs to preserve n+1 newest block headers to verify new block headers autonomously. #### Light Client for PoS Chains For Proof-of-Stake and BFT based blockchains, blocks are signed by a group of selected staked validators. By verifying digital signatures, the validity of a block can be easily checked. The set of validators could change over time, but new validators are proved by the old set via signatures. With only validator set information (staked weight, public keys), a light client can check new block headers and update itself efficiently. #### Light Client of MAP Relay Chain MAP Relay Chain adopts PoS and IBFT consensus with aggregate BLS signature over BN256 curve. This allows verification of all validators' signatures to be reduced to verifying one aggregated signature with one aggregated public key. As precompile contracts for BN256 are widely supported by EVM-compatible blockchains, gas consumption for maintaining MAP Relay Chain's light client is minimized. ### Maintainer Off-chain service that keeps light clients updated. * Monitors source chain blocks * Submits block headers to light clients * Anyone can run a Maintainer ### Messenger Off-chain service that relays cross-chain messages. * Detects cross-chain events * Generates Merkle proofs * Delivers messages to target chains * Earns fees for successful delivery ### MOS (MAP Omnichain Service) The messaging layer that standardizes cross-chain communication. * Unified message format * Cross-chain event emission * Message verification interface ## Security Model ### Trust Assumptions * Source chain consensus is secure * At least one honest Maintainer keeps light client updated ### Why It's Secure * **Cryptographic Verification**: Light client verifies actual blockchain proofs * **No Trusted Third Party**: Verification is done on-chain * **Permissionless**: Anyone can participate as Maintainer or Messenger ## Supported Chains * Ethereum * BSC (BNB Smart Chain) * Polygon * Near Protocol * And more EVM-compatible chains ## Limitations * Requires light client implementation for each chain * Higher gas costs for proof verification * Cannot support Bitcoin (no smart contracts) ## Use Cases * Cross-chain messaging between DApps * Token transfers between EVM chains * Cross-chain governance voting * Omnichain NFT transfers ## Getting Started * **Build Cross-chain App**: See [Development Guide](/develop/cross-chain-application/overview) # Tokenomics MAPO is the native cryptocurrency of MAP Protocol. It is the digital money that opens the door for you to access the Bitcoin-level peer-to-peer omnichain network. ## Token Distribution ### DAO Governance 21% of MAP tokens are allocated to DAO. Any actions that will potentially affect every community member will need to be decided by MAP DAO. ## Role of MAPO ### Fueling MAP Protocol MAPO is the heart of MAP Protocol. When you send MAPO or use an app on MAP Protocol, you'll pay a fee in MAPO to use the MAP Protocol network. This fee serves as an incentive for a block producer to process and verify your activity on the network. Validators are like the gatekeepers of MAP Protocol—they check and ensure all the transactions are valid and accurate. They are randomly selected to verify new translations and add them to a blockchain. Validators will be rewarded with a small amount of MAPO for the work they do. ### Underpinning the Omnichain Financial System Moving beyond mere transactions, the omnichain community is crafting an all-encompassing financial network that is peer-to-peer and universally accessible. Currently, users can earn MAPO through staking. As MAP Protocol evolves and expands, forthcoming functionalities like borrowing and lending will be introduced, broadening the utility of MAPO. ### Growing Use Cases Because MAP Protocol is programmable, developers can shape MAPO in countless ways: * **Swap tokens with** [**ButterSwap**](https://www.butterswap.io/) — you can trade MAPO with tokens on multiple different chains. * **Earn interest by** [**staking**](https://staking.mapprotocol.io/) — stake MAPO and get rewarded. * **Get stablecoins** — access the world of cryptocurrencies with a steady, less volatile value. ## Getting MAPO Users can get MAPO from a centralized exchange or decentralized exchange. You can also become a validator or participate in staking to earn MAPO as a reward. ## Staking MAPO Staking is the process of participating in a proof-of-stake (PoS) consensus mechanism to support the operations of a blockchain network. Participants lock up a certain amount of cryptocurrency in a wallet to help validate transactions, secure the network, and produce new blocks. In return, participants usually receive additional tokens as rewards. In MAP Protocol, staking is the act of locking certain amounts of MAPO into the MAP Protocol Validator Pool. Both validators and users can participate in staking. * **Validators**: Once validators have configured their Validator node, they need to have 1 Million MAPO in their staking pool. * **Users**: Users can participate in staking by delegating their MAPO to the stake of a particular Validator; in this way, they help that Validator operate and earn a percentage of rewards based on their stake. ## Query MAPO Balance Users can query the MAPO balance of any account by inspecting the account's balance field, which shows MAPO holdings denominated in Gwei. [Maposcan](https://maposcan.io/) is the tool to inspect address balances via a web-based application. Account balances can also be queried using wallets or directly by making requests to nodes. ## Related Documentation * [Become a Validator](/validator/become-validator) * [Voting](/validator/vote) * [DAO Governance](/learn/dao) # DAO Governance MAP Protocol uses a formal **on-chain** governance mechanism to manage and upgrade the protocol such as for upgrading smart contracts, adding new stable currencies, or modifying the reserve target asset allocation. All changes must be agreed upon by **MAP holders**. A **quorum threshold** model is used to determine the number of votes needed for a proposal to pass. ## **Proposal Process** Changes are managed via the MAP Governance smart contract. This contract acts as an "owner" for making modifications to other protocol smart contracts. Such smart contracts are termed **governable**. The Governance contract itself is governable, and owned by itself. The change procedure happens in the following phases: * Proposal * Approval * Referendum * Execution ## Phases Overview Each proposal starts on the **Proposal Queue** where it may receive **upvotes** to move forward in the queue relative to other queued proposals. Proposal authors should work to find community members to upvote their proposal (proposers may also upvote their proposals). Up to **3 proposals** from the top of the queue are dequeued and promoted to the approval stage automatically per day. Any proposal that remains in the queue for **4 weeks** will expire. * **Approval** lasts **1 day (24 hours)**, during which the proposal must be approved by the Approver(s). Approved proposals are promoted to the Referendum stage. * **Referendum** lasts **5 days**, during which owners of Locked MAP vote yes or no on the proposal. Proposals that satisfy the necessary quorum are promoted to the execution phase. * **Execution** lasts up to **3 days**, during which anybody may trigger the execution of the proposal. ## Proposal Any user may submit a Proposal to the Governance smart contract, along with **50000 MAP** deposit. This deposit is required to avoid spam proposals, and is refunded to the proposer if the proposal reaches the Approval stage. A Proposal consists of a list of transactions, and a description URL where voters can get more information about the proposal. It is encouraged that this description URL points to a **MEP document** in the repository. Transaction data in the proposal includes the destination address, data, and value. If the proposal passes, the included transactions will be executed by the Governance contract. Submitted proposals are added to the queue of proposals. While a proposal is on this queue, voters may use their [Locked MAP](https://docs.mapprotocol.io/develop/map-relay-chain/how-to-vote) to upvote the proposal. Once per day the **top three proposals**, by weight of the Locked Map upvoting them, are dequeued and moved into the Approval phase. Note that if there are fewer than three proposals on the queue, all may be dequeued even if they have no upvotes. If a proposal has been on the queue for for more than **4 weeks**, it expires and the deposit is forfeited. ## Approval Every day the top three proposals at the head of the queue are pop off and move to the Approval phase. At this time, the original proposers are eligible to reclaim their Locked Map deposit. In this phase, the proposal needs to be approved by the Approver. The Approver is initially a 3 of 9 multi-signature address held by individuals selected by the Map Foundation, and will move to a DAO in the future. The Approval phase lasts **1 day** and if the proposal is not approved in this window, it is considered expired and does not move on to the “Referendum” phase. ## Referendum Once the Approval phase is over, approved proposals graduate to the referendum phase. Any user may vote **yes**, **no**, or **abstain** on these proposals. Their vote's weight is determined by the **weight of their Locked Map**. After the Referendum phase is over, which lasts **five days**, each proposal is marked as passed or failed as a function of the votes and the corresponding passing function parameters. In order for a proposal to pass, it must meet a minimum threshold for participation, and agreement: * **Participation** is the **minimum portion of Locked MAP** which must cast a vote for a proposal to pass. It exists to prevent proposals passing with very low participation. The participation requirement is calculated as a governable portion of the participation baseline, which is an exponential moving average of final participation in past governance proposals. * **Agreement** is the portion of votes cast that must be **"yes" votes** for a proposal to pass. Each contract and function can define a required level of agreement, and the required agreement for a proposal is the maximum requirement among its constituent transactions. ## **Execution** Proposals that graduate from the Referendum phase to the Execution phase may be **executed by anyone**, triggering a call operation code with the arguments defined in the proposal, originating from the Governance smart contract. Proposals expire from this phase after **three days**. # FAQ # 2.0 Contracts MAP Protocol v2 uses TSS (Threshold Signature Scheme) for cross-chain asset custody. This page lists the contract addresses and vault information for v2. > **Note**: Vault addresses may change with each epoch due to TSS key rotation. Use the [tss\_getVault](/api-and-sdk/json-rpc/tss-rpc) RPC method to query the latest vault information. ## TSS Contracts on MAP Relay Chain | Contract | Address | Description | | --------------- | -------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- | | TSS Manager | [0xf3Fa35B6e3753cFe88Da86c71B2283F75EB64BE9](https://explorer.mapprotocol.io/address/0xf3Fa35B6e3753cFe88Da86c71B2283F75EB64BE9) | Manages TSS key generation and signing | | Maintainers | [0xBfb6B7d0d5Fc120703F7B57CC18157d79a50a7e5](https://explorer.mapprotocol.io/address/0xBfb6B7d0d5Fc120703F7B57CC18157d79a50a7e5) | Maintainer registration and management | | Relay | [0x00004080D86e1077ce96E67C1B167fF105025307](https://explorer.mapprotocol.io/address/0x00004080D86e1077ce96E67C1B167fF105025307) | Cross-chain message relay | | Vault Manager | [0xdfC3F894Fb30F3E2f81608829968959DB65FD13b](https://explorer.mapprotocol.io/address/0xdfC3F894Fb30F3E2f81608829968959DB65FD13b) | Manages cross-chain vault operations | | Gas Service | [0x1De9C47ae0074F347d9fF6bfA39CDd3389322eAD](https://explorer.mapprotocol.io/address/0x1De9C47ae0074F347d9fF6bfA39CDd3389322eAD) | Cross-chain gas fee management | | Registry | [0xf2C3a9b547875C48Ba8598C4973BAC71eDc4C34c](https://explorer.mapprotocol.io/address/0xf2C3a9b547875C48Ba8598C4973BAC71eDc4C34c) | Contract registry | | View Controller | [0x8c98bA0a11Cbb0DB3C52e4CD91B0844B39BC1F11](https://explorer.mapprotocol.io/address/0x8c98bA0a11Cbb0DB3C52e4CD91B0844B39BC1F11) | View functions for querying state | ## EVM Gateway Addresses | Contract | Address | Description | | -------- | ------------------------------------------ | ------------------- | | Gateway | 0x00004080D86e1077ce96E67C1B167fF105025307 | Cross-chain gateway | ## Vault Addresses ### MAP Protocol BTC Vault | Epoch | Address | Status | | ----- | -------------------------------------------- | ------ | | 0 | `bc1q86m6d8fmlvan8r9pypd4p592xtcpfkn6ezxj3t` | active | ### MAP Protocol DOGE Vault | Epoch | Address | Status | | ----- | ------------- | ------ | | 0 | `Coming soon` | - | ## Query Vault Information To get the latest vault addresses programmatically, use the `tss_getVault` RPC method: ```shell # Query latest vault curl -X POST -H "Content-Type: application/json" \ --data '{"jsonrpc":"2.0","method":"tss_getVault","params":["latest"],"id":1}' \ https://rpc.maplabs.io # Query by epoch curl -X POST -H "Content-Type: application/json" \ --data '{"jsonrpc":"2.0","method":"tss_getVault","params":["0x1"],"id":1}' \ https://rpc.maplabs.io ``` See [TSS RPC API](/api-and-sdk/json-rpc/tss-rpc) for more details. # 1.0 Contracts Below is MAP Protocol's latest chain connectivity progress and the corresponding contract addresses. ### Ethereum * `Light-client on MAPO`\ `Source Code`: [Ethereum2.0 POS light client](https://github.com/mapprotocol/map-contracts/blob/main/lightclients/eth2/README.md)\ `Address`: [0x6859b2aE7CE9fb0c4FAA71798aC5498B41B42D7A](https://maposcan.io/address/0x6859b2aE7CE9fb0c4FAA71798aC5498B41B42D7A) * `Light-client on Chain`\ `Source Code`: [MAP Relay Chain light client deployed on EVM chains](https://github.com/mapprotocol/map-contracts/blob/main/mapclients/eth/README.md)\ `Address`: [0x624E6F327c4F91F1Fa6285711245c215de264d49](https://etherscan.io/address/0x624E6F327c4F91F1Fa6285711245c215de264d49) * `MOS`\ `Source Code`: [MOS Message Contracts](https://github.com/mapprotocol/mapo-service-contracts/blob/main/evm/README.md)\ `Address`: [0x8C3cCc219721B206DA4A2070fD96E4911a48CB4f](https://etherscan.io/address/0x8C3cCc219721B206DA4A2070fD96E4911a48CB4f) * `Chain ID`: `1` * `Status`:`Completed` `MAP Protocol` <-> `Ethereum` ### BNB Smart Chain * `Light-client on MAPO`\ `Source Code`: [BNB Smart Chain light client](https://github.com/mapprotocol/map-contracts/blob/main/lightclients/bsc/README.md)\ `Address`: [0x14843295C38EaC604dEDe0eDb77e08B460D093D8](https://maposcan.io/address/0x14843295C38EaC604dEDe0eDb77e08B460D093D8) * `Light-client on Chain`\ `Source Code`: [MAP Relay Chain light client deployed on EVM chains](https://github.com/mapprotocol/map-contracts/blob/main/mapclients/eth/README.md)\ `Address`: [0x624E6F327c4F91F1Fa6285711245c215de264d49](https://bscscan.com/address/0x624E6F327c4F91F1Fa6285711245c215de264d49) * `MOS`\ `Source Code`: [MOS Message Contracts](https://github.com/mapprotocol/mapo-service-contracts/blob/main/evm/README.md)\ `Address`: [0x8C3cCc219721B206DA4A2070fD96E4911a48CB4f](https://github.com/mapprotocol/docs/blob/master/network/0x8C3cCc219721B206DA4A2070fD96E4911a48CB4f/README.md) * `Chain ID`: `56` * `Status`: `Completed` `MAP Protocol` <-> `BNB Smart Chain` ### Polygon Mainnet * `Light-client on MAPO`\ `Source Code`: [Polygon Mainnet light client](https://github.com/mapprotocol/map-contracts/blob/main/lightclients/matic/README.md)\ `Address`: [0x1D621078676D7bdd75FC7F5ebbaBadDC9a65E3c5](https://maposcan.io/address/0x1D621078676D7bdd75FC7F5ebbaBadDC9a65E3c5) * `Light-client on Chain`\ `Source Code`: [MAP Relay Chain light client deployed on EVM chains](https://github.com/mapprotocol/map-contracts/blob/main/mapclients/eth/README.md)\ `Address`: [0x624E6F327c4F91F1Fa6285711245c215de264d49](https://github.com/mapprotocol/docs/blob/master/network/0x624E6F327c4F91F1Fa6285711245c215de264d49/README.md) * `MOS`\ `Source Code`: [MOS Message Contracts](https://github.com/mapprotocol/mapo-service-contracts/blob/main/evm/README.md)\ `Address`: [0x8C3cCc219721B206DA4A2070fD96E4911a48CB4f](https://polygonscan.com/address/0x8C3cCc219721B206DA4A2070fD96E4911a48CB4f) * `Chain ID`: `137` * `Status`: `Completed` `MAP Protocol` <-> `Polygon Mainnet` ### NEAR * `Light-client on MAPO`\ `Source Code`: [NEAR light client](https://github.com/mapprotocol/map-contracts/blob/main/lightclients/near/README.md)\ `Address`: [0x4464fA3A804b8a44a0aD212eD23155a08f336B34](https://maposcan.io/address/0x4464fA3A804b8a44a0aD212eD23155a08f336B34) * `Light-client on Chain`\ `Source Code`: [MAP light client on NEAR](https://github.com/mapprotocol/map-contracts/blob/main/mapclients/near/README.md)\ `Address`: [4WUmfmcRYbLfAJyBzXnYPP69iSRuVQ81cJAhZas6Cw1i](https://explorer.near.org/accounts/client2.cfac.mapprotocol.near) * `MOS`\ `Source Code`: [MAP Omnichain Service](https://github.com/butternetwork/butter-mos-contracts/tree/master/near)\ `Address`: [J1KQdJSNUyBZGwsW3oZ8nFUqv2iLxb3Y8X9DTTJjxJgr](https://explorer.near.org/accounts/mosv21.mfac.butternetwork.near) * `Chain ID`: `5566818579631833088` * `Status`: `Completed` `MAP Protocol` <-> `NEAR` ### Arbitrum One * `Light-client on MAPO`\ `Source Code`: `N/A`\ `Address`:`N/A` * `Light-client on Chain`\ `Source Code`: [MAP Relay Chain light client delpoyed on EVM chains](https://github.com/mapprotocol/map-contracts/blob/main/mapclients/eth/README.md)\ `Address`: [0x624E6F327c4F91F1Fa6285711245c215de264d49](https://arbiscan.io/address/0x624e6f327c4f91f1fa6285711245c215de264d49) * `MOS`\ `Source Code`: [MOS Message Contracts](https://github.com/mapprotocol/mapo-service-contracts/blob/main/evm/README.md)\ `Address`: [0x8C3cCc219721B206DA4A2070fD96E4911a48CB4f](https://arbiscan.io/address/0x8c3ccc219721b206da4a2070fd96e4911a48cb4f) * `Chain ID`: `42161` * `Status`: `Completed` `MAP Protocol` --> `Arbitrum One` ### Klaytn * `Light-client on MAPO`\ `Source Code`: [Klaytn light client](https://github.com/mapprotocol/map-contracts/blob/main/lightclients/klaytn/README.md)\ `Address`:[0x91a14b93e4d588879dAE94E2EeE5E1d88b879D81](https://maposcan.io/address/0x91a14b93e4d588879dAE94E2EeE5E1d88b879D81) * `Light-client on Chain`\ `Source Code`: [MAP Relay Chain light client delpoyed on EVM chains](https://github.com/mapprotocol/map-contracts/blob/main/mapclients/eth/README.md)\ `Address`: [0x624E6F327c4F91F1Fa6285711245c215de264d49](https://scope.klaytn.com/account/0x624E6F327c4F91F1Fa6285711245c215de264d49?tabId=txList) * `MOS`\ `Source Code`: [MOS Message Contracts](https://github.com/mapprotocol/mapo-service-contracts/blob/main/evm/README.md)\ `Address`: [0x8C3cCc219721B206DA4A2070fD96E4911a48CB4f](https://scope.klaytn.com/account/0x8c3ccc219721b206da4a2070fd96e4911a48cb4f?tabId=txList) * `Chain ID`: `8721` * `Status`: `Completed` `MAP Protocol` <-> `Klaytn` ### Conflux * `Light-client on MAPO`\ `Source Code`: [Conflux light client](https://github.com/mapprotocol/map-contracts/tree/main/lightclients/conflux)\ `Address`:[0x3E357098bbBeD2810c9a37FDfB5816067890304a](https://maposcan.io/address/0x3E357098bbBeD2810c9a37FDfB5816067890304a) * `Light-client on Chain`\ `Source Code`: [MAP Relay Chain light client delpoyed on EVM chains](https://github.com/mapprotocol/map-contracts/blob/main/mapclients/eth/README.md)\ `Address`: [0x624E6F327c4F91F1Fa6285711245c215de264d49](https://evm.confluxscan.io/address/0x624e6f327c4f91f1fa6285711245c215de264d49) * `MOS`\ `Source Code`: [MOS Message Contracts](https://github.com/mapprotocol/mapo-service-contracts/blob/main/evm/README.md)\ `Address`: [0xfeb2b97e4efce787c08086dc16ab69e063911380](https://evm.confluxscan.io/address/0xfeb2b97e4efce787c08086dc16ab69e063911380) * `Chain ID`:1030 * `Status`: `Completed` `MAP Protocol` <-> `Conflux` ### Tron * `OracleNode on MAPO`\ `Address`:[0x17ecd177019CDD72125659af33446758d7390A42](https://maposcan.io/address/0x17ecd177019CDD72125659af33446758d7390A42) * `OracleNode on Chain`\ `Address`: [TCgts2dcdEszFdHnp3D9iKqxGqNrpTYSjQ](https://tronscan.org/#/contract/TCgts2dcdEszFdHnp3D9iKqxGqNrpTYSjQ/code) * `Chain ID`: `728126428` * `Status`: `MAP Protocol` <--> `Tron` ### PlatON Mainnet * `Light-client on MAPO`\ `Source Code`: [PlatON light client](https://github.com/mapprotocol/map-contracts/blob/main/lightclients/platon/README.md)\ `Address`:`Coming soon` * `Light-client on Chain`\ `Source Code`: [MAP Relay Chain light client deployed on EVM chains](https://github.com/mapprotocol/map-contracts/blob/main/mapclients/eth/README.md)\ `Address`: `Coming soon` * `MOS`\ `Source Code`: [MOS Message Contracts](https://github.com/mapprotocol/mapo-service-contracts/blob/main/evm/README.md)\ `Address`: `Coming soon` * `Chain ID`: `210425` * `Status`: `Coming soon` ### OP Mainnet * `OracleNode on MAPO`\ `Address`:[0x0EBDBB2b94953C1375dbA3C063682a094b4d9780](https://maposcan.io/address/0x0EBDBB2b94953C1375dbA3C063682a094b4d9780) * `Light-client on Chain`\ `Source Code`: [MAP Relay Chain light client deployed on EVM chains](https://github.com/mapprotocol/map-contracts/blob/main/mapclients/eth/README.md)\ `Address`: [0x0001805c0b57dbd48b5c5c26e237a135ddc678ae](https://optimism.blockscout.com/address/0x0001805c0b57dbd48b5c5c26e237a135ddc678ae) * `MOS`\ `Source Code`: [MOS Message Contracts](https://github.com/mapprotocol/mapo-service-contracts/blob/main/evm/README.md)\ `Address`:[0x8C3cCc219721B206DA4A2070fD96E4911a48CB4f](https://optimism.blockscout.com/address/0x8C3cCc219721B206DA4A2070fD96E4911a48CB4f) * `Chain ID`: `10` * `Status`: `MAP Protocol` --> `OP Mainnet` ### Base * `OracleNode on MAPO`\ `Address`:[0x10c195Ab0FF99b6711FE8be65469E460d1d4478f](https://maposcan.io/address/0x10c195Ab0FF99b6711FE8be65469E460d1d4478f) * `Light-client on Chain`\ `Source Code`: [MAP Relay Chain light client deployed on EVM chains](https://github.com/mapprotocol/map-contracts/blob/main/mapclients/eth/README.md)\ `Address`: [0x0001805c0b57dbd48b5c5c26e237a135ddc678ae](https://basescan.org/address/0x0001805c0b57dbd48b5c5c26e237a135ddc678ae) * `MOS`\ `Source Code`: [MOS Message Contracts](https://github.com/mapprotocol/mapo-service-contracts/blob/main/evm/README.md)\ `Address`: [0xfeB2b97e4Efce787c08086dC16Ab69E063911380](https://basescan.org/address/0xfeB2b97e4Efce787c08086dC16Ab69E063911380) * `Chain ID`: `8453` * `Status`: `MAP Protocol` <--> `Base` ### Linea * `OracleNode on MAPO`\ `Address`:[0x667E45a64F7c0e5Ba897C0c072D70cE6B2F73701](https://maposcan.io/address/0x667E45a64F7c0e5Ba897C0c072D70cE6B2F73701) * `Light-client on Chain`\ `Source Code`: [MAP Relay Chain light client deployed on EVM chains](https://github.com/mapprotocol/map-contracts/blob/main/mapclients/eth/README.md)\ `Address`: [0x0001805c0b57dbd48b5c5c26e237a135ddc678ae](https://explorer.linea.build/address/0x0001805c0b57dbd48b5c5c26e237a135ddc678ae) * `MOS`: `0xfeB2b97e4Efce787c08086dC16Ab69E063911380` * `Chain ID`: `59144` * `Status`: `MAP Protocol` <--> `Linea` ### zkSync * `OracleNode on MAPO`\ `Address`:[0x371717D5ea21f73FEf2a30537571e05f62460CcE](https://maposcan.io/address/0x371717D5ea21f73FEf2a30537571e05f62460CcE) * `OracleNode on Chain`\ `Address`: [0xA9bDC7D5738d88A6F082b2580A4a425697Da9E5D](https://explorer.zksync.io/address/0xA9bDC7D5738d88A6F082b2580A4a425697Da9E5D) * `Chain ID`: `324` * `Status`: `MAP Protocol` <--> `zkSync` ### Merlin * `OracleNode on MAPO`\ `Address`:[0xe656bd52F9953b2688881644e3858fBE4c024627](https://maposcan.io/address/0xe656bd52F9953b2688881644e3858fBE4c024627) * `OracleNode on Chain`\ `Address`: [0x1cbB3ACbD5f8817c75A83A62135A8CF2F86EEd48](https://scan.merlinchain.io/address/0x1cbB3ACbD5f8817c75A83A62135A8CF2F86EEd48) * `Chain ID`: `4200` * `Status`: `MAP Protocol` <--> `Merlin` ### Blast * `OracleNode on MAPO`\ `Address`:[0x4030d0e5F10c859268Cd60C18e6DD3F645eea83C](https://maposcan.io/address/0x4030d0e5F10c859268Cd60C18e6DD3F645eea83C) * `Light-client on Chain`\ `Address`: [0x0001805c0b57dbd48b5c5c26e237a135ddc678ae](https://blastscan.io/address/0x0001805c0b57dbd48b5c5c26e237a135ddc678ae) * `Chain ID`: `81457` * `Status`: `MAP Protocol` <--> `Blast` ### Scroll * `OracleNode on MAPO`\ `Address`:[0xe1E918C2157eC00a0b83280C738d3Bb08f172B8B](https://maposcan.io/address/0xe1E918C2157eC00a0b83280C738d3Bb08f172B8B) * `Light-client on Chain`\ `Address`: [0x0001805c0b57dbd48b5c5c26e237a135ddc678ae](https://scrollscan.com/address/0x0001805c0b57dbd48b5c5c26e237a135ddc678ae) * `Chain ID`: `534352` * `Status`: `MAP Protocol` <--> `Scroll` ### AILayer * `OracleNode on MAPO`\ `Address`:[0xB8560Ed626De95Bad25CcD34264F29682FE677AB](https://maposcan.io/address/0xB8560Ed626De95Bad25CcD34264F29682FE677AB) * `OracleNode on Chain`\ `Address`: [0x6951B909A71cd4189aA21aEfD38dFc3dCee90001](https://mainnet-explorer.ailayer.xyz/address/0x6951B909A71cd4189aA21aEfD38dFc3dCee90001) * `Chain ID`: `2649` * `Status`: `MAP Protocol` <--> `AINN` ### Mantle * `OracleNode on MAPO`\ `Address`:[0x5ACa31Fe7314a4c323E83C0F58936Fc40fB47a80](https://maposcan.io/address/0x5ACa31Fe7314a4c323E83C0F58936Fc40fB47a80) * `Light-client on Chain`\ `Address`: [0x0001805c0b57dbd48b5c5c26e237a135ddc678ae](https://mantlescan.info/address/0x0001805c0b57dbd48b5c5c26e237a135ddc678ae) * `Chain ID`: `5000` * `Status`: `MAP Protocol` <--> `Mantle` ### Ton Testnet * `MOS`\ `Source Code`: [MOS Message Contracts](https://github.com/mapprotocol/ton-router-contracts)\ `Address`: [EQDyD3ICi9YkGdIf19dJHoq-70Ng9lWY9lCbIVM-tfi\_yp1v](https://testnet.tonscan.org/address/EQDyD3ICi9YkGdIf19dJHoq-70Ng9lWY9lCbIVM-tfi_yp1v) * `Chain ID`: `1360104473493506` * `Status`: `Completed` `MAP Protocol` <-> `Ton` ### Solana * `Planning` ## Related Documentation * [Cross-chain Application Development](broken://pages/JEyUgtzsHVjT5b48nGCe) * [MOS Overview](broken://pages/wxAexKDKvUXEjsd6lcXu) # MAP Relay Chain MAP Relay Chain (Atlas) is an EVM-compatible blockchain at the core of MAP Protocol. ## Mainnet | Property | Value | | --------------- | --------------------------------- | | Network Name | MAP Mainnet | | Chain ID | `22776` | | Currency Symbol | MAPO | | RPC URL | `https://rpc.maplabs.io` | | WebSocket | `wss://wss.maplabs.io` | | Explorer | | | Explorer (alt) | | ### Add to Wallet ```json { "chainId": "0x58f8", "chainName": "MAP Mainnet", "nativeCurrency": { "name": "MAPO", "symbol": "MAPO", "decimals": 18 }, "rpcUrls": ["https://rpc.maplabs.io"], "blockExplorerUrls": ["https://explorer.mapprotocol.io"] } ``` ## Testnet (Makalu) | Property | Value | | --------------- | -------------------------------- | | Network Name | MAP Makalu | | Chain ID | `212` | | Currency Symbol | MAPO | | RPC URL | `https://testnet-rpc.maplabs.io` | | WebSocket | `wss://testnet-wss.maplabs.io` | | Explorer | | | Faucet | | ### Add to Wallet ```json { "chainId": "0xd4", "chainName": "MAP Makalu", "nativeCurrency": { "name": "MAPO", "symbol": "MAPO", "decimals": 18 }, "rpcUrls": ["https://testnet-rpc.maplabs.io"], "blockExplorerUrls": ["https://testnet.maposcan.io"] } ``` ## Network Specifications | Specification | Value | | ----------------- | ---------------------- | | Consensus | Istanbul BFT (IBFT) | | Block Time | \~5 seconds | | Finality | Instant (single block) | | EVM Compatibility | Full | | Gas Token | MAPO | # Become a Validator ## Overview MAP Protocol uses Proof of Stake (POS) consensus. Validators secure the network by: * Staking at least 1,000,000 MAP tokens * Running a validator node to produce and validate blocks * Earning rewards based on votes received ## Prerequisites ### Hardware Requirements | Component | Requirement | | --------- | -------------------------------------- | | CPU | Quad core 2.5 GHz (64-bit) | | RAM | 16 GB | | Storage | 256 GB SSD + secondary HDD | | Network | 100 Mb/s, fiber connection recommended | ### Software Requirements * Go 1.14 or later * Git * C compiler ### MAP Tokens Your account needs at least **1,000,000 MAP** for staking. ## Build Tools ```bash # Clone repository git clone https://github.com/mapprotocol/atlas.git cd atlas # Build atlas and marker make atlas make marker ``` ## Prepare Accounts You need two accounts: | Account | Purpose | File | | ------- | ------------------------- | ------------ | | Account | Staking, receives rewards | account.json | | Signer | Signs blocks | signer.json | ### Generate Keystore ```bash ./atlas account new --keystore ./datadir/keystore ``` Or import existing private key: ```bash ./atlas --dataDir "./data" console > web3.personal.importRawKey("your_private_key", "your_password") ``` ## Start Validator Node ```bash ./atlas --datadir ./node \ --syncmode "full" \ --port 30321 \ --v5disc \ --mine \ --miner.validator \ --unlock ``` Wait for the node to sync with the network. ## Register as Validator ### Step 1: Create Account Register your account with the management contract: ```bash ./marker createAccount \ --rpcaddr http://127.0.0.1:7445 \ --keystore ./account.json \ --name "validator" ``` ### Step 2: Authorize Signer Authorize the signer address to sign blocks on behalf of your account: ```bash ./marker authorizeValidatorSigner \ --rpcaddr http://127.0.0.1:7445 \ --keystore ./account.json \ --signerPriv ``` ### Step 3: Lock MAP Lock at least 1,000,000 MAP: ```bash ./marker lockedMAP \ --rpcaddr http://127.0.0.1:7445 \ --keystore ./account.json \ --lockedNum 1000000 ``` ### Step 4: Register Validator ```bash ./marker register \ --rpcaddr http://127.0.0.1:7445 \ --keystore ./account.json \ --signerPriv \ --commission 150000 ``` ### Step 5: Vote for Yourself Validators need votes to be elected. Vote for yourself: ```bash ./marker vote \ --rpcaddr http://127.0.0.1:7445 \ --keystore ./account.json \ --target \ --voteNum 1000000 ``` ## Verify Registration Check if you're registered as a validator: ```bash ./marker getTotalVotesForEligibleValidators --rpcaddr http://127.0.0.1:7445 ``` Check if you're in the active validator set (after next epoch): ```bash curl -X POST -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","method":"istanbul_getValidators","params":[],"id":1}' \ http://127.0.0.1:7445 ``` *** ## Advanced: Signature Separation For enhanced security, you can separate the signing process from registration. This keeps your signer's private key more secure. ### Generate ECDSA Signature ```bash ./marker makeECDSASignatureFromSigner \ --target \ --signerPriv ``` Save the output signature (e.g., `0x59dff185...32f0d700`). ### Authorize by Signature ```bash ./marker authorizeValidatorSignerBySignature \ --rpcaddr http://127.0.0.1:7445 \ --keystore ./account.json \ --signer \ --signature ``` ### Generate Signer Proof ```bash ./marker generateSignerProof \ --validator \ --signerPriv ``` Save the output proof (e.g., `0xf90149b8...0e56f0ab1`). ### Register by Proof ```bash ./marker registerByProof \ --rpcaddr http://127.0.0.1:7445 \ --keystore ./account.json \ --proof \ --commission 150000 ``` ## Related * [Voting & Withdrawal](/validator/vote) * [Marker Tool](/validator/marker-tool/overview) * [Network Info](/network/relay-chain) # Voting ## Introduction You can use your validator account to vote for yourself, or let other validators or voters vote for you. Below we demonstrate voting for yourself using your own validator account, as this is the easiest approach. The number of votes corresponds 1:1 with the number of MAP you pledge. Before voting, you must first become a validator. If you are not a validator, please see [Become a Validator](/validator/become-validator). ## Step 1: Create Account If you have done this step before, please skip it. In this step, you need to transfer your identification information to the corresponding management contract, which will manage your account, keys, and metadata. The purpose of this step is to keep your locked `MAP` more secure by authorizing alternative keys to be used for signing attestations, voting, and validating. By doing so, you can continue to participate in the protocol while keeping the key with access to your locked `MAP` in storage. You need `createAccount` command to perform the above operations. For more details about `createAccount` command please see [Marker Common Commands](/validator/marker-tool/common#createaccount). Example: ```shell ./marker createAccount --rpcaddr http://127.0.0.1:7445 --name "validator" --keystore ./UTC--2022-07-01T04-02-22.985282926Z--078f684c7d3bf78bdbe8bef93e56998442dc8099 INFO [07-01|05:54:37.048] Create account func=createAccount address=0x078F684c7d3bf78BDbe8bEf93E56998442dc8099 name=validator INFO [07-01|05:54:37.048] === create Account === INFO [07-01|05:54:37.056] TxInfo func=sendContractTransaction TX data nonce =0 gasLimit =4,500,000 gasPrice =101,000,000,000 chainID =29088 INFO [07-01|05:54:37.057] Please waiting func=getResult txHash =0xbd9603b438fa5b98b894431111c6298605d47a12c8b508458482aa865f2d707c INFO [07-01|05:54:42.082] Transaction Success func=queryTx block Number=360,085 INFO [07-01|05:54:42.083] === setName name === INFO [07-01|05:54:42.090] TxInfo func=sendContractTransaction TX data nonce =1 gasLimit =4,500,000 gasPrice =101,000,000,000 chainID =29088 INFO [07-01|05:54:42.091] Please waiting func=getResult txHash =0x8c68f99e1c7216a12d3e2ea12d293d150d94c2e0d0136504860e0f86c87cf77c INFO [07-01|05:54:47.117] Transaction Success func=queryTx block Number=360,086 INFO [07-01|05:54:47.117] === setAccountDataEncryptionKey === INFO [07-01|05:54:47.125] TxInfo func=sendContractTransaction TX data nonce =2 gasLimit =4,500,000 gasPrice =101,000,000,000 chainID =29088 INFO [07-01|05:54:47.126] Please waiting func=getResult txHash =0xed401e84bf7759f2559ba8d97bcee09bb2128cbfb798f3751a427a640944f60d INFO [07-01|05:54:52.152] Transaction Success func=queryTx block Number=360,087 ``` ## Step 2: Lock MAP If you have locked enough `MAP` for voting, please skip this step. The purpose of this step is to deduct the part of the corresponding vote from the money you locked to the validator you want to vote. You need to lock your `MAP` into the corresponding management contract in advance. You need `lockedMAP` command to perform the above operations. For more details about `lockedMAP` command please see [Marker Common Commands](/validator/marker-tool/common#lockedmap). Example: ```shell ./marker lockedMAP --rpcaddr http://127.0.0.1:7445 --keystore ./UTC--2022-07-01T04-02-22.985282926Z--078f684c7d3bf78bdbe8bef93e56998442dc8099 --lockedNum 1000000 INFO [07-01|06:12:45.068] === Lock gold === INFO [07-01|06:12:45.069] Lock gold amount=1000000000000000000000000 INFO [07-01|06:12:45.084] TxInfo func=sendContractTransaction TX data nonce =3 gasLimit =4,500,000 gasPrice =101,000,000,000 chainID =29088 INFO [07-01|06:12:45.085] Please waiting func=getResult txHash =0x6f8c9ea1d4481ba26af144d4cf04b5275750f51b899a898e6c57a798fdbcceab INFO [07-01|06:12:47.095] Transaction Success func=queryTx block Number=360,302 ``` ## Step 3: Vote When you get to this step, you can vote for your favorite validator. You can use the `getTotalVotesForEligibleValidators` subcommand to view all current validators and their votes. Example: ```shell ./marker getTotalVotesForEligibleValidators --rpcaddr http://127.0.0.1:7445 --keystore ./UTC--2022-07-01T04-02-22.985282926Z--078f684c7d3bf78bdbe8bef93e56998442dc8099 INFO [07-06|06:04:01.431] === getTotalVotesForEligibleValidators === admin=0x078F684c7d3bf78BDbe8bEf93E56998442dc8099 INFO [07-06|06:04:01.434] Validator: addr=0x36b77597430cc2C0DD090c67f77f67Fc28195b5D vote amount=1,056,438,467,567,624,843,076,833 INFO [07-06|06:04:01.434] Validator: addr=0x7cC3e34C2075D96ef69bF6445a234F6C5E244073 vote amount=1,056,438,467,567,624,843,076,833 INFO [07-06|06:04:01.434] Validator: addr=0x3B778BB4F460956E313Ba92484Eb84603A86a625 vote amount=1,046,438,467,567,624,843,076,833 INFO [07-06|06:04:01.434] Validator: addr=0x19b375EBB9eE1B21A592A933c6383Df49380046D vote amount=1,046,425,233,310,919,400,227,838 INFO [07-06|06:04:01.434] Validator: addr=0x19C560de95c222Ac4B0ad3093D66EF1Fe75640f4 vote amount=134,664,371,097,943,842,325,525 INFO [07-06|06:04:01.434] Validator: addr=0x078F684c7d3bf78BDbe8bEf93E56998442dc8099 vote amount=103,060,000,000,004,450,909,077 ``` Vote example: ```shell ./marker vote --rpcaddr http://127.0.0.1:7445 --keystore ./UTC--2022-07-01T04-02-22.985282926Z--078f684c7d3bf78bdbe8bef93e56998442dc8099 --target "0x078F684c7d3bf78BDbe8bEf93E56998442dc8099" --voteNum 100000 INFO [07-06|06:05:31.454] === vote Validator === admin=0x078F684c7d3bf78BDbe8bEf93E56998442dc8099 voteTargetValidator=0x078F684c7d3bf78BDbe8bEf93E56998442dc8099 vote MAP Num=100000 INFO [07-06|06:05:31.478] TxInfo func=sendContractTransaction TX data nonce =10 gasLimit =4,500,000 gasPrice =101,000,000,000 chainID =29088 INFO [07-06|06:05:31.479] Please waiting func=getResult txHash =0x8f8724be7e7eb2ffb0034dee92dbe57fbd2534b057ba43adcc7c6be5b20b9ffa INFO [07-06|06:05:32.083] Transaction Success func=queryTx block Number=446,614 ``` When you finish voting, your votes will be in pending status. At the end of epoch block, the elected validator will automatically activate the votes in pending related to them. You can also use `activate` command to activate your votes yourself. This activate operation needs to be greater than your pending vote epoch. For more details about vote commands, see [Marker Vote Commands](/validator/marker-tool/vote). ## Additional Notes ### When You Vote for a Validator Who Is Not Yet Elected Your pending votes will not be automatically activated until the validator is elected. Once the validator is elected, they will automatically activate your votes at the next epoch. If you don't activate your vote manually, your votes will get benefits after the second epoch when the validator is elected. # Withdrawal ### Validator withdraw #### Query the number of locked MAP You can query how many MAP are locked by doing the following. ```shell ./marker getAccountTotalLockedGold --rpcaddr http://127.0.0.1:7445 --target 0x73bc690093b9dd0400c91886184a60cc127b2c33 INFO [08-02|16:50:22.331] === getAccountTotalLockedGold === admin=0x0000000000000000000000000000000000000000 target=0x73bC690093b9dD0400c91886184A60cC127b2c33 INFO [08-02|16:50:22.333] result lockedGold=1,000,000,000,000,000,000,000,000 ``` #### Unregister validator This step is not required, but if your locked balance is less than 10000000 after unlocking, please unregister first. unregister operation can only be performed 60 days after registration as a validator, and unregister needs to wait for the last block of the current epoch to take effect. ```shell ./marker deregister --rpcaddr http://127.0.0.1:7445 --keystore /Users/alex/data/atlas-1/keystore/UTC--2022-06-14T05-46-17.312327000Z--73bc690093b9dd0400c91886184a60cc127b2c33 INFO [08-02|16:52:40.688] === deregisterValidator === INFO [08-02|16:52:40.701] TxInfo func=sendContractTransaction TX data nonce =10 gasLimit =4,500,000 gasPrice =101,000,000,000 chainID =22776 INFO [08-02|16:52:40.702] Please waiting func=getResult txHash =0xb904cae42c8e9d5481b0023b367a35a5be37802c1a9f7a9ff55835cd72044def INFO [08-02|16:52:41.107] Transaction Success func=queryTx block Number=1211 ``` #### Unlock MAP This step is used to convert the state of your MAP from locked to unlocked ```shell ./marker unlockMap --rpcaddr http://127.0.0.1:7445 --keystore /Users/alex/data/atlas-1/keystore/UTC--2022-06-14T05-46-17.312327000Z--73bc690093b9dd0400c91886184a60cc127b2c33 --lockedNum 200000 INFO [08-02|17:24:16.166] === unLock validator gold === INFO [08-02|17:24:16.166] unLock validator gold amount=200,000,000,000,000,000,000,000 admin=0x73bC690093b9dD0400c91886184A60cC127b2c33 INFO [08-02|17:24:16.180] TxInfo func=sendContractTransaction TX data nonce =15 gasLimit =4,500,000 gasPrice =101,000,000,000 chainID =22776 INFO [08-02|17:24:16.181] Please waiting func=getResult txHash =0x70b5c777daa507ca6b6e6f9132e757f8804c4147f0f8542f71a456ecf079bffa INFO [08-02|17:24:21.229] Transaction Success func=queryTx block Number=1591 ``` #### Query the number of unlocked MAP ```shell ./marker getPendingWithdrawals --rpcaddr http://127.0.0.1:7445 --target 0x73bc690093b9dd0400c91886184a60cc127b2c33 INFO [08-02|17:24:28.336] === getPendingWithdrawals === admin=0x0000000000000000000000000000000000000000 target=0x73bC690093b9dD0400c91886184A60cC127b2c33 INFO [08-02|17:24:28.343] result: index=0 values=100,000,000,000,000,000,000,000 timestamps=1,660,727,111 INFO [08-02|17:24:28.343] result: index=1 values=200,000,000,000,000,000,000,000 timestamps=1,660,728,211 ``` Looking at the output, we can see that we now have two unlocked funds numbered 0 and 1. Next we will withdraw the fund numbered 1. #### Withdraw MAP This step will redeem the status of the reward from the unlocked state to the balance, but this step needs to be unlocked for 15 days before it can be executed. ```shell ./marker withdrawMap --rpcaddr http://127.0.0.1:7445 --keystore /Users/alex/data/atlas-1/keystore/UTC--2022-06-14T05-46-17.312327000Z--73bc690093b9dd0400c91886184a60cc127b2c33 --withdrawIndex 1 INFO [08-02|17:24:44.848] === withdraw validator gold === admin=0x73bC690093b9dD0400c91886184A60cC127b2c33 INFO [08-02|17:24:44.858] TxInfo func=sendContractTransaction TX data nonce =16 gasLimit =4,500,000 gasPrice =101,000,000,000 chainID =22776 INFO [08-02|17:24:44.859] Please waiting func=getResult txHash =0x1d592838b4044a05072692ebc9e8ef68b3f14ff6faa690283f4f363bc6642639 INFO [08-02|17:24:46.072] Transaction Success func=queryTx block Number=1596 ``` #### Check balance Now the redeemed MAP is in the account balance, let's verify it. ```shell web3.fromWei(eth.getBalance("0x73bc690093b9dd0400c91886184a60cc127b2c33"), "ether") 200000.940633728411925694 ``` ### Voter withdraw #### Query the validators that account has voted for. ```shell ./marker getValidatorsVotedForByAccount --rpcaddr http://127.0.0.1:7445 --target 0x6d842e9c25c0c6246231296ca6ecf4bc8268949f INFO [08-03|14:41:27.096] === getValidatorsVotedForByAccount === admin=0x0000000000000000000000000000000000000000 INFO [08-03|14:41:27.100] validator Address=0x73bC690093b9dD0400c91886184A60cC127b2c33 ``` #### Query your account's active votes for validator ```shell ./marker getActiveVotesForValidatorByAccount --rpcaddr http://127.0.0.1:7445 --keystore /Users/alex/data/atlas-1/keystore/UTC--2022-06-17T03-50-52.931374000Z--6d842e9c25c0c6246231296ca6ecf4bc8268949f --target 0x73bc690093b9dd0400c91886184a60cc127b2c33 INFO [08-03|14:41:59.009] === getActiveVotesForValidatorByAccount === admin=0x6D842E9c25C0c6246231296ca6ECf4bC8268949F INFO [08-03|14:41:59.011] ActiveVotes balance=100,648,411,651,178,302,866,465 ``` #### Revokes active votes for validator ```shell ./marker revokeActive --rpcaddr http://127.0.0.1:7445 --keystore /Users/alex/data/atlas-1/keystore/UTC--2022-06-17T03-50-52.931374000Z--6d842e9c25c0c6246231296ca6ecf4bc8268949f --target 0x73bc690093b9dd0400c91886184a60cc127b2c33 --lockedNum 50000 INFO [08-03|14:43:01.909] === revokeActive === admin=0x6D842E9c25C0c6246231296ca6ECf4bC8268949F INFO [08-03|14:43:01.928] TxInfo func=sendContractTransaction TX data nonce =5 gasLimit =4,500,000 gasPrice =101,000,000,000 chainID =22776 INFO [08-03|14:43:01.931] Please waiting func=getResult txHash =0x8dd81d60fdddb8e23f8edaeb243477bce34ab8e835d594f1081b17d4d48c089d INFO [08-03|14:43:10.818] Transaction Success func=queryTx block Number=438 ``` #### Query the total amount of non-voting locked MAP in your account. ```shell ./marker getAccountNonvotingLockedGold --rpcaddr http://127.0.0.1:7445 --target 0x6d842e9c25c0c6246231296ca6ecf4bc8268949f INFO [08-03|14:43:20.659] === getAccountNonvotingLockedGold === admin=0x0000000000000000000000000000000000000000 target=0x6D842E9c25C0c6246231296ca6ECf4bC8268949F INFO [08-03|14:43:20.661] result lockedGold=50,000,000,000,000,000,000,000 ``` #### Unlock MAP This step is used to convert the state of your MAP from locked to unlocked ```shell ./marker unlockMap --rpcaddr http://127.0.0.1:7445 --keystore /Users/alex/data/atlas-1/keystore/UTC--2022-06-17T03-50-52.931374000Z--6d842e9c25c0c6246231296ca6ecf4bc8268949f --lockedNum 50000 INFO [08-03|14:45:33.629] === unLock validator gold === INFO [08-03|14:45:33.629] unLock validator gold amount=50,000,000,000,000,000,000,000 admin=0x6D842E9c25C0c6246231296ca6ECf4bC8268949F INFO [08-03|14:45:33.641] TxInfo func=sendContractTransaction TX data nonce =6 gasLimit =4,500,000 gasPrice =101,000,000,000 chainID =22776 INFO [08-03|14:45:33.642] Please waiting func=getResult txHash =0xd23397b70eb3e13c90fa79c9c4e793569fb21a59bb80719a795864e6c5398b04 INFO [08-03|14:45:37.074] Transaction Success func=queryTx block Number=468 ``` #### Query the number of unlocked MAP ```shell ./marker getPendingWithdrawals --rpcaddr http://127.0.0.1:7445 --target 0x6d842e9c25c0c6246231296ca6ecf4bc8268949f INFO [08-03|14:45:57.066] === getPendingWithdrawals === admin=0x0000000000000000000000000000000000000000 target=0x6D842E9c25C0c6246231296ca6ECf4bC8268949F INFO [08-03|14:45:57.069] result: index=0 values=50,000,000,000,000,000,000,000 timestamps=1,660,805,137 ``` Looking at the output, we can see that we now have a fund number 0 waiting to be redeemed, below we will redeem it #### Withdraw MAP This step will redeem the status of the reward from the unlocked state to the balance, but this step needs to be unlocked for 15 days before it can be executed. ```shell ./marker withdrawMap --rpcaddr http://127.0.0.1:7445 --keystore /Users/alex/data/atlas-1/keystore/UTC--2022-06-17T03-50-52.931374000Z--6d842e9c25c0c6246231296ca6ecf4bc8268949f --withdrawIndex 0 INFO [08-03|14:46:21.582] === withdraw validator gold === admin=0x6D842E9c25C0c6246231296ca6ECf4bC8268949F INFO [08-03|14:46:21.591] TxInfo func=sendContractTransaction TX data nonce =7 gasLimit =4,500,000 gasPrice =101,000,000,000 chainID =22776 INFO [08-03|14:46:21.592] Please waiting func=getResult txHash =0xdc8d99434cdb69ea22cd631b2768999126cf2c7ccc41cfb9fc8f2fabcf301e8c INFO [08-03|14:46:25.229] Transaction Success func=queryTx Block Number=477 T ``` #### Check balance Now the redeemed MAP is in the account balance, let's verify it. ```shell > web3.fromWei(eth.getBalance("0x6d842e9c25c0c6246231296ca6ecf4bc8268949f"), "ether") 50000.880957764 ``` # Marker Tool # Overview ### What is marker marker is a simple command-line tool provided by Atlas. With marker, you can easily perform various operations without the need for additional scripting. It allows you to interact with the Atlas protocol and smart contracts using command-line commands. Some of the common functionalities include registering validators, participating in elections, on-chain governance, and voting for validators. ### Building marker ```shell git clone https://github.com/mapprotocol/atlas.git cd atlas make marker ``` After the build is complete, you can run "./build/bin/marker" to start marker, or navigate to the "./build/bin" directory and run "./marker" to start marker. ### Usage Most of the marker subcommands require connecting to a running Atlas RPC node. Therefore, you need to start an Atlas RPC node first. You can refer to [Run RPC Node](broken://pages/KkWpobRMsoO2L7NuzG2m) for instructions on how to start an RPC node. Alternatively, you can use the provided [public RPC endpoints](/network/relay-chain). There is also a subcommand that requires authentication using a keystore file. Therefore, you need to prepare a keystore file in advance when using these commands. You can generate a keystore file using the following method: 1. [Build Atlas](/run-node/install) 2. Generate a keystore file using the Atlas client: ```shell USAGE ./atlas account new --keystore "keystore path" EXAMPLES: ./atlas account new --keystore ./datadir/keystore RESPONSE: Your new account is locked with a password. Please give a password. Do not forget this password. Password: Repeat password: Your new key was generated Public address of the key: 0x929510A8b54D3a8d7943e2Cdb5BA1888F7Ab7C4a Path of the secret key file: ./datadir/keystore/UTC--2022-03-15T02-11-43.837807000Z--929510a8b54d3a8d7943e2cdb5ba1888f7ab7c4a The keystore has been stored in the directory specified by --keystore. ``` If you already have an account, you can go to the Atlas console to convert your account private key into a keystore file. ```shell USAGE ./atlas --dataDir "./data" console web3.personal.importRawKey("your private key","your password") EXAMPLES: > web3.personal.importRawKey("eaff...db280","password") "0xd2f9e7716cc88944e5ed9f675649532c80d765f8" The keystore has been stored in the directory specified by --dataDir. ``` After the execution is completed, a keystore file will be generated in the "data" directory of the current directory. # Common Commands This article will introduce the features of creating an account, locking MAPO, and various query interfaces. ### createAccount Create an account. Parameter description: * `rpcaddr`: The address of the RPC service, which can be the provided [RPC service address](/network/relay-chain) or your own RPC service address. * `keystore`: The path to the keystore file. * `name`: The name of the account. ```shell ./marker createAccount --rpcaddr http://127.0.0.1:7445 --keystore ./UTC--2021-09-08T08-00-15.473724074Z--1c0edab88dbb72b119039c4d14b1663525b3ac15 --name "validator" ``` ### lockedMAP Lock MAPO for voting or registering validators. Parameter description: * `rpcaddr`: The address of the RPC service, which can be the provided [RPC service address](/network/relay-chain) or your own RPC service address. * `keystore`: The path to the keystore file. * `lockedNum`: The amount of MAPO to be locked. ```shell ./marker lockedMAP --rpcaddr http://127.0.0.1:7445 --keystore ./UTC--2021-09-08T08-00-15.473724074Z--1c0edab88dbb72b119039c4d14b1663525b3ac15 --lockedNum 1000000 ``` ### unlockMap Unlock MAPO, which can be redeemed after the lock period. Parameter description: * `rpcaddr`: The address of the RPC service, which can be the provided [RPC service address](/network/relay-chain) or your own RPC service address. * `keystore`: The path to the keystore file. * `lockedNum`: The amount of MAPO to be unlocked. ```shell ./marker unlockMap --rpcaddr http://127.0.0.1:7445 --keystore ./UTC--2021-09-08T08-00-15.473724074Z--1c0edab88dbb72b119039c4d14b1663525b3ac15 --lockedNum 1000000 ``` ### relockMAP Relock MAPO that has been unlocked but not redeemed. Parameter description: * `rpcaddr`: The address of the RPC service, which can be the provided [RPC service address](/network/relay-chain) or your own RPC service address. * `keystore`: The path to the keystore file. * `lockedNum`: The amount of MAPO to be locked. * `relockIndex`: The index of the request to be redeemed, obtained through the [getPendingWithdrawals](#getpendingwithdrawals) command. ```shell ./marker relockMAP --rpcaddr http://127.0.0.1:7445 --keystore ./UTC--2021-09-08T08-00-15.473724074Z--1c0edab88dbb72b119039c4d14b1663525b3ac15 --lockedNum 100000 --relockIndex 1 ``` ### withdrawMap Redeem MAPO that has passed the unlock period. Parameter description: * `rpcaddr`: The address of the RPC service, which can be the provided [RPC service address](/network/relay-chain) or your own RPC service address. * `keystore`: The path to the keystore file. * `withdrawIndex`: The index of the request to be redeemed, obtained through the [getPendingWithdrawals](#getpendingwithdrawals) command. ```shell USAGE ./marker withdrawMap --rpcaddr http://127.0.0.1:7445 --keystore ./UTC--2021-09-08T08-00-15.473724074Z--1c0edab88dbb72b119039c4d14b1663525b3ac15 --withdrawIndex 1 ``` ### getNumRegisteredValidators Get the number of registered validators. Parameter description: * `rpcaddr`: The address of the RPC service, which can be the provided [RPC service address](/network/relay-chain) or your own RPC service address. ```shell ./marker getNumRegisteredValidators --rpcaddr http://127.0.0.1:7445 ``` ### getTopValidators Return the top N validators in the validator set. Parameter description: * `rpcaddr`: The address of the RPC service, which can be the provided [RPC service address](/network/relay-chain) or your own RPC service address. * `topNum`: Specify the number of top validators to query. ```shell ./marker GetTopValidators --rpcaddr http://127.0.0.1:7445 --topNum 6 RESPONSE: INFO [03-14|17:04:48.606] === getTopValidators === admin=0x0000000000000000000000000000000000000000 INFO [03-14|17:04:48.636] Validator: index=0 addr=0x1c0eDab88dbb72B119039c4d14b1663525b3aC15 INFO [03-14|17:04:48.636] Validator: index=1 addr=0x16FdBcAC4D4Cc24DCa47B9b80f58155a551ca2aF INFO [03-14|17:04:48.636] Validator: index=2 addr=0x2dC45799000ab08E60b7441c36fCC74060Ccbe11 INFO [03-14|17:04:48.636] Validator: index=3 addr=0x6C5938B49bACDe73a8Db7C3A7DA208846898BFf5 ``` ### getTotalVotesForEligibleValidators Return the list of all eligible validators and the number of votes they have received. Parameter description: * `rpcaddr`: The address of the RPC service, which can be the provided [RPC service address](/network/relay-chain) or your own RPC service address. ```shell ./marker getTotalVotesForEligibleValidators --rpcaddr http://127.0.0.1:7445 RESPONSE: INFO [03-14|17:06:13.020] === getTotalVotesForEligibleValidators === admin=0x0000000000000000000000000000000000000000 INFO [03-14|17:06:13.049] Validator: addr=0x1c0eDab88dbb72B119039c4d14b1663525b3aC15 vote amount=70,350,500,000,000,000,000,000,000 INFO [03-14|17:06:13.049] Validator: addr=0x16FdBcAC4D4Cc24DCa47B9b80f58155a551ca2aF vote amount=70,322,500,000,000,000,000,000,000 INFO [03-14|17:06:13.049] Validator: addr=0x2dC45799000ab08E60b7441c36fCC74060Ccbe11 vote amount=70,322,500,000,000,000,000,000,000 INFO [03-14|17:06:13.049] Validator: addr=0x6C5938B49bACDe73a8Db7C3A7DA208846898BFf5 vote amount=70,322,500,000,000,000,000,000,000 INFO [03-14|17:06:13.049] Validator: addr=0x81f02Fd21657DF80783755874a92c996749777Bf vote amount=32,968,000,000,000,000,000,000,000 ``` ### getTotalVotes Get the total number of votes received by all validators. Parameter description: * `rpcaddr`: The address of the RPC service, which can be the provided [RPC service address](/network/relay-chain) or your own RPC service address. ```shell ./marker getTotalVotes --rpcaddr http://127.0.0.1:7445 RESPONSE: INFO [03-14|17:07:24.458] === getAccountLockedGoldRequirement === admin=0x0000000000000000000000000000000000000000 INFO [03-14|17:07:24.487] result getTotalVotes=315,096,000,000,000,000,000,000,000 ``` ### getValidatorEligibility Check if a validator is eligible for receiving votes. Parameter description: * `rpcaddr`: The address of the RPC service, which can be the provided [RPC service address](/network/relay-chain) or your own RPC service address. * `target`: The address of the validator to query. ```shell ./marker getValidatorEligibility --rpcaddr http://127.0.0.1:7445 --target 0x1c0edab88dbb72b119039c4d14b1663525b3ac15 RESPONSE: INFO [03-14|17:10:27.990] === getValidatorEligibility === admin=0x0000000000000000000000000000000000000000 INFO [03-14|17:10:28.018] === result === bool=true ``` ### getValidator Get information about a specific validator. Parameter description: * `rpcaddr`: The address of the RPC service, which can be the provided [RPC service address](/network/relay-chain) or your own RPC service address. * `target`: The address of the validator to query. ```shell ./marker getValidator --rpcaddr http://127.0.0.1:7445 --target 0x1c0edab88dbb72b119039c4d14b1663525b3ac15 RESPONSE: INFO [03-14|17:12:22.303] === getValidator === admin=0x0000000000000000000000000000000000000000 INFO [03-14|17:12:22.332] ecdsaPublicKey=0x2b5e2a3beacf839d1ec74fd00f4388d4b813eac26b26ab4859003473b286650a INFO [03-14|17:12:22.332] BlsPublicKey=0x1fd39f1fbcad8e3188442ea31dee662389599751f8e73b99215cefc2e0003f81 INFO [03-14|17:12:22.332] Score=1 INFO [03-14|17:12:22.332] Signer=0x1c0eDab88dbb72B119039c4d14b1663525b3aC15 INFO [03-14|17:12:22.332] Commission=0.1 INFO [03-14|17:12:22.333] NextCommission=0 INFO [03-14|17:12:22.333] NextCommissionBlock=0 INFO [03-14|17:12:22.333] SlashMultiplier=1 INFO [03-14|17:12:22.333] LastSlashed=0 ``` ### getValidatorRewardInfo Return the reward information for the previous epoch of a validator. Parameter description: * `rpcaddr`: The address of the RPC service, which can be the provided [RPC service address](/network/relay-chain) or your own RPC service address. ```shell ./marker getValidatorRewardInfo --rpcaddr http://127.0.0.1:7445 RESPONSE: INFO [03-14|17:13:42.872] === getReward === cur_epoch=389 epochSize=20 queryBlockNumber=7760 validatorContractAddress=0x000000000000000000000000000000000000D012 admin=0x0000000000000000000000000000000000000000 INFO [03-14|17:13:42.874] validator=0x1c0eDab88dbb72B119039c4d14b1663525b3aC15 reward=19,999,999,999,999,999,999,999 INFO [03-14|17:13:42.874] validator=0x16FdBcAC4D4Cc24DCa47B9b80f58155a551ca2aF reward=19,999,999,999,999,999,999,999 INFO [03-14|17:13:42.874] validator=0x2dC45799000ab08E60b7441c36fCC74060Ccbe11 reward=19,999,999,999,999,999,999,999 INFO [03-14|17:13:42.874] validator=0x6C5938B49bACDe73a8Db7C3A7DA208846898BFf5 reward=19,999,999,999,999,999,999,999 INFO [03-14|17:13:42.874] validator=0x81f02Fd21657DF80783755874a92c996749777Bf reward=9,999,999,999,999,999,999,999 INFO [03-14|17:13:42.874] === END === ``` ### getPendingVotesForValidatorByAccount Get the pending vote count from a specific account for a specific validator. Parameter description: * `rpcaddr`: The address of the RPC service, which can be the provided [RPC service address](/network/relay-chain) or your own RPC service address. * `keystoreAddress`: The address of the account. * `target`: The address of the validator to query. ```shell ./marker getPendingVotesForValidatorByAccount --rpcaddr https://rpc.maplabs.io --keystoreAddress 0x1c0edab88dbb72b119039c4d14b1663525b3ac15 --target 0x51e297bae83b653405ec44cb8dd28792e5510083 INFO [10-10|23:14:22.329] === getPendingVotesForValidatorByAccount === admin=0x1c0edab88dbb72b119039c4d14b1663525b3ac15 INFO [10-10|23:14:24.944] PendingVotes balance=0 ``` ### getActiveVotesForValidatorByAccount Get the active vote count from a specific account for a specific validator. Parameter description: * `rpcaddr`: The address of the RPC service, which can be the provided [RPC service address](/network/relay-chain) or your own RPC service address. * `keystoreAddress`: The address of the account. * `target`: The address of the validator to query. ```shell ./marker getActiveVotesForValidatorByAccount --rpcaddr https://rpc.maplabs.io --keystoreAddress 0x1c0edab88dbb72b119039c4d14b1663525b3ac15 --target 0x51e297bae83b653405ec44cb8dd28792e5510083 RESPONSE: INFO [10-10|23:14:58.531] === getActiveVotesForValidatorByAccount === admin=0x1c0edab88dbb72b119039c4d14b1663525b3ac15 INFO [10-10|23:15:01.851] ActiveVotes balance=100,000,568,936,610,167,111,833 ``` ### getPendingInfoForValidator Retrieve the pending votes and corresponding epoch for a specified account on a specific validator. Parameter description: * `rpcaddr`: The address of the RPC service, which can be the provided [RPC service address](/network/relay-chain) or your own RPC service address. * `keystoreAddress`: The address of the account. * `target`: The address of the validator to query. ```shell ./marker getPendingInfoForValidator --rpcaddr https://rpc.maplabs.io --keystoreAddress 0x1c0edab88dbb72b119039c4d14b1663525b3ac15 --target 0x51e297bae83b653405ec44cb8dd28792e5510083 RESPONSE: INFO [03-14|17:20:49.046] === getPendingInfoForValidator === admin=0x0000000000000000000000000000000000000000 INFO [03-14|17:20:49.074] getPendingInfoForValidator Value=0 Epoch=0 ``` ### getValidatorsVotedForByAccount Get the list of validators voted for by a specific account. Parameter description: * `rpcaddr`: The address of the RPC service, which can be the provided [RPC service address](/network/relay-chain) or your own RPC service address. * `target`: The address of the account to query. ```shell ./marker getValidatorsVotedForByAccount --rpcaddr https://rpc.maplabs.io --target 0x51e297bae83b653405ec44cb8dd28792e5510083 RESPONSE: INFO [10-10|23:32:20.130] === getValidatorsVotedForByAccount === admin=0x0000000000000000000000000000000000000000 INFO [10-10|23:32:23.092] validator Address=0x51E297bAE83b653405ec44Cb8DD28792E5510083 ``` ### getAccountTotalLockedGold Get the total amount of locked MAPO for a specific account. Parameter description: * `rpcaddr`: The address of the RPC service, which can be the provided [RPC service address](/network/relay-chain) or your own RPC service address. * `target`: The address of the account to query. ```shell ./marker getAccountTotalLockedGold \ --rpcaddr https://rpc.maplabs.io \ --target 0x51e297bae83b653405ec44cb8dd28792e5510083 RESPONSE: INFO [10-10|23:38:02.825] === getAccountTotalLockedGold === admin=0x0000000000000000000000000000000000000000 target=0x51E297bAE83b653405ec44Cb8DD28792E5510083 INFO [10-10|23:38:05.419] result lockedGold=1,152,952,667,878,467,847,105,123 ``` ### getAccountNonvotingLockedGold Get the total amount of non-voting locked MAPO for a specific account. Parameter description: * `rpcaddr`: The address of the RPC service, which can be the provided [RPC service address](/network/relay-chain) or your own RPC service address. * `target`: The address of the account to query. ```shell ./marker getAccountNonvotingLockedGold \ --rpcaddr https://rpc.maplabs.io \ --target 0x51e297bae83b653405ec44cb8dd28792e5510083 RESPONSE: INFO [10-10|23:40:16.854] === getAccountNonvotingLockedGold === admin=0x0000000000000000000000000000000000000000 target=0x51E297bAE83b653405ec44Cb8DD28792E5510083 INFO [10-10|23:40:19.401] result lockedGold=0 ``` ### getPendingWithdrawals Get the amount of pending MAPO withdrawals for a specific account. Parameter description: * `rpcaddr`: The address of the RPC service, which can be the provided [RPC service address](/network/relay-chain) or your own RPC service address. * `target`: The address of the account to query. ```shell ./marker getPendingWithdrawals --rpcaddr http://127.0.0.1:7445 --target 0x1c0edab88dbb72b119039c4d14b1663525b3ac15 RESPONSE: INFO [03-14|17:33:18.696] === getPendingWithdrawals === admin=0x1c0eDab88dbb72B119039c4d14b1663525b3aC15 target=0x1c0eDab88dbb72B119039c4d14b1663525b3aC15 INFO [03-14|17:33:18.724] nil ``` ### transfer Transfer MAPO from one account to another. Parameter description: * `rpcaddr`: The address of the RPC service, which can be the provided [RPC service address](/network/relay-chain) or your own RPC service address. * `keystore`: The path to the keystore file. * `target`: The address of the recipient's account. * `amount`: The amount of MAPO to transfer. ```shell ./marker transfer \ --rpcaddr http://127.0.0.1:7445 \ --keystore /Users/alex/data/keystore/UTC--2022-05-31T03-33-25.405082000Z--3b778bb4f460956e313ba92484eb84603a86a625 \ --target 0x7cc3e34c2075d96ef69bf6445a234f6c5e244073 \ --amount 10 RESPONSE: INFO [08-30|10:56:11.048] Tx Info func=sendContractTransaction from=0x3B778BB4F460956E313Ba92484Eb84603A86a625 to=0x7cC3e34C2075D96ef69bF6445a234F6C5E244073 value=10 nonce =1 gasLimit =4,500,000 gasPrice =101,000,000,000 chainID =212 INFO [08-30|10:56:11.144] Please waiting func=getResult txHash =0x55beb566d735e7b46e61d85f23e52b0958777ba4bbd2332244b3a2e5eb22e137 INFO [08-30|10:56:12.234] Please waiting, Transaction is in pending status func=getResult INFO [08-30|10:56:13.328] Please waiting, Transaction is in pending status func=getResult INFO [08-30|10:56:15.748] Transaction Success func=getResult number=668,236 INFO [08-30|10:56:15.748] transfer success from =0x3B778BB4F460956E313Ba92484Eb84603A86a625 to=0x7cC3e34C2075D96ef69bF6445a234F6C5E244073 amount=10 ``` ### getAccountMetadataURL Get the metadata URL for a specific account. Parameter description: * `rpcaddr`: The address of the RPC service, which can be the provided [RPC service address](/network/relay-chain) or your own RPC service address. * `target`: The address of the account to query. ```shell ./marker getAccountMetadataURL \ --rpcaddr https://rpc.maplabs.io \ --target 0x82965be3c2784edca8ad4472c80ffbe44404da49 RESPONSE: INFO [10-10|23:50:02.275] get account metadata url address=0x82965bE3c2784eDcA8ad4472c80FfBe44404Da49 url= ``` ### setAccountMetadataURL Set the metadata URL for a specific account. Parameter description: * `rpcaddr`: The address of the RPC service, which can be the provided [RPC service address](/network/relay-chain) or your own RPC service address. * `keystore`: The path to the keystore file. * `target`: The address of the account. ```shell ./marker setAccountMetadataURL \ --rpcaddr http://127.0.0.1:7445 \ --keystore /Users/alex/data/keystore/UTC--2022-08-26T10-59-01.086763000Z--ef021f15d188ad28625517a8d73cd20ce743a32d \ --url https://www.metadata.com RESPONSE: INFO [08-30|11:09:53.016] set account metadata url address=0xeF021f15D188ad28625517A8D73CD20cE743a32D url=https://www.metadata.com INFO [08-30|11:09:54.678] Tx Info func=sendContractTransaction from=0xeF021f15D188ad28625517A8D73CD20cE743a32D to=0x000000000000000000000000000000000000d010 value= nonce =5 gasLimit =4,500,000 gasPrice =101,000,000,000 chainID =20212 INFO [08-30|11:09:55.092] Please waiting func=getResult txHash =0xde15a1daee5e74c183f759c00cf51ba09c31c76c01362a25e2020b1c04fa9f7d INFO [08-30|11:09:56.508] Please waiting, Transaction is in pending status func=getResult INFO [08-30|11:09:57.926] Please waiting, Transaction is in pending status func=getResult INFO [08-30|11:09:58.350] Transaction Success func=getResult number=61898 ``` ### getAccountName Get the name of an account. Parameter description: * `rpcaddr`: The address of the RPC service, which can be the provided [RPC service address](/network/relay-chain) or your own RPC service address. * `target`: The address of the account. ```shell ./marker getAccountName \ --rpcaddr https://rpc.maplabs.io \ --target 0x5d643dfb9ae372ce4fdbc80890156e2cd8290846 RESPONSE: INFO [10-10|23:52:46.084] get name address=0x5d643Dfb9ae372ce4Fdbc80890156E2CD8290846 name="MAP Protocol#1" ``` ### setAccountName Set the name for an account. Parameter description: * `rpcaddr`: The address of the RPC service, which can be the provided [RPC service address](/network/relay-chain) or your own RPC service address. * `keystore`: The path to the keystore file. * `name`: The name to set for the account. ```shell ./marker setAccountName \ --rpcaddr http://127.0.0.1:7445 \ --keystore ./UTC--2022-08-26T10-59-01.086763000Z--ef021f15d188ad28625517a8d73cd20ce743a32d \ --name "so cool validator" RESPONSE: INFO [08-31|15:16:07.006] set name address=0xeF021f15D188ad28625517A8D73CD20cE743a32D name="so cool validator" INFO [08-31|15:16:09.039] Tx Info func=sendContractTransaction from=0xeF021f15D188ad28625517A8D73CD20cE743a32D to=0x000000000000000000000000000000000000d010 value= nonce =10 gasLimit =4,500,000 gasPrice =101,000,000,000 chainID =20212 INFO [08-31|15:16:09.448] Please waiting func=getResult txHash =0x046ee71f161c06d34c4eb13ed9c536e909da152d9ca4036ccb240ae1ab23cb7f INFO [08-31|15:16:10.983] Please waiting, Transaction is in pending status func=getResult INFO [08-31|15:16:12.517] Please waiting, Transaction is in pending status func=getResult INFO [08-31|15:16:14.048] Please waiting, Transaction is in pending status func=getResult INFO [08-31|15:16:17.024] Transaction Success func=getResult number=82133 ``` ### setNextCommissionUpdate Add a validator commission update request to the queue. If there is an existing update request, it will be overridden. Parameter description: * `rpcaddr`: The address of the RPC service, which can be the provided [RPC service address](/network/relay-chain) or your own RPC service address. * `keystore`: The path to the keystore file. * `commission`: The commission rate for the validator, expressed as a ratio relative to 1000000. The range of the commission parameter is from 0 to 1000000. If you want to set the commission rate to 15%, you would set this parameter to 150000 (150000/1000000=15%). This is one of the parameters that voters consider when voting. ```shell ./marker setNextCommissionUpdate \ --rpcaddr http://127.0.0.1:7445 \ --keystore ./UTC--2022-08-26T10-59-01.086763000Z--ef021f15d188ad28625517a8d73cd20ce743a32d \ --commission 300000 RESPONSE: INFO [09-01|14:17:15.746] === setNextCommissionUpdate === commission=300,000 INFO [09-01|14:17:17.644] Tx Info func=sendContractTransaction from=0xeF021f15D188ad28625517A8D73CD20cE743a32D to=0x000000000000000000000000000000000000D012 value= nonce =14 gasLimit =4,500,000 gasPrice =101,000,000,000 chainID =20212 INFO [09-01|14:17:18.062] Please waiting func=getResult txHash =0xcb72b1a5055b290712a5f8e72a4bc60028b144ebea92c12637315891874ab8bf INFO [09-01|14:17:20.911] Transaction Success func=getResult number=98706 ``` ### updateCommission Update the commission based on the previous update request in the queue. This operation can only be executed after 2000 blocks have passed since [setNextCommissionUpdate](#setNextCommissionUpdate) was executed. Parameter description: * `rpcaddr`: The address of the RPC service, which can be the provided [RPC service address](/network/relay-chain) or your own RPC service address. * `keystore`: The path to the keystore file. ```shell ./marker updateCommission \ --rpcaddr http://127.0.0.1:7445 \ --keystore ./UTC--2022-08-26T10-59-01.086763000Z--ef021f15d188ad28625517a8d73cd20ce743a32d RESPONSE: INFO [09-01|14:18:15.648] === updateCommission === INFO [09-01|14:18:17.303] Tx Info func=sendContractTransaction from=0xeF021f15D188ad28625517A8D73CD20cE743a32D to=0x000000000000000000000000000000000000D012 value= nonce =15 gasLimit =4,500,000 gasPrice =101,000,000,000 chainID =20212 INFO [09-01|14:18:17.717] Please waiting func=getResult txHash =0x4f252120cc61e27d72d47e6f6a9dd732bb9aa319937b94fdb602c6c93feb4c83 INFO [09-01|14:18:20.536] Transaction Success func=getResult number=98718 ``` # Validator Commands 关于 validator 的注册、注销等介绍。 ### register Register a new validator. Through this command, we will transfer your Commission, ecdsaPublicKey, blsPublicKey, blsG1PublicKey, and BLSProof to the management contract to manage and secure your assets. Your ecdsaPublicKey, blsPublicKey, and BLSProof will be obtained through the specified keystore. The ECDSA public key that the validator is using for consensus should match the validator signer and be 64 bytes in length. The BLS public key that the validator is using for consensus should pass proof of possession and be 129 bytes in length. The BLS G1 public key that the validator is using for consensus should be 129 bytes in length. The BLS public key proof-of-possession consists of a signature on the account address and is 129 bytes in length. Parameter description: * `rpcaddr`: The address of the RPC service, which can be either the provided [RPC service address](/network/relay-chain) or your own RPC service address. * `keystore`: The path to the keystore file. * `commission`: The commission rate for the validator's rewards. The commission parameter is set relative to 1000000, with a range from 0 to 1000000. If you want to set the commission rate to 15%, you need to set this parameter to 150000 (150000/1000000=15%). This attribute is one of the reference objects used by voters when voting. ```shell ./marker register --rpcaddr http://127.0.0.1:7445 --keystore ./UTC--2021-09-08T08-00-15.473724074Z--1c0edab88dbb72b119039c4d14b1663525b3ac15 --commission 0.1 RESPONSE: success or Failed ``` ### quicklyRegister To quickly register a new validator, you can use the `quicklyRegister` command, which integrates the `createAccount`, `lockedMAP`, and `register` commands. Please note that you can only use this command once. Regardless of the success or failure of the command, it includes the operations corresponding to the `createAccount` and `lockedMAP` commands and does not have the feature of being reusable. Parameter description: * `rpcaddr`: The address of the RPC service, which can be either the provided [RPC service address](/network/relay-chain) or your own RPC service address. * `keystore`: The path to the keystore file. * `commission`: The commission rate for the validator's rewards. The commission parameter is set relative to 1000000, with a range from 0 to 1000000. If you want to set the commission rate to 15%, you need to set this parameter to 150000 (150000/1000000=15%). This attribute is one of the reference objects used by voters when voting. * `lockedNum`: The amount of MAPO tokens to be locked in order to register as a validator. * `signerPriv`: The private key of the signer account. ```shell ./marker quicklyRegister --rpcaddr http://127.0.0.1:7445 --keystore ./UTC--2021-09-08T08-00-15.473724074Z--1c0edab88dbb72b119039c4d14b1663525b3ac15 --commission 100000 --signerPriv 842e1d8a93b4e46104da96676066ddb0973c63ec80a15746856c046dd4a1004c --lockedNum 1000000 RESPONSE: success or Failed ``` ### deregister The `deregister` command is used to unregister a validator. You must be a validator to use this command. The contract has a minimum time requirement to become a validator (default is 60 days). To deregister a validator, you must have exceeded this time. To prevent malicious resource occupation during the deregistration process, we will put your deregistration request in a pending state and execute batch deregistration at the last block of the epoch. Parameter description: * `rpcaddr`: The address of the RPC service, which can be either the provided [RPC service address](/network/relay-chain) or your own RPC service address. * `keystore`: The path to the keystore file. ```shell ./marker deregister --rpcaddr http://127.0.0.1:7445 --keystore ./UTC--2021-09-08T08-00-15.473724074Z--1c0edab88dbb72b119039c4d14b1663525b3ac15 RESPONSE: success or Failed ``` ### revertRegister If you deregistered your account in a specific epoch, you can use the `revertRegister` command within the same epoch to restore your validator status. Parameter description: * `rpcaddr`: The address of the RPC service, which can be either the provided [RPC service address](/network/relay-chain) or your own RPC service address. * `keystore`: The path to the keystore file. ```shell ./marker revertRegister --rpcaddr http://127.0.0.1:7445 --keystore ./UTC--2021-09-08T08-00-15.473724074Z--1c0edab88dbb72b119039c4d14b1663525b3ac15 RESPONSE: success or Failed ``` ### authorizeValidatorSigner Call this method before becoming a validator. If you need to authorize another account to perform on-chain consensus operations instead of using the validator account, you can call this method to grant authorization. This allows another account to perform on-chain consensus operations. Parameter description: * `rpcaddr`: The address of the RPC service, which can be either the provided [RPC service address](/network/relay-chain) or your own RPC service address. * `keystore`: The path to the keystore file. * `signerPriv`: The private key of the signer account. ```shell ./marker authorizeValidatorSigner --rpcaddr http://127.0.0.1:7445 --keystore ./UTC--2021-09-08T08-00-15.473724074Z--1c0edab88dbb72b119039c4d14b1663525b3ac15 --signerPriv 842e1d8a93b4e46104da96676066ddb0973c63ec80a15746856c046dd4a1004c RESPONSE: INFO [05-30|13:41:55.131] === authorizeValidatorSigner === INFO [05-30|13:41:55.140] TxInfo func=sendContractTransaction TX data nonce =3 gasLimit =4,500,000 gasPrice =101,000,000,000 chainID =214 INFO [05-30|13:41:55.141] Please waiting func=getResult txHash =0x6ccc9758199c105c2b8eb9f9807b553baaa9062ec871a1fc47f3866a4a1e8d49 INFO [05-30|13:42:03.231] Transaction Success func=queryTx block Number=37 ``` ### makeECDSASignatureFromSigner Generate an ECDSA signature signed by the signer account, which has signed the validator account. Parameter description: * `signerPriv`: The private key of the signer account. * `target`: The address of the validator account you want to sign. ```shell makeECDSASignatureFromSigner --signerPriv c59c8a05f70b5ea0a0f2a2bd9491686a8c4a55c0585db2c8c6ed7ccfa0ee2c7b --target 0xac146d6629F8C3B8F2e830275B583C5402032472 RESPONSE: INFO [05-30|13:41:55.131] === ECDSASignature === INFO [05-30|13:41:55.131] === signer === account=0x05D0CFd882185dEB9b3E0eA7872Ad332acB9E31d INFO [05-30|13:41:55.131] ECDSASignature result=0x6dcec34a67a3388b6fbf93ad48f88aa88c0ce46789de0f9e042acbe6e116c97f26d645652576a65602ed97f7ca16f890898b8e761de3edc34447edb2e41713ad01 ``` ### makeBLSProofOfPossessionFromSigner Generate a BLSProofOfPossession signed by the signer account for the validator account. Parameter description: * `signerPriv`: The private key of the signer account. * `target`: The address of the validator account you want to sign. ```shell makeBLSProofOfPossessionFromSigner --signerPriv c59c8a05f70b5ea0a0f2a2bd9491686a8c4a55c0585db2c8c6ed7ccfa0ee2c7b --target 0xac146d6629F8C3B8F2e830275B583C5402032472 RESPONSE: INFO [05-30|13:52:40.371] === makeBLSProofOfPossessionFromSigner === INFO [05-30|13:52:40.375] === pop === result=0x1417ef1814518ade2af0e52ce7a11bcf834bba5ac42f91f3a1229c072721bb1b0c82513600690ebc0244572dd459d280abd6c14c0fc4837fa06335c88457a402 ``` ### signerToAccount Query the validator account that has authorized the target signer account. Parameter description: * `rpcaddr`: The address of the RPC service, which can be either the provided [RPC service address](/network/relay-chain) or your own RPC service address. * `keystore`: The path to the keystore file. * `target`: The address of the signer account. ```shell signerToAccount --rpcaddr http://127.0.0.1:7445 --keystore ./UTC--2022-05-11T03-31-08.562982000Z--6621f2b6da2bed64b5ffbd6c5b2138547f44c8f9 --target "0x05D0CFd882185dEB9b3E0eA7872Ad332acB9E31d" RESPONSE: INFO [05-30|13:52:40.371] === signerToAccount === INFO [05-30|13:56:05.126] signerToAccount authorizingAccount=0xa88cF1842AC49A22435D6B4e4c1d8782e3C29EfE ``` ### generateSignerProof Generate a proof using the signer private key. Parameter description: * `validator`: The address of the validator account. * `signerPriv`: The private key of the signer account. ```shell ./marker generateSignerProof --validator 0x73bc690093b9dd0400c91886184a60cc127b2c33 --signerPriv 040939e5...604b6f25 RESPONSE: INFO [08-26|17:32:23.950] generateBLSProof validator=0x01ccDcd1aE63a2C6B4c3493983dc6400C63729Ad signerPrivate=040939e5...604b6f25 INFO [08-26|17:32:23.955] === makeBLSProofOfPossessionFromSigner === INFO [08-26|17:32:23.958] generateBLSProof proof=0xf90149b8...0e56f0ab1 ``` ### authorizeValidatorSignerBySignature Call this method before becoming a validator. If you need to authorize another account to perform on-chain consensus operations instead of using the validator account, you can call this method to grant authorization. This allows another account to perform on-chain consensus operations. Parameter description: * `rpcaddr`: The address of the RPC service, which can be either the provided [RPC service address](/network/relay-chain) or your own RPC service address. * `keystore`: The path of the keystore file. * `signer`: The address of the signer account. * `signature`: The ECDSA signature generated using the [makeECDSASignatureFromSigner](#makeECDSASignatureFromSigner) command. * ```shell ./marker authorizeValidatorSignerBySignature --rpcaddr http://127.0.0.1:7445 --keystore ./account.json --signer 0x26654eb0bb935dce4a34daa3e14c67662a8aa1f8 --signature 0x59dff185...32f0d700 RESPONSE: INFO [07-08|14:55:00.015] authorizeValidatorSignerBySignature signer=0x26654eb0bb935dce4a34daa3e14c67662a8aa1f8 signature=0x59dff185...32f0d700 INFO [07-08|14:55:00.032] Please waiting func=getResult txHash =0xb73a1376e661d523e44b87c37e2e03cc36534d3a550808245f263aaad358b0ad INFO [07-08|14:55:05.078] Transaction Success func=queryTx block Number=16 ``` ### registerByProof Register a validator using the proof generated by `generateSignerProof`. Parameter description: * `rpcaddr`: The address of the RPC service, which can be either the provided [RPC service address](/network/relay-chain) or your own RPC service address. * `keystore`: The path of the keystore file. * `proof`: The proof generated using the [generateSignerProof](#generateSignerProof) command. * `commission`: The commission rate for the validator, expressed as a ratio relative to 1000000. The range of the commission parameter is from 0 to 1000000. If you want to set the commission rate to 15%, you would set this parameter to 150000 (150000/1000000=15%). This is one of the parameters that voters consider when voting. ```shell ./marker registerByProof --rpcaddr http://127.0.0.1:7445 --keystore ./account.json - --proof 0xf90149b8...0e56f0ab1 --commission 150000 RESPONSE: INFO [08-26|17:32:25.055] registerValidatorByProof commission=150,000 INFO [08-26|17:32:25.548] === getTotalVotesForValidator === admin=0x73bc690093b9dd0400c91886184a60cc127b2c33 INFO [08-26|17:32:25.974] === getTotalVotesForValidator === result=0 INFO [08-26|17:32:26.011] TxInfo func=sendContractTransaction TX data nonce =7 gasLimit =4,500,000 gasPrice =101,000,000,000 chainID =1,098,789 INFO [08-26|17:32:26.119] Please waiting func=getResult txHash =0xfb0487e7196df7489e90ab91217251da5fc7d07b2bc2d2f4ea67966a506a4cd6 INFO [08-26|17:32:27.241] Transaction Success func=queryTx ``` # Vote Commands Introduction to commands related to voting operations ## vote Vote for the specified validator. You must [locked](/validator/marker-tool/common#lockedmap) enough MAPO tokens in the LockedGold contract in advance and register your information in the contract. This operation will decrease the total votes and unvoted amount of your previously registered account in the LockedGold contract, and increase the total votes and pending votes of the validator in the Election contract. Parameter description: * `rpcaddr`: The address of the RPC service, which can be either the provided [RPC service address](/network/relay-chain) or your own RPC service address. * `keystore`: The path to the keystore file. * `target`: The address of the validator you want to vote for. * `voteNum`: The number of MAPO tokens you want to vote with. ```shell ./marker vote --rpcaddr http://127.0.0.1:7445 --keystore ./UTC--2021-09-08T08-00-15.473724074Z--1c0edab88dbb72b119039c4d14b1663525b3ac15 --target "0x81f02fd21657df80783755874a92c996749777bf" --voteNum 10000 ``` ## quicklyVote If you have not created an account and locked MAPO tokens yet, you can quickly vote using the quicklyVote command, which integrates the createAccount, lockedMAP, and vote commands. Please note that you can only use this command once. Regardless of the success or failure of the command, it includes the operations corresponding to the createAccount, lockedMAP, and vote commands and does not have the feature of being reusable. Parameter description: * `rpcaddr`: The address of the RPC service, which can be either the provided [RPC service address](/network/relay-chain) or your own RPC service address. * `keystore`: The path to the keystore file. * `target`: The address of the validator you want to vote for. * `voteNum`: The number of MAPO tokens you want to vote with. * `lockedNum`: The number of MAPO tokens you want to lock. ```shell ./marker quicklyVote --rpcaddr http://127.0.0.1:7445 --keystore ./UTC--2021-09-08T08-00-15.473724074Z--1c0edab88dbb72b119039c4d14b1663525b3ac15 --target "0x81f02fd21657df80783755874a92c996749777bf" --voteNum 10000 --lockedNum 10000 ``` ## activate Activate pending votes to start earning rewards. As a voter, you need to activate your pending votes at some point after the end of the epoch in which the pending votes were generated. This means converting the pending votes of your account into active votes. Parameter description: * `rpcaddr`: The address of the RPC service, which can be either the provided [RPC service address](/network/relay-chain) or your own RPC service address. * `keystore`: The path to the keystore file. * `target`: The address of the validator for which you want to activate votes. ```shell ./marker activate --rpcaddr http://127.0.0.1:7445 --keystore ./UTC--2021-09-08T08-00-15.473724074Z--1c0edab88dbb72b119039c4d14b1663525b3ac15 --target "0x81f02fd21657df80783755874a92c996749777bf" ``` ## revokePending Revoke pending votes for a validator. This command converts the voting state of MAPO tokens to non-voting MAPO tokens and increases the total votes and non-votes of your previously registered account in the LockedGold contract. In the Election contract, it decreases the total votes and pending votes of the validator. Parameter description: * `rpcaddr`: The address of the RPC service, which can be either the provided [RPC service address](/network/relay-chain) or your own RPC service address. * `keystore`: The path to the keystore file. * `target`: The address of the validator for which you want to revoke pending votes. * `lockNum`: The number of MAPO tokens you want to revoke from the validator's pending votes. ```shell ./marker revokePending --rpcaddr http://127.0.0.1:7445 --keystore ./UTC--2021-09-08T08-00-15.473724074Z--1c0edab88dbb72b119039c4d14b1663525b3ac15 --target "0x81f02fd21657df80783755874a92c996749777bf" --lockedNum 10000 ``` ## revokeActive Revoke active votes for a validator. This command converts voting MAPO tokens to non-voting MAPO tokens. It increases the total votes and non-votes of your previously registered account in the LockedGold contract. In the Election contract, it decreases the total votes and active votes of the validator. Parameter description: * `rpcaddr`: The address of the RPC service, which can be either the provided [RPC service address](/network/relay-chain) or your own RPC service address. * `keystore`: The path to the keystore file. * `target`: The address of the validator for which you want to revoke active votes. * `lockNum`: The number of MAPO tokens you want to revoke from the validator's active votes. ```shell ./marker revokeActive --rpcaddr http://127.0.0.1:7445 --keystore ./UTC--2021-09-08T08-00-15.473724074Z--1c0edab88dbb72b119039c4d14b1663525b3ac15 --target "0x81f02fd21657df80783755874a92c996749777bf" --lockedNum 10000 ``` # Overview ## Introduction Compass-TSS is the off-chain client software for participating in MAP Protocol v2's TSS (Threshold Signature Scheme) network. It enables Validators to become Maintainers and participate in cross-chain signing operations. ## What is Compass-TSS? Compass-TSS is a node software that: * **Observes** cross-chain events on multiple chains * **Participates** in TSS key generation (KeyGen) * **Signs** cross-chain transactions collaboratively (KeySign) * **Communicates** with other Maintainer nodes via P2P network ## System Requirements ### Hardware Requirements | Component | Minimum | Recommended | | --------- | ---------- | ----------- | | CPU | 4 cores | 8+ cores | | RAM | 8 GB | 16+ GB | | Storage | 100 GB SSD | 500 GB SSD | | Network | 100 Mbps | 1 Gbps | ### Network Requirements * Static IP or reliable dynamic DNS * Open ports for P2P communication * Low latency connection to other Maintainers ### Prerequisites * Running MAP Relay Chain Validator node * Registered as Validator with sufficient stake * Registered as Maintainer on-chain ## Architecture ``` ┌─────────────────────────────────────────────────────────────────┐ │ Compass-TSS Node │ │ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ Observer │ │ Signer │ │ P2P Node │ │ │ │ │ │ │ │ │ │ │ │ - Watch │ │ - KeyGen │ │ - Discovery │ │ │ │ chains │ │ - KeySign │ │ - Messaging │ │ │ │ - Parse │ │ - Key │ │ - Broadcast │ │ │ │ events │ │ storage │ │ │ │ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │ │ │ │ │ │ └────────────────┼────────────────┘ │ │ │ │ │ ┌──────┴──────┐ │ │ │ Database │ │ │ │ (LevelDB) │ │ │ └─────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────┘ │ │ │ ▼ ▼ ▼ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ Source │ │ MAP │ │ Other │ │ Chains │ │ Relay │ │Maintainer│ │ │ │ Chain │ │ Nodes │ └──────────┘ └──────────┘ └──────────┘ ``` ## Key Features ### Multi-Chain Observation * Monitors events on all connected chains * Parses deposit and withdrawal events * Submits observations to MAP Relay Chain ### TSS Operations * Participates in KeyGen when elected * Signs transactions via TSS KeySign * Securely stores key shares ### P2P Network * Discovers other Maintainer nodes * Exchanges TSS protocol messages * Maintains reliable connections ## Rewards and Penalties ### Rewards * Share of cross-chain transaction fees * Proportional to participation in signing ### Penalties (Slashing) | Violation | Consequence | | --------------------------- | ------------------- | | Offline during KeySign | Slash points | | Failed KeyGen participation | Jail period | | Double signing | Severe slash + jail | | Invalid observations | Slash points | ## Comparison with Compass (v1) | Feature | Compass (v1) | Compass-TSS (v2) | | -------------- | ---------------------- | ----------------- | | Role | Maintainer + Messenger | TSS Maintainer | | Function | Light client updates | TSS signing | | Registration | Permissionless | Must be Validator | | Key Management | No keys | TSS key shares | | Consensus | Independent | Threshold (2/3) | ## Quick Start 1. **Set up Validator**: Run MAP Relay Chain validator node 2. **Register**: Register as Maintainer on-chain 3. **Install**: Install Compass-TSS software 4. **Configure**: Set up configuration file 5. **Run**: Start Compass-TSS node ## Next Steps * [Requirements](/compass-tss-crossx/requirements) - Detailed hardware and network requirements * [Register as Maintainer](/compass-tss-crossx/register-maintainer) - How to register on-chain ## Support For issues and questions: * GitHub Issues: [compass-tss repository](https://github.com/mapprotocol/compass-tss) * Discord: MAP Protocol community # Requirements ## Overview This document outlines the requirements for running a Compass-TSS node as a Maintainer in MAP Protocol v2. ## Hardware Requirements ### Minimum Specifications | Component | Requirement | | --------- | ------------------ | | CPU | 4 cores, 2.0 GHz+ | | RAM | 8 GB | | Storage | 100 GB SSD | | Network | 100 Mbps symmetric | ### Recommended Specifications | Component | Requirement | | --------- | ------------------ | | CPU | 8+ cores, 3.0 GHz+ | | RAM | 16 GB+ | | Storage | 500 GB NVMe SSD | | Network | 1 Gbps symmetric | ### Storage Considerations * **Key Storage**: TSS key shares require secure storage * **Database**: LevelDB for local state * **Logs**: Sufficient space for operational logs ## Network Requirements ### Connectivity * **Static IP**: Recommended for reliable P2P connections * **Dynamic DNS**: Acceptable alternative to static IP * **Uptime**: 99.9%+ availability expected ### Ports | Port | Protocol | Purpose | | ----- | -------- | ------------------------------- | | 8080 | TCP | P2P communication | | 9090 | TCP | Metrics (optional) | | 26656 | TCP | MAP Relay Chain P2P | | 8545 | TCP | JSON-RPC (if running validator) | ### Firewall Rules ```bash # Allow P2P communication ufw allow 8080/tcp # Allow metrics (optional) ufw allow 9090/tcp ``` ### Latency Requirements * **P2P Latency**: < 500ms to majority of Maintainers * **RPC Latency**: < 100ms to MAP Relay Chain node ## Software Requirements ### Operating System | OS | Version | Support | | ------ | -------------------- | ---------------- | | Ubuntu | 20.04 LTS, 22.04 LTS | Recommended | | Debian | 11, 12 | Supported | | CentOS | 8, 9 | Supported | | macOS | 12+ | Development only | ### Dependencies * Go 1.21+ * Git * Make * GCC (for CGO) ### Installation Commands (Ubuntu) ```bash # Update system sudo apt update && sudo apt upgrade -y # Install dependencies sudo apt install -y git make gcc curl # Install Go wget https://go.dev/dl/go1.21.0.linux-amd64.tar.gz sudo tar -C /usr/local -xzf go1.21.0.linux-amd64.tar.gz echo 'export PATH=$PATH:/usr/local/go/bin' >> ~/.bashrc source ~/.bashrc ``` ## Prerequisites ### 1. MAP Relay Chain Validator You must be running a MAP Relay Chain validator node: * Synced to latest block * Participating in consensus * Sufficient stake locked ### 2. Validator Registration Your validator must be registered and active: ```bash # Check validator status marker getValidator --address ``` ### 3. Maintainer Registration Register as Maintainer on MAP Relay Chain: ```bash # Register as Maintainer (see register-maintainer.md for details) ``` ### 4. Stake Requirements | Requirement | Amount | | --------------- | -------------------------------- | | Validator Stake | 1,000,000 MAPO minimum | | Maintainer Bond | Additional stake may be required | ## Security Requirements ### Key Management * **Secure Storage**: Key shares must be encrypted at rest * **Backup**: Secure backup of key shares (offline) * **Access Control**: Restrict access to key files ### Server Security * **SSH**: Key-based authentication only * **Firewall**: Restrict to necessary ports * **Updates**: Regular security updates * **Monitoring**: Intrusion detection recommended ### Operational Security * **Separate Accounts**: Don't run as root * **Dedicated Server**: Avoid shared hosting * **Physical Security**: Secure data center recommended ## Monitoring Requirements ### Recommended Monitoring * CPU, RAM, Disk usage * Network connectivity * P2P peer count * Signing participation rate * Slash points accumulation ### Alerting Set up alerts for: * Node offline * High resource usage * Failed signing sessions * Peer disconnections ## Checklist Before proceeding to installation: * [ ] Hardware meets minimum requirements * [ ] Static IP or dynamic DNS configured * [ ] Required ports open * [ ] Operating system installed and updated * [ ] Dependencies installed * [ ] MAP Relay Chain validator running and synced * [ ] Validator registered and active * [ ] Sufficient stake locked * [ ] Security measures in place # Register as Maintainer ## Overview To participate in MAP Protocol v2's TSS network, you must register as a Maintainer on MAP Relay Chain. This document explains the registration process. ## Prerequisites Before registering as Maintainer: 1. **Running Validator**: Active validator on MAP Relay Chain 2. **Sufficient Stake**: Meet minimum staking requirements 3. **Compass-TSS Ready**: Node software installed and configured ## Registration Process ### Step 1: Check Validator Status Ensure your validator is active: ```bash # Check validator status marker getValidator --rpcaddr --address ``` Expected output should show: * `isValidator: true` * `isElected: true` (if currently in validator set) ### Step 2: Prepare Registration Information Gather the following information: | Field | Description | Example | | ----------------- | ------------------------ | ---------------------- | | Validator Address | Your validator's address | 0x1234...abcd | | P2P Public Key | Compass-TSS P2P identity | Generated during setup | | P2P Endpoint | Your node's P2P address | 192.168.1.1:8080 | ### Step 3: Generate P2P Identity If not already done during Compass-TSS setup: ```bash # Generate P2P key pair compass-tss keys generate --output ./keys/p2p ``` This creates: * `p2p.key`: Private key (keep secure) * `p2p.pub`: Public key (used for registration) ### Step 4: Register on Chain Call the Maintainer Manager contract: ```bash # Register as Maintainer marker registerMaintainer \ --rpcaddr \ --keystore \ --p2pPubKey \ --p2pEndpoint ``` ### Step 5: Verify Registration Check your registration status: ```bash # Check Maintainer status marker getMaintainer --rpcaddr --address ``` ## Election Process ### How Election Works 1. **Registration**: Maintainers register during open period 2. **Snapshot**: At epoch boundary, registered Maintainers are snapshotted 3. **Selection**: Top N Maintainers by stake are elected 4. **Activation**: Elected Maintainers participate in next epoch ### Election Parameters | Parameter | Value | | ------------------ | --------------------- | | Election Period | Every epoch (\~1 day) | | Active Set Size | Variable (e.g., 21) | | Selection Criteria | Stake-weighted | ### Check Election Status ```bash # Check if elected for current epoch marker isElectedMaintainer --rpcaddr --address ``` ## After Registration ### Wait for Election * Registration doesn't guarantee immediate participation * You'll be considered in the next election cycle * Higher stake increases election probability ### Start Compass-TSS Once registered, start your Compass-TSS node: ```bash # Start Compass-TSS compass-tss start --config ./config.toml ``` ### Monitor Status Check your Maintainer status regularly: ```bash # Check participation metrics compass-tss status ``` ## Updating Registration ### Update P2P Endpoint If your IP changes: ```bash marker updateMaintainer \ --rpcaddr \ --keystore \ --p2pEndpoint ``` ### Update P2P Key If you need to rotate your P2P key: ```bash # Generate new key compass-tss keys generate --output ./keys/p2p-new # Update on chain marker updateMaintainer \ --rpcaddr \ --keystore \ --p2pPubKey ``` ## Deregistration To stop being a Maintainer: ```bash marker deregisterMaintainer \ --rpcaddr \ --keystore ``` **Note**: Deregistration may have a cooldown period. Check current protocol parameters. ## Troubleshooting ### Registration Failed | Error | Solution | | --------------------- | ----------------------------------------- | | "Not a validator" | Ensure validator is registered and active | | "Insufficient stake" | Lock additional MAPO tokens | | "Invalid P2P key" | Regenerate P2P key pair | | "Registration closed" | Wait for next registration period | ### Not Getting Elected * Increase your stake * Ensure validator is performing well (not jailed) * Check for pending slashing ### P2P Connection Issues * Verify firewall allows P2P port * Check P2P endpoint is reachable * Ensure correct P2P public key registered ## Best Practices 1. **Reliable Infrastructure**: Use stable, well-connected servers 2. **Monitor Continuously**: Set up alerts for node issues 3. **Keep Software Updated**: Update Compass-TSS promptly 4. **Secure Keys**: Backup P2P and TSS keys securely 5. **Maintain Stake**: Keep stake above minimum to remain competitive # Overview This section covers how to build applications on MAP Protocol. ## Cross-chain Application Build omnichain DApps using MAP Omnichain Service (MOS): * [**Overview**](/develop/cross-chain-application/overview) - MOS concepts and components * [**Asset Cross-chain**](/develop/cross-chain-application/asset-cross-chain) - Transfer tokens between blockchains * [**Message Cross-chain**](/develop/cross-chain-application/message-cross-chain) - Call contracts or sync data across chains * [**Build OmniApp**](/develop/cross-chain-application/omni-app) - Complete step-by-step tutorial ## Other Resources | Topic | Description | | --------------------------------------------------- | ------------------------------------------ | | [Exchange Integration](/develop/integrate-exchange) | Guide for exchanges to integrate MAP token | | [Supra Oracle](/develop/supra) | Use Supra oracle on MAP Relay Chain | ## Advanced Documentation For in-depth technical documentation including protocol design, architecture details, and implementation specifications, please refer to **Developer Docs**, covering: * Protocol v1 (Light Client) and v2 (TSS) design * Relay Chain consensus and genesis contracts * Cross-chain verification mechanisms * Smart contract development fundamentals # Exchange Integration ## Overview The objective of this document is to provide a brief overview of how to integrate with the EVM-Compatible MAP Relay Chain. For teams that already support ETH, supporting the MAP Relay Chain is as straightforward as spinning up an MAP Relay Chain node (atlas) (which has the same API as go-ethereum) and populating MAP Relay Chain ID (22776) when constructing transactions. ## Integration using MAP Relay Chain Endpoints ### Running an atlas node you can get it from [source code](https://github.com/mapprotocol/atlas) or [release versin](https://github.com/mapprotocol/atlas/releases). from source code: ``` // make sure the golang env git clone https://github.com/mapprotocol/atlas.git cd atlas git checkout release_v1 make atlas ``` then start a node with the RPC service on the background,use `./build/bin/atlas -h` get more details. ``` ./build/bin/atlas --datadir ./data --gcmode "archive" --syncmode "full" --port 28360 --v5disc --http --http.addr "0.0.0.0" --http.api eth,web3,net,debug,txpool,header,istanbul --http.corsdomain "*" --http.vhosts "*" ``` ## Interacting with the Atlas Interacting with the Atlas node is identical to interacting with [go-ethereum](https://geth.ethereum.org/). You can find the reference material for Atlas API [here](/api-and-sdk/json-rpc/standard-rpc). Please note that personal\_ namespace is turned off by default. To turn it on, you need to pass the appropriate command line . ### Java SDK and Web3.js you can use the [Java SDK](https://github.com/web3j/web3j) and [web3.js](https://web3js.readthedocs.io/en/v1.2.9/) libs interacting with the atlas. If you plan on extracting data from the Atlas into your own systems using golang, we recommend using our custom [ethclient](https://github.com/mapprotocol/compass/tree/main/pkg/ethclient). ### Constructing transactions MAP Relay chain transactions are identical to standard EVM transactions with one exceptions:: ``` They must be signed with MAP Relay Chain ChainID (22776). ``` For development purposes, MAP Relay Chain supports all the popular tooling for Ethereum,like as `MetaMask and Remix`,`Truffle` and `Hardhat`, so developers familiar with Ethereum and Solidity can feel right at home. We are compatible with the improvement of Ethereum eip1559, and set the minimum base fee to 100GWei. ps: MAP Relay Chain consensus provides fast and irreversible finality with 5 seconds. To query the most up-to-date finalized block, query any value (i.e. block, balance, state, etc.) with the latest parameter. # Cross-chain Application # Overview ## Introduction MAP Omnichain Service (MOS) provides common modules for building cross-chain DApps, lowering the development threshold. MOS supports two types of cross-chain operations: * **Asset Cross-chain**: Transfer tokens between different blockchains * **Message Cross-chain**: Call contracts or sync data across chains ## Core Components ### MOS Relay MOS Relay is the main contract on MAP Relay Chain, responsible for: * Processing cross-chain transfers from users * Calling LightNodeManager to verify messages * Forwarding transactions to other chain's MOS contracts * Managing token minting/burning and Vault permissions * Handling fee distribution ### MOS MOS is the main contract on source/destination chains, responsible for: * Processing cross-chain transfers from users * Calling LightNode to verify MAP Relay Chain transactions * Parsing cross-chain events ### Messenger Messenger is an independent inter-chain program that: * Listens to events on source chains * Builds Merkle proofs on source chain's ledger * Transmits messages and proofs to destination chain * Prepays gas fees and earns rewards **Key Properties:** * As long as one honest Messenger works, all cross-chain messages can be transferred * Malicious Messenger attacks only cause verification failure, not asset loss * Messenger SDK is open to DApp developers ### Vault Vault is the equity token contract for each cross-chain token: * Stakes user liquidity, issues VToken * Records cross-chain fees and distributes to liquidity providers * Handles liquidity withdrawal and transfer ### Fee Fee contract manages cross-chain fee collection and distribution: * Sets fee distribution ratio for Vault, Relay, and Protocol * Sets fee charging standards ## Proof Verification Cross-chain data verification flow: 1. Verify Proof in transaction body 2. Prove transaction body can construct ReceiptRoot 3. Prove ReceiptRoot exists in block header 4. Verify header legitimacy against LightNode's stored headers ## Cross-chain Types | Type | Description | Use Case | | --------------------------------------------------------------------------- | ------------------------------ | ------------------ | | [Asset Cross-chain](/develop/cross-chain-application/asset-cross-chain) | Transfer tokens between chains | Token bridges, DEX | | [Message Cross-chain](/develop/cross-chain-application/message-cross-chain) | Call contracts or sync data | Omnichain DApps | ## Contract Addresses See [v1 Contracts](https://github.com/mapprotocol/docs/blob/master/develop/network/v1-contracts.md) for MOS contract addresses on supported chains. ## Getting Started * [Asset Cross-chain Guide](/develop/cross-chain-application/asset-cross-chain) * [Message Cross-chain Guide](/develop/cross-chain-application/message-cross-chain) * [Build OmniApp Tutorial](https://github.com/mapprotocol/docs/blob/master/develop/cross-chain-app/omni-app.md) # Asset Cross-chain Transfer tokens between different blockchains using MOS. ## How It Works ![MOS Flow](/files/rAQwCyBFXO45cNHgN4ea) ### Transfer Out (Source Chain) 1. User authorizes asset deduction 2. User calls MOS contract specifying target chainId and amount 3. Contract maps token to target chain, calculates fees 4. Generates order info and emits `transferOut` event ### Relay (MAP Relay Chain) 1. Messenger detects `transferOut` event on source chain 2. Messenger builds Merkle proof 3. Messenger calls `transferIn` on MAP Relay Chain 4. MOS Relay verifies proof via Light Client 5. If not final destination, emits new `transferOut` event ### Transfer In (Destination Chain) 1. Messenger detects event on MAP Relay Chain 2. Messenger builds Merkle proof 3. Messenger calls `transferIn` on destination chain 4. MOS verifies proof via Light Client 5. Transfers assets to user ## Example: Transfer 100 USDC from Ethereum to BSC **Step 1: Lock on Ethereum** Alice calls `transferOutToken` on Ethereum MOS, locking 100 USDC. **Step 2: Relay** Messenger automatically relays the transaction through MAP Relay Chain. **Step 3: Receive on BSC** Alice receives 100 USDC on BSC. She only sent one transaction. ## Contract Interface ```solidity interface IMOS { // Transfer token to another chain function transferOutToken( address _token, bytes memory _to, uint256 _amount, uint256 _toChain ) external; // Transfer native token to another chain function transferOutNative( bytes memory _to, uint256 _toChain ) external payable; // Deposit token to vault (provide liquidity) function depositToken( address _token, address _to, uint256 _amount ) external; // Deposit native token to vault function depositNative(address _to) external payable; // Check if token is bridgeable to target chain function isBridgeable( address _token, uint256 _toChain ) external view returns (bool); } ``` ## Usage Example ```solidity // Transfer 100 USDC to BSC IERC20(usdcAddress).approve(mosAddress, 100e6); IMOS(mosAddress).transferOutToken( usdcAddress, // token abi.encodePacked(to), // receiver on target chain 100e6, // amount 56 // BSC chain id ); // Transfer native token (e.g., ETH) to BSC IMOS(mosAddress).transferOutNative{value: 1 ether}( abi.encodePacked(to), // receiver 56 // BSC chain id ); ``` ## Contract Addresses See [v1 Contracts](/network/v1-contracts) for MOS contract addresses on supported chains. # Message Cross-chain Send cross-chain messages to call contracts or sync data across chains. ## Overview MOS Message enables: * Call contracts on chain B from chain A * Sync data changes from chain A to chain B MOS uses MAP Protocol Light Client to verify cross-chain message transactions, ensuring authenticity and on-chain traceability. ## Prerequisites * Application must be on a MAP Protocol supported chain * Cross-chain executable contract must authorize the MOS contract * Both source and destination chains must have MOS Message contracts deployed ## How It Works ### On Source Chain 1. DApp prepares cross-chain message and target chain callData 2. DApp calls MOS `transferOut` method, paying cross-chain gas fee 3. MOS emits cross-chain message log ### On MAP Relay Chain 1. Messenger detects message log on source chain 2. Messenger builds proof data and calls `transferIn` on MOS Relay 3. MOS Relay verifies via Light Client 4. If MAP Relay Chain is destination, executes call; otherwise emits new event ### On Destination Chain 1. Messenger detects message log on MAP Relay Chain 2. Messenger builds proof and calls `transferIn` on destination MOS 3. MOS verifies message via Light Client 4. Executes cross-chain contract call ## Message Types ```solidity enum MessageType { CALLDATA, // Execute calldata directly MESSAGE // Call mapoExecute interface } ``` ### CALLDATA Mode Target contract method is called directly with encoded calldata. ### MESSAGE Mode Target contract must implement `IMapoExecutor` interface: ```solidity interface IMapoExecutor { function mapoExecute( uint256 _fromChain, uint256 _toChain, bytes calldata _fromAddress, bytes32 _orderId, bytes calldata _message ) external returns (bytes memory); } ``` ## Contract Interface ```solidity interface IMOSV3 { struct MessageData { bool relay; // Use relay chain for execution MessageType msgType; // CALLDATA or MESSAGE bytes target; // Target contract address bytes payload; // Cross-chain data uint256 gasLimit; // Gas limit on target chain uint256 value; // Native token amount (currently 0) } // Send cross-chain message function transferOut( uint256 toChain, bytes memory messageData, address feeToken ) external payable returns (bytes32); // Get cross-chain fee function getMessageFee( uint256 toChain, address feeToken, uint256 gasLimit ) external view returns (uint256, address); // Set trusted source address function addRemoteCaller( uint256 _fromChain, bytes memory _fromAddress, bool _tag ) external; } ``` ## Usage Example ### Send Cross-chain Message (CALLDATA Mode) ```solidity contract MyDApp { IMOSV3 public mos; function sendCrossChain( uint256 _toChainId, bytes memory _target, uint256 _number ) external payable { // Encode target method call bytes memory payload = abi.encodeWithSelector( ITarget.crossChainAdd.selector, _number ); // Build MessageData IMOSV3.MessageData memory messageData = IMOSV3.MessageData({ relay: false, msgType: IMOSV3.MessageType.CALLDATA, target: _target, payload: payload, gasLimit: 500000, value: 0 }); // Get fee (uint256 fee,) = mos.getMessageFee(_toChainId, address(0), 500000); // Send cross-chain message mos.transferOut{value: fee}( _toChainId, abi.encode(messageData), address(0) ); } } ``` ### Receive Cross-chain Message (Target Contract) ```solidity contract TargetContract { IMOSV3 public mos; uint256 public cumulativeResult; // For CALLDATA mode - called directly by MOS function crossChainAdd(uint256 _number) external { require(msg.sender == address(mos), "only MOS"); cumulativeResult += _number; } // For MESSAGE mode - must implement IMapoExecutor function mapoExecute( uint256 _fromChain, uint256 _toChain, bytes calldata _fromAddress, bytes32 _orderId, bytes calldata _message ) external returns (bytes memory) { require(msg.sender == address(mos), "only MOS"); uint256 number = abi.decode(_message, (uint256)); cumulativeResult += number; return _message; } // Set trusted source contract function setTrustedSource( uint256 _chainId, bytes memory _sourceAddress ) external onlyOwner { mos.addRemoteCaller(_chainId, _sourceAddress, true); } } ``` ## Security Before receiving cross-chain messages, the target contract must: 1. Call `addRemoteCaller` to trust the source chain contract address 2. Verify `msg.sender == mos` in receiving functions ## Complete Tutorial See [Build OmniApp](https://github.com/mapprotocol/docs/blob/master/develop/cross-chain-app/omni-app.md) for a complete step-by-step tutorial. # Build OmniApp ## 1.To determine the contract version and project name. ``` // SPDX-License-Identifier: MIT pragma solidity ^0.8.0; import "@openzeppelin/contracts/access/Ownable.sol"; contract OApp is Ownable { } ``` ## 2.Importing the "@mapprotocol/mos" module and importing the "IMOSV3.sol" interface would look like this: ``` // SPDX-License-Identifier: MIT pragma solidity ^0.8.0; import "@openzeppelin/contracts/access/Ownable.sol"; import "@mapprotocol/mos/contracts/interface/IMOSV3.sol"; contract OApp is Ownable { } ``` For contract details, please look this ## 3.Sure, let's add some code to ensure that our MOS can function correctly. ``` // SPDX-License-Identifier: MIT pragma solidity ^0.8.0; import "@openzeppelin/contracts/access/Ownable.sol"; import "@mapprotocol/mos/contracts/interface/IMOSV3.sol"; contract OApp is Ownable { IMOSV3 public mos; // Add the MOS contract address as a parameter in the constructor to ensure that the MOS // interface can be invoked. constructor(address _mos){ mos = IMOSV3(_mos); } } ``` ## 4.In the above, when deploying, we need to add the correct MOS contract address. Now, let's complete the DAPP required method. Our requirement is: to send a number on the source chain, and after execution on the target chain, the result will be accumulated with this number. ``` // This is a target chain method for accumulating numbers, which will store the accumulated // result in the mapping called "cumulativeResult." function crossChainAdd(uint256 _number) external { // To prevent arbitrary access to the method from addresses other than the target // chain's MOS contract, we restrict the method to only allow calls from the MOS // address for the accumulation. require(msg.sender == address(mos),"do not have permission"); cumulativeResult += _number; } // By using this method, you can retrieve the current result of cumulativeResult and verify // if the cross-chain accumulation has been executed. function getCumulativeResult() external view returns(uint256){ return cumulativeResult; } ``` ## 5. Now let's try how to complete a cross-chain transfer through MOSV3 ### 5.1 First, let's take a look at the standard interface of IMOSV3 as shown below. ``` enum MessageType { CALLDATA, MESSAGE } // @notice This is the configuration you need across the chain. // @param relay - When it is true, the relay chain is required to perform a special // execution to continue across the chain. // @param msgType - Different execution patterns of messages across chains. // @param target - The contract address of the target chain. // @param payload - Cross-chain data. // @param gasLimit - The gasLimit allowed to be consumed by an operation performed on the // target chain. // @param value - Collateral value cross-chain, currently not supported, default is 0. struct MessageData { bool relay; MessageType msgType; bytes target; bytes payload; uint256 gasLimit; uint256 value; } // @notice Initiate cross-chain transactions. Generate cross-chain logs. // @param toChain - Target chain chainID. // @param messageData - Structure MessageData encoding. // @param feeToken - In what Token would you like to pay the fee. function transferOut( uint256 toChain, bytes memory messageData, address feeToken ) external payable returns(bytes32); ``` ### 5.2 Through the standard interface, we can observe that transferOut requires three parameters. toChain represents the target chain's chainId, messageData is the encoded form of the struct MessageData, and feeToken is the token you wish to use for covering the execution fee on the target chain during cross-chain operations. All that's needed is for us to complete a pre-payment on the source chain. ### In our demonstration, we are exclusively using native tokens of the current chain. Therefore, for feeToken, we consistently input address(0). Now, let's explore the explanation below to determine the payment required for each cross-chain operation. ``` // @notice Gets the fee to cross to the target chain. // @param toChain - Target chain chainID. // @param feeToken - Token address that supports payment fee,if it's native, it's address(0). // @param gasLimit - The gasLimit allowed to be consumed by an operation performed on the target chain. function getMessageFee(uint256 toChain, address feeToken, uint256 gasLimit) external view returns(uint256, address); ``` Having read the comments for the getMessageFee interface in IMOSV3, we understand that the fee for each payment is determined by tochain and gasLimit. Given that the execution complexity on the target chain is not extensive, an estimated gasLimit of 500,000 is more than sufficient. Let's proceed to create a straightforward method for accurately obtaining \_getTransferOutFee. ``` // Similarly, this method is also intended to serve transferOut, and we will define it as internal as well. function _getTransferOutFee(uint256 _toChainId) internal view returns(uint256){ (uint256 amount,) = mos.getMessageFee(_toChainId,address(0),500000); return amount; } ``` ### 5.3 Continuing to review the standard interface of IMOSV3, we discern that there are two cross-chain modes, selected based on the MessageType enumeration. When opting for transferOut, it is necessary to accurately encode the struct MessageData. Let's begin by examining the construction of MessageData for cross-chain using the CALLDATA mode. ``` // This method is intended to retrieve the messageData parameter for transferOut, so it is // designed to serve internal contract functions. Therefore, we define it as internal. // @param _number Parameters for Cross-Chain Accumulation // @param _target Address for Cross-Chain Execution, with a data type of 'bytes' to ensure // compatibility with non-EVM chains function _getCalldataMessageData( uint256 _number, bytes memory _target ) internal pure returns(bytes memory) { // To obtain the payload field value of the CALLDATA cross-chain method, this is // the callcode that will be executed on the target chain. bytes memory payload = abi.encodeWithSelector(OAppSourceSender.crossChainAdd.selector,_number); // false indicates that there is no need for secondary execution on the relay. // IMOSV3.MessageType.CALLDATA is the option to select our cross-chain type. // IMOSV3.MessageType is an enumeration type. // 500000 is the maximum gasLimit estimated to be consumed by the execution of the // method on the target chain. IMOSV3.MessageData memory messageData = IMOSV3.MessageData(false,IMOSV3.MessageType.CALLDATA,_target,payload,500000,0); return abi.encode(messageData); } ``` 5.3.1 Preparations are complete, and now we proceed to finalize the cross-chain message method in the CALLDATA mode. ``` function sendCalldataCrossChain( uint256 _toChainId, uint256 _number, bytes memory _target ) external payable returns(bytes32) { bytes memory messageData = _getCalldataMessageData(_number,_target); uint256 fee = _getTransferOutFee(_toChainId); // Since we have chosen to use the native token of this chain to pay the fee, we will // copy the fee value to the value parameter when calling the method. // The three parameters of transferOut should have been understood clearly during our // construction process. bytes32 orderId = mos.transferOut{value:fee}(_tochainId, messageData, address(0)); // The returned orderId is a unique identifier assigned by MOS after a successful // transferOut call. It serves as a cross-chain unique identifier and will not be // repeated. return orderId; } ``` 5.3.2 When the source chain initiates a cross-chain request through the `sendCalldataCrossChain` method, the `crossChainAdd` on the target chain will be invoked by the MOS contract to fulfill the cross-chain accumulation requirements. Upon closer observation during the construction of the `MessageData`, we utilize the `encodeWithSelector` of the `crossChainAdd` method. This constitutes the entire process of initiating a cross-chain message from the source chain to executing it on the target chain under the CALLDATA mode. ``` function crossChainAdd(uint256 _number) external { // To prevent arbitrary access to the method from addresses other than the target // chain's MOS contract, we restrict the method to only allow calls from the MOS // address for the accumulation. require(msg.sender == address(mos),"do not have permission"); cumulativeResult += _number; } ``` ### 5.4 Above, we've completed cross-chain functionality in the CALLDATA mode. Now, let's proceed to construct the `MessageData` for the MESSAGE mode. ``` // This method is intended to retrieve the messageData parameter for transferOut, so it is // designed to serve internal contract functions. Therefore, we define it as internal. // @param _number // @param _target function _getMessageMessageData( uint256 _number, bytes memory _target ) internal pure returns(bytes memory) { // For the message's cross-chain method, we only need to encode the parameters // required for the cross-chain operation and do not need to include the method's // selector. bytes memory prePayload = abi.encode(_number); // Here, we are adding a cross-chain identifier to facilitate the organization of cross_chain messages. bytes memory payload = abi.encode(CROSS_CHIAN_MESSAGE,prePayload); // false indicates that there is no need for secondary execution on the relay. // IMOSV3.MessageType.MESSAGE is the option to select our cross-chain type. // IMOSV3.MessageType is an enumeration type. // 500000 is the maximum gasLimit estimated to be consumed by the execution of the // method on the target chain. IMOSV3.MessageData memory messageData = IMOSV3.MessageData(false,IMOSV3.MessageType.MESSAGE,_target,payload,500000,0); return abi.encode(messageData); } ``` Note: The cross-chain identifier is a `bytes32`, resembling something like`keccak256("Message(bytes32,bytes)")`, and its content is arbitrary. 5.4.1 Similarly, we finalize the cross-chain message method in the MESSAGE mode. ``` function sendMessageCrossChain( uint256 _toChainId, uint256 _number, bytes memory _target ) external payable returns(bytes32) { bytes memory messageData = _getMessageMessageData(_number,_target); uint256 fee = _getTransferOutFee(_toChainId); // Since we have chosen to use the native token of this chain to pay the fee, we will // copy the fee value to the value parameter when calling the method. // The three parameters of transferOut should have been understood clearly during our // construction process. bytes32 orderId = mos.transferOut{value:fee}(_tochainId, messageData, address(0)); // The returned orderId is a unique identifier assigned by MOS after a successful // transferOut call. It serves as a cross-chain unique identifier and will not be // repeated. return orderId; } ``` 5.4.2 Take note, now we move on to accomplish the execution of cross-chain using the MESSAGE mode on the target chain. Employing the MESSAGE mode for cross-chain necessitates the implementation of a specific method within the target contract. For more details, please refer to [IMapoExecutor](https://github.com/mapprotocol/mapo-service-contracts/blob/main/evm/contracts/interface/IMapoExecutor.sol) ``` // After the MESSAGE cross-chain, the method will be directly invoked by the MOS contract. // Parameters such as _fromChain, _toChain, _fromAddress, and _orderId can be optionally // passed and ignored if not used. function mapoExecute( uint256 _fromChain, uint256 _toChain, bytes calldata _fromAddress, bytes32 _orderId, bytes calldata _message ) external override returns(bytes memory newMessage){ // Check the _orderId to determine whether this method has been called and executed // already, and prevent duplicate calls. require(!orderList[_orderId],"The orderId is invalid"); // Firstly, decipher the cross-chain type identifier to retrieve the required cross-chain data. (bytes32 typeTag,bytes memory payload) = abi.decode(_message,(bytes32,bytes)); //decode number uint256 number = abi.decode(payload,(uint256)); // Completed the accumulation requirement. cumulativeResult += number; // Mark _orderId as executed. orderList[_orderId] = true; return _message; } ``` 5.4.3 When you utilize the MESSAGE mode for cross-chain transactions from the source chain, while constructing the `MessageData`, only encode the data required by the target chain. Consequently, on the target chain, the `mapoExecute` method will be invoked by MOS in a predetermined manner. In this method, you can incorporate your unique logic and conditions. The above explanation provides a basic demonstration of the complete process of cross-chain using the MESSAGE mode. ## 6.In step 5, we've individually completed two distinct forms of cross-chain methods. Now, let's attempt to use a single method to achieve selectable cross-chain modes. Previously, the cross-chain transaction fees had to be provided alongside the cross-chain process. This time, we will explore an alternative approach. ``` // Enable the contract to accept native tokens of this chain. receive() external payable {} // The "tag" serves as a selection option for the cross-chain mode. If you wish to use the // Message mode for cross-chain, input 1. function sendCrossChain( uint256 _toChainId, uint256 _number, bytes memory _target, uint256 _tag ) external returns(bytes32) { bytes memory messageData; if(_tag == 1){ messageData = _getMessageMessageData(_number,_target); }else{ messageData = _getCalldataMessageData(_number,_target); } uint256 fee = getTransferOutFee(_toChainId); bytes32 orderId = mos.transferOut{value:fee}(_toChainId, messageData, address(0)); return orderId; } ``` Note: When using this method for cross-chain transactions, you only need to provide a small fee to the contract in advance. There's no need to include transaction fees during the actual cross-chain process. ## 7.It seems that we have completed a cross-chain DAPP contract, but don't rush, there is one more crucial step. MOS has a clever permission verification process, which requires each cross-chain contract to autonomously grant permissions to the source chain addresses. Let's complete this step. ``` // Fill in the source chain's ID and address, and set the tag to true to indicate a // willingness to trust messages coming from this source chain. With this, MOS can // successfully execute the cross-chain call. function setTrustFromAddress(uint256 _sourceChainId, bytes memory _sourceAddress, bool _tag) external onlyOwner { mos.addRemoteCaller(_sourceChainId,_fromAddress,_tag); } // This method can be used to check if the _targetAddress on the target chain trusts the // sourceAddress from the source chain. function getTrustFromAddress(address _targetAddress,uint256 _sourceChainId,bytes memory _sourceAddress) external view returns(bool){ return mos.getExecutePermission(_targetAddress,_sourceChainId,_sourceAddress); } ``` ## 8.We have completed the development of a cross-chain DAPP contract. Now, let's take a look at the complete contract code. ### 8.1Let's take a look at the contract on the source chain responsible for sending cross-chain requests. ``` // SPDX-License-Identifier: MIT pragma solidity ^0.8.0; import "@openzeppelin/contracts/access/Ownable.sol"; import "@mapprotocol/mos/contracts/interface/IMOSV3.sol"; contract OAppSourceSender is Ownable { IMOSV3 public mos; uint256 public cumulativeResult; bytes32 public constant CROSS_CHIAN_MESSAGE = keccak256("Message(bytes32,bytes)"); receive() external payable {} constructor(address _mos){ mos = IMOSV3(_mos); } function crossChainAdd(uint256 _number) external { require(msg.sender == address(mos),"do not have permission"); cumulativeResult += _number; } function _getCalldataMessageData( uint256 _number, bytes memory _target ) internal pure returns(bytes memory) { bytes memory payload = abi.encodeWithSelector(OAppSourceSender.crossChainAdd.selector,_number); IMOSV3.MessageData memory messageData = IMOSV3.MessageData(false,IMOSV3.MessageType.CALLDATA,_target,payload,500000,0); return abi.encode(messageData); } function _getMessageMessageData( uint256 _number, bytes memory _target ) internal pure returns(bytes memory) { bytes memory prePayload = abi.encode(_number); bytes memory payload = abi.encode(CROSS_CHIAN_MESSAGE,prePayload); IMOSV3.MessageData memory messageData = IMOSV3.MessageData(false,IMOSV3.MessageType.MESSAGE,_target,payload,500000,0); return abi.encode(messageData); } function getTransferOutFee(uint256 _toChainId) public view returns(uint256){ (uint256 amount,) = mos.getMessageFee(_toChainId,address(0),500000); return amount; } function sendCalldataCrossChain( uint256 _toChainId, uint256 _number, bytes memory _target ) external payable returns(bytes32) { bytes memory messageData = _getCalldataMessageData(_number,_target); uint256 fee = getTransferOutFee(_toChainId); bytes32 orderId = mos.transferOut{value:fee}(_toChainId, messageData, address(0)); return orderId; } function sendMessageCrossChain( uint256 _toChainId, uint256 _number, bytes memory _target ) external payable returns(bytes32) { bytes memory messageData = _getMessageMessageData(_number,_target); uint256 fee = getTransferOutFee(_toChainId); bytes32 orderId = mos.transferOut{value:fee}(_toChainId, messageData, address(0)); return orderId; } function sendCrossChain( uint256 _toChainId, uint256 _number, bytes memory _target, uint256 _tag ) external returns(bytes32) { bytes memory messageData; if(_tag == 1){ messageData = _getMessageMessageData(_number,_target); }else{ messageData = _getCalldataMessageData(_number,_target); } uint256 fee = getTransferOutFee(_toChainId); bytes32 orderId = mos.transferOut{value:fee}(_toChainId, messageData, address(0)); return orderId; } } ``` ### 8.2 Below is the contract on our target chain responsible for receiving and executing cross-chain messages. ``` // SPDX-License-Identifier: MIT pragma solidity ^0.8.0; import "@openzeppelin/contracts/access/Ownable.sol"; import "@mapprotocol/mos/contracts/interface/IMOSV3.sol"; import "@mapprotocol/mos/contracts/interface/IMapoExecutor.sol"; contract OAppTargetReceiver is Ownable, IMapoExecutor{ IMOSV3 public mos; uint256 public cumulativeResult; mapping(bytes32 => bool) orderList; constructor(address _mos){ mos = IMOSV3(_mos); } function crossChainAdd(uint256 _number) external { require(msg.sender == address(mos),"do not have permission"); cumulativeResult += _number; } function mapoExecute( uint256 _fromChain, uint256 _toChain, bytes calldata _fromAddress, bytes32 _orderId, bytes calldata _message ) external returns(bytes memory newMessage){ require(!orderList[_orderId],"The orderId is invalid"); (bytes32 typeTag,bytes memory payload) = abi.decode(_message,(bytes32,bytes)); uint256 number = abi.decode(payload,(uint256)); cumulativeResult += number; orderList[_orderId] = true; return _message; } function getCumulativeResult() external view returns(uint256){ return cumulativeResult; } function setTrustFromAddress(uint256 _sourceChainId, bytes memory _sourceAddress, bool _tag) external onlyOwner { mos.addRemoteCaller(_sourceChainId,_sourceAddress,_tag); } function getTrustFromAddress(address _targetAddress,uint256 _sourceChainId,bytes memory _sourceAddress) external view returns(bool){ return mos.getExecutePermission(_targetAddress,_sourceChainId,_sourceAddress); } } ``` ### 9.Great! Above, we have completed the implementation of a simple cross-chain DAPP contract for accumulation. Let's now go through the complete process of interacting with the contract. ``` 1. Deploy our OAppSourceSender contract on the EVM source chain A to obtain the Source-contract-address. 2. Similarly, deploy our OAppTargetReceiver contract on the EVM target chain to obtain the Target-contract-address. 3. Invoke the setTrustFromAddress method on the target chain to set a security flag for Source-contract-address. 4. Call getTrustFromAddress on the target chain to verify if the setup is completed. 5. Call getCumulativeResult on the target chain to retrieve the current result. 6. Call getTransferOutFee on the source chain to determine the required fee for the target chain. 7. Initiate a cross-chain request on the source chain by using the sendCalldataCrossChain method or the sendMessageCrossChain method. 8. Alternatively, transfer a certain fee to Source-contract-address and initiate a cross-chain request by calling sendCrossChain. 9. After observing the completion of the cross-chain transaction on the cross-chain explorer, call the getTrustFromAddress method on the target chain to check if the result has been successfully accumulated. ``` # Supra Oracle [Supra](https://supra.com) is a novel, high-throughput Oracle & IntraLayer that has been deployed on MAP Protocol: A vertically integrated toolkit of cross-chain solutions (data oracles, asset bridges, automation network, and more) that interlink all blockchains, public (L1s and L2s) or private (enterprises). Supra provides decentralized Oracle price feeds that can be used for on-chain and off-chain use cases such as spot and perpetual DEXes, lending protocols, and payments protocols. Supra’s oracle chain and consensus algorithm make it the fastest-to-finality oracle provider, with layer-1 security guarantees. The pull oracle has a sub-second response time. Aside from speed and security, Supra’s rotating node architecture gathers data from 40+ data sources and applies a robust calculation methodology to get the most accurate value. The node provenance on the data dashboard also provides a fully transparent historical audit trail. Supra’s Distributed Oracle Agreement (DORA) paper was accepted into ICDCS 2023, the oldest distributed systems conference. Check out more developer docs [here](https://supra.com/docs/overview/) # JSON-RPC # Standard RPC ## The default block parameter The following methods have an extra default block parameter: * [eth\_getBalance](#eth_getbalance) * [eth\_getCode](https://github.com/mapprotocol/docs/blob/master/sdk/eth_getcode/README.md) * [eth\_getTransactionCount](https://github.com/mapprotocol/docs/blob/master/sdk/eth_gettransactioncount/README.md) * [eth\_getStorageAt](https://github.com/mapprotocol/docs/blob/master/sdk/eth_getstorageat/README.md) * [eth\_call](https://github.com/mapprotocol/docs/blob/master/sdk/eth_call/README.md) When requests are made that act on the state of ethereum, the last default block parameter determines the height of the block. The following options are possible for the defaultBlock parameter: * `HEX String` - an integer block number * `String "earliest"` for the earliest/genesis block * `String "latest"` - for the latest mined block * `String "pending"` - for the pending state/transactions ## web3 ### web3\_clientVersion Returns the current client version. #### Parameters none #### Returns `String` - The current client version. #### Example ```js // Request curl -X POST --data '{"jsonrpc":"2.0","method":"web3_clientVersion","params":[],"id":1}' // Result { "jsonrpc": "2.0", "id": 1, "result": "atlas/v0.3.2-stable/linux-amd64/go1.17.1" } ``` ### web3\_sha3 Returns Keccak-256 (*not* the standardized SHA3-256) of the given data. #### Parameters 1. `DATA` - the data to convert into a SHA3 hash. #### Example Parameters ```js params: [ "0x68656c6c6f20776f726c64" ] ``` #### Returns `DATA` - The SHA3 result of the given string. #### Example ```js // Request curl -X POST --data '{"jsonrpc":"2.0","method":"web3_sha3","params":["0x68656c6c6f20776f726c64"],"id":1}' // Result { "jsonrpc": "2.0", "id": 1, "result": "0x47173285a8d7341e5e972fc677286384f802f8ef42a5ec5f03bbfa254cb01fad" } ``` ## net ### net\_version Returns the current network id. #### Parameters none #### Returns `String` - The current network id. * `"22776"`: Mainnet * `"212"`: Testnet * `"213"`: Devnet #### Example ```js // Request curl -X POST --data '{"jsonrpc":"2.0","method":"net_version","params":[],"id":1}' // Result { "jsonrpc": "2.0", "id": 1, "result": "22776" } ``` ### net\_listening Returns `true` if client is actively listening for network connections. #### Parameters none #### Returns `Boolean` - `true` when listening, otherwise `false`. #### Example ```js // Request curl -X POST --data '{"jsonrpc":"2.0","method":"net_listening","params":[],"id":1}' // Result { "jsonrpc": "2.0", "id": 1, "result": true } ``` ### net\_peerCount Returns number of peers currently connected to the client. #### Parameters none #### Returns `QUANTITY` - integer of the number of connected peers. #### Example ```js // Request curl -X POST --data '{"jsonrpc":"2.0","method":"net_peerCount","params":[],"id":1}' // Result { "jsonrpc": "2.0", "id": 1, "result": "0x4" } ``` ## eth ### eth\_gasPrice Returns the current price per gas in wei. #### Parameters none #### Returns `QUANTITY` - integer of the current gas price in wei. #### Example ```js // Request curl -X POST --data '{"jsonrpc":"2.0","method":"eth_gasPrice","params":[],"id":1}' // Result { "id":1, "jsonrpc": "2.0", "result": "0x77359400" } ``` ### eth\_maxPriorityFeePerGas Returns a fee per gas that is an estimate of how much you can pay as a priority fee, or "tip", to get a transaction included in the current block. #### Parameters none #### Returns `QUANTITY` - the estimated priority fee per gas. #### Example ```js // Request curl -X POST --data '{"jsonrpc":"2.0","method":"eth_maxPriorityFeePerGas","params":[],"id":1}' // Result { "jsonrpc": "2.0", "id": 1, "result": "0x3b9aca00" } ``` ### eth\_syncing Returns an object with data about the sync status or `false`. #### Parameters none #### Returns `Object|Boolean`, An object with sync status data or `FALSE`, when not syncing: * `startingBlock`: `QUANTITY` - The block at which the import started (will only be reset, after the sync reached his head) * `currentBlock`: `QUANTITY` - The current block, same as eth\_blockNumber * `highestBlock`: `QUANTITY` - The estimated highest block * `pulledStates`: `String` -already complete state * `knownStates`: `String` -already know state startingBlock: QUANTITY - The block at which the import started (will only be reset, after the sync reached his head) currentBlock: QUANTITY - The current block, same as eth\_blockNumber highestBlock: QUANTITY - The estimated highest block #### Example ```js // Request curl -X POST --data '{"jsonrpc":"2.0","method":"eth_syncing","params":[],"id":1}' // Result { "jsonrpc": "2.0", "id": 1, "result": { "currentBlock": "0x2bb", "highestBlock": "0x2bd", "knownStates": "0x0", "pulledStates": "0x0", "startingBlock": "0x22b" } } // Or when not syncing { "id":1, "jsonrpc": "2.0", "result": false } ``` ### eth\_accounts Returns a list of addresses owned by client. #### Parameters none #### Returns `Array of DATA`, 20 Bytes - addresses owned by the client. #### Example ```js // Request curl -X POST --data '{"jsonrpc":"2.0","method":"eth_accounts","params":[],"id":1}' // Result { "id":1, "jsonrpc": "2.0", "result": ["0x84d46b3055454646a419d023f73472561b6cf20f"] } ``` ### eth\_blockNumber Returns the number of most recent block. #### Parameters none #### Returns `QUANTITY` - integer of the current block number the client is on. #### Example ```js // Request curl -X POST --data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' // Result { "jsonrpc": "2.0", "id": 1, "result": "0x9ff" } ``` ### eth\_getBalance Returns the balance of the account of given address. #### Parameters DATA, 20 Bytes - address to check for balance. QUANTITY|TAG - integer block number, or the string "latest", "earliest" or "pending", see the [default block parameter](#the-default-block-parameter). #### Returns `QUANTITY` - integer of the current block number the client is on. #### Example ```js // Request curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getBalance","params":["0x84d46b3055454646a419d023f73472561b6cf20f", "latest"],"id":1}' // Result { "jsonrpc": "2.0", "id": 1, "result": "0x0" } ``` ### eth\_getBlockByNumber Returns information about a block by block number. #### Parameters `QUANTITY|TAG` - integer of a block number, or the string "earliest", "latest" or "pending", as in the default block parameter. `Boolean` - If true it returns the full transaction objects, if false only the hashes of the transactions. #### Returns `Object` - A block object, or null when no block was found: - `number`: QUANTITY - the block number. null when its pending block. - `hash`: DATA, 32 Bytes - hash of the block. null when its pending block. - `parentHash`: DATA, 32 Bytes - hash of the parent block. - `nonce`: DATA, 8 Bytes - hash of the generated proof-of-work. null when its pending block. - `logsBloom`: DATA, 256 Bytes - the bloom filter for the logs of the block. null when its pending block. - `transactionsRoot`: DATA, 32 Bytes - the root of the transaction trie of the block. - `stateRoot`: DATA, 32 Bytes - the root of the final state trie of the block. - `receiptsRoot`: DATA, 32 Bytes - the root of the receipts trie of the block. - `miner`: DATA, 20 Bytes - the address of the beneficiary to whom the mining rewards were given. - `totalDifficulty`: QUANTITY - integer of the total difficulty of the chain until this block. - `extraData`: DATA - the “extra data” field of this block. - `size`: QUANTITY - integer the size of this block in bytes. - `gasLimit`: QUANTITY - the maximum gas allowed in this block. - `gasUsed`: QUANTITY - the total used gas by all transactions in this block. - `timestamp`: QUANTITY - the unix timestamp for when the block was collated. - `transactions`: Array - Array of transaction objects, or 32 Bytes transaction hashes depending on the last given parameter. - `baseFeePerGas`: QUANTITY - The base fee is the bare minimum you will be charged to send a transaction on the network. #### Example ```js // Request curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getBlockByNumber","params":["0x1", true],"id":1}}' // Result { "jsonrpc": "2.0", "id": 1, "result": { "baseFeePerGas": "0x3b9aca00", "extraData": "0xd8820100846765746888676f312e31352e368664617277696e00000000000000f87ec0c080b8413628b60a5e8d7a3e8b20d7afafbaee473814f7c20a400bbfb57cd4b388e0962d4c44720c2b58aece9d82cd2807d524237170c041ef02326365c40d10cdffa80000f307b0a5abe24b01c5f800d88d5b350bc781723283f870feab4f683571b585447b4909b9bd72201aa5dd6d99a349e4dc6d660006c3808080", "gasLimit": "0x2fa31c5", "gasUsed": "0x0", "hash": "0xdddfede981cb797b5492be3b6a238db872ae3260bb19472f06dfa5b2214850dc", "logsBloom": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000", "miner": "0x2dc45799000ab08e60b7441c36fcc74060ccbe11", "mixHash": "0x0000000000000000000000000000000000000000000000000000000000000000", "nonce": "0x0000000000000000", "number": "0x1", "parentHash": "0x22edf1b785c14db4fb893e6b01e74ad9ce01ece81de7c4a49c0ee594852c70cc", "receiptsRoot": "0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421", "size": "0x2c7", "stateRoot": "0x71e4afa51d013ff42245c45f840e14117d692befd8a7fa52354bf61480d84f12", "timestamp": "0x619da786", "totalDifficulty": "0x2", "transactions": [], "transactionsRoot": "0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421" } } ``` ### eth\_getBlockByHash Returns information about a block by block hash. #### Parameters `DATA`, 32 Bytes - Hash of a block. `Boolean` - If true it returns the full transaction objects, if false only the hashes of the transactions. #### Returns See [eth\_getBlockByNumber](#eth_getblockbynumber) #### Example ```js // Request curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getBlockByHash","params":["0xdddfede981cb797b5492be3b6a238db872ae3260bb19472f06dfa5b2214850dc", true],"id":1}}' ``` Result See [eth\_getBlockByNumber](#eth_getblockbynumber) ### eth\_getCode Returns code at a given address. #### Parameters 1. `DATA`, 20 Bytes - address. 2. `QUANTITY|TAG` - integer block number, or the string `"latest"`, `"earliest"` or `"pending"`, see the [default block parameter](#the-default-block-parameter). #### Returns `DATA` - the code from the given address. #### Example ```js // Request curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getCode","params":["0xa94f5374fce5edbc8e2a8697c15331677e6ebf0b", "0x2"],"id":1}' // Result { "id":1, "jsonrpc": "2.0", "result": "0x600160008035811a818181146012578301005b601b6001356025565b8060005260206000f25b600060078202905091905056" } ``` ### eth\_getStorageAt Returns the value from a storage position at a given address. #### Parameters 1. `DATA`, 20 Bytes - address of the storage. 2. `QUANTITY` - integer of the position in the storage. 3. `QUANTITY|TAG` - integer block number, or the string `"latest"`, `"earliest"` or `"pending"`, see the [default block parameter](#the-default-block-parameter) #### Returns `DATA` - the value at this storage position. #### Example Calculating the correct position depends on the storage to retrieve. Consider the following contract deployed at `0x295a70b2de5e3953354a6a8344e616ed314d7251` by address `0x391694e7e0b0cce554cb130d723a9d27458f9298`. ``` contract Storage { uint pos0; mapping(address => uint) pos1; function Storage() { pos0 = 1234; pos1[msg.sender] = 5678; } } ``` Retrieving the value of pos0 is straight forward: ```js curl -X POST --data '{"jsonrpc":"2.0", "method": "eth_getStorageAt", "params": ["0x295a70b2de5e3953354a6a8344e616ed314d7251", "0x0", "latest"], "id": 1}' localhost:8545 {"jsonrpc":"2.0","id":1,"result":"0x00000000000000000000000000000000000000000000000000000000000004d2"} ``` Retrieving an element of the map is harder. The position of an element in the map is calculated with: ```js keccack(LeftPad32(key, 0), LeftPad32(map position, 0)) ``` This means to retrieve the storage on pos1\["0x391694e7e0b0cce554cb130d723a9d27458f9298"] we need to calculate the position with: ```js keccak(decodeHex("000000000000000000000000391694e7e0b0cce554cb130d723a9d27458f9298" + "0000000000000000000000000000000000000000000000000000000000000001")) ``` The geth console which comes with the web3 library can be used to make the calculation: ```js > var key = "000000000000000000000000391694e7e0b0cce554cb130d723a9d27458f9298" + "0000000000000000000000000000000000000000000000000000000000000001" undefined > web3.sha3(key, {"encoding": "hex"}) "0x6661e9d6d8b923d5bbaab1b96e1dd51ff6ea2a93520fdc9eb75d059238b8c5e9" ``` Now to fetch the storage: ```js curl -X POST --data '{"jsonrpc":"2.0", "method": "eth_getStorageAt", "params": ["0x295a70b2de5e3953354a6a8344e616ed314d7251", "0x6661e9d6d8b923d5bbaab1b96e1dd51ff6ea2a93520fdc9eb75d059238b8c5e9", "latest"], "id": 1}' localhost:8545 {"jsonrpc":"2.0","id":1,"result":"0x000000000000000000000000000000000000000000000000000000000000162e"} ``` ### eth\_call Executes a new message call immediately without creating a transaction on the block chain. #### Parameters 1. `Object` - The transaction call object * `from`: `DATA`, 20 Bytes - (optional) The address the transaction is sent from. * `to`: `DATA`, 20 Bytes - The address the transaction is directed to. * `gas`: `QUANTITY` - (optional) Integer of the gas provided for the transaction execution. eth\_call consumes zero gas, but this parameter may be needed by some executions. * `gasPrice`: `QUANTITY` - (optional) Integer of the gasPrice used for each paid gas * `maxFeePerGas`: `QUANTITY` - It's just the sum of baseFeePerGas and maxPriorityFeePerGas: maxFeePerGas = baseFeePerGas + maxPriorityFeePerGas. * `maxPriorityFeePerGas`: `QUANTITY` - When you submit a transaction you will also provide a "tip" to the miner. This is the maxPriorityFeePerGas field. fork. * `value`: `QUANTITY` - (optional) Integer of the value sent with this transaction * `nonce`: `QUANTITY` - the number of transactions made by the sender prior to this one. * `data`: `DATA` - (optional) Hash of the method signature and encoded parameters * `input`: `DATA` - (optional) We accept "data" and "input" for backwards-compatibility reasons. "input" is the newer name and should be preferred by clients. 1. `QUANTITY|TAG` - integer block number, or the string `"latest"`, `"earliest"` or `"pending"`, see the [default block parameter](#the-default-block-parameter) #### Returns `DATA` - the return value of executed contract. #### Example ```json // Request curl -X POST --data '{ "id": 1, "jsonrpc": "2.0", "method": "eth_call", "params": [ { "from": "0xd13fe09e7a304709b1c4ed6bd3a2d6c272357bbb", "to": "0xd46e8dd67c5d32be8058bb8eb970870f07244567", "gas": "0x76c0", "gasPrice": "0x9184e72a000", "value": "0x9184e72a", "data": "0xd46e8dd67c5d32be8d46e8dd67c5d32be8058bb8eb970870f072445675058bb8eb970870f072445675" } ], }' // Result { "id":1, "jsonrpc": "2.0", "result": "0x" } ``` ### eth\_estimateGas Generates and returns an estimate of how much gas is necessary to allow the transaction to complete. The transaction will not be added to the blockchain. Note that the estimate may be significantly more than the amount of gas actually used by the transaction, for a variety of reasons including EVM mechanics and node performance. #### Parameters See [eth\_call](#eth_call) parameters, expect that all properties are optional. If no gas limit is specified geth uses the block gas limit from the pending block as an upper bound. As a result the returned estimate might not be enough to executed the call/transaction when the amount of gas is higher than the pending block gas limit. #### Returns `QUANTITY` - the amount of gas used. #### Example ```js // Request curl -X POST --data '{"jsonrpc":"2.0","method":"eth_estimateGas","params":[{"from": "0xd13fe09e7a304709b1c4ed6bd3a2d6c272357bbb","to": "0xd46e8dd67c5d32be8058bb8eb970870f07244567","gas": "0x76c0","gasPrice": "0x9184e72a000","value": "0x9184e72a","data": "0xd46e8dd67c5d32be8d46e8dd67c5d32be8058bb8eb970870f072445675058bb8eb970870f072445675"}, "latest"],"id":1}],"id":1}' // Result { "id":1, "jsonrpc": "2.0", "result": "0x5498" } ``` ### eth\_getBlockTransactionCountByNumber Returns the number of transactions in a block matching the given block number. #### Parameters 1. `QUANTITY|TAG` - integer of a block number, or the string `"earliest"`, `"latest"` or `"pending"`, as in the [default block parameter](#the-default-block-parameter). #### Returns `QUANTITY` - integer of the number of transactions in this block. #### Example ```js // Request curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getBlockTransactionCountByNumber","params":["0x1"],"id":1}' // Result { "jsonrpc": "2.0", "id": 1, "result": "0x0" } ``` ### eth\_getBlockTransactionCountByHash Returns the number of transactions in a block from a block matching the given block hash. #### Parameters 1. `DATA`, 32 Bytes - hash of a block. #### Returns `QUANTITY` - integer of the number of transactions in this block. #### Example ```js // Request curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getBlockTransactionCountByHash","params":["0xdddfede981cb797b5492be3b6a238db872ae3260bb19472f06dfa5b2214850dc"],"id":1}' // Result { "jsonrpc": "2.0", "id": 1, "result": "0x0" } ``` ### eth\_getTransactionByHash Returns the information about a transaction requested by transaction hash. #### Parameters 1. `DATA`, 32 Bytes - hash of a transaction #### Returns `Object` - A transaction object, or `null` when no transaction was found: * `blockHash`: `DATA`, 32 Bytes - hash of the block where this transaction was in. `null` when its pending. * `blockNumber`: `QUANTITY` - block number where this transaction was in. `null` when its pending. * `from`: `DATA`, 20 Bytes - address of the sender. * `gas`: `QUANTITY` - gas provided by the sender. * `gasPrice`: `QUANTITY` - gas price provided by the sender in Wei. * `maxFeePerGas`: `QUANTITY` - It's just the sum of baseFeePerGas and maxPriorityFeePerGas: maxFeePerGas = baseFeePerGas + maxPriorityFeePerGas. * `maxPriorityFeePerGas`: `QUANTITY` - When you submit a transaction you will also provide a "tip" to the miner. This is the maxPriorityFeePerGas field. fork. * `hash`: `DATA`, 32 Bytes - hash of the transaction. * `input`: `DATA` - the data send along with the transaction. * `nonce`: `QUANTITY` - the number of transactions made by the sender prior to this one. * `to`: `DATA`, 20 Bytes - address of the receiver. `null` when its a contract creation transaction. * `transactionIndex`: `QUANTITY` - integer of the transaction's index position in the block. `null` when its pending. * `value`: `QUANTITY` - value transferred in Wei. * `accessList`: * `chainId`: * `v`: `QUANTITY` - ECDSA recovery id * `r`: `DATA`, 32 Bytes - ECDSA signature r * `s`: `DATA`, 32 Bytes - ECDSA signature s * `payer`: `DATA`, 20 Bytes - address of the payer. * `fee`: `QUANTITY` - transaction fee in Wei. * `pv`: `QUANTITY` - ECDSA recovery id * `pr`: `DATA`, 32 Bytes - ECDSA signature pr * `ps`: `DATA`, 32 Bytes - ECDSA signature ps #### Example ```js // Request curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getTransactionByHash","params":["0x88df016429689c079f3b2f6ad39fa052532c56795b733da78a91ebe6a713944b"],"id":1}' // Result { "jsonrpc": "2.0", "id": 1, "result": { "blockHash": "0xe1773ed82b29bb3ee541966e4a8d26c0dc2da8efe8534eb51d0522566a744b0f", "blockNumber": "0x824", "from": "0xd13fe09e7a304709b1c4ed6bd3a2d6c272357bbb", "gas": "0x4b6ed", "gasPrice": "0xd09dc300", "maxFeePerGas": "0x10c388d00", "maxPriorityFeePerGas": "0x9502f900", "hash": "0x9b9e8bab3acd3c581bb3231c6f5d3a13dc57feb69ab8767929669e8a08185c9b", "input": "0x608060405234801561001057600080fd5b506104a4806100206000396000f3fe608060405234801561001057600080fd5b50600436106100365760003560e01c806306fdde031461003b578063c47f002714610059575b600080fd5b610043610075565b60405161005091906102b2565b60405180910390f35b610073600480360381019061006e9190610230565b610103565b005b6000805461008290610388565b80601f01602080910402602001604051908101604052809291908181526020018280546100ae90610388565b80156100fb5780601f106100d0576101008083540402835291602001916100fb565b820191906000526020600020905b8154815290600101906020018083116100de57829003601f168201915b505050505081565b806000908051906020019061011992919061011d565b5050565b82805461012990610388565b90600052602060002090601f01602090048101928261014b5760008555610192565b82601f1061016457805160ff1916838001178555610192565b82800160010185558215610192579182015b82811115610191578251825591602001919060010190610176565b5b50905061019f91906101a3565b5090565b5b808211156101bc5760008160009055506001016101a4565b5090565b60006101d36101ce846102f9565b6102d4565b9050828152602081018484840111156101ef576101ee61044e565b5b6101fa848285610346565b509392505050565b600082601f83011261021757610216610449565b5b81356102278482602086016101c0565b91505092915050565b60006020828403121561024657610245610458565b5b600082013567ffffffffffffffff81111561026457610263610453565b5b61027084828501610202565b91505092915050565b60006102848261032a565b61028e8185610335565b935061029e818560208601610355565b6102a78161045d565b840191505092915050565b600060208201905081810360008301526102cc8184610279565b905092915050565b60006102de6102ef565b90506102ea82826103ba565b919050565b6000604051905090565b600067ffffffffffffffff8211156103145761031361041a565b5b61031d8261045d565b9050602081019050919050565b600081519050919050565b600082825260208201905092915050565b82818337600083830152505050565b60005b83811015610373578082015181840152602081019050610358565b83811115610382576000848401525b50505050565b600060028204905060018216806103a057607f821691505b602082108114156103b4576103b36103eb565b5b50919050565b6103c38261045d565b810181811067ffffffffffffffff821117156103e2576103e161041a565b5b80604052505050565b7f4e487b7100000000000000000000000000000000000000000000000000000000600052602260045260246000fd5b7f4e487b7100000000000000000000000000000000000000000000000000000000600052604160045260246000fd5b600080fd5b600080fd5b600080fd5b600080fd5b6000601f19601f830116905091905056fea264697066735822122038d2501678007ade07a8a41476358bf19cd27e0f7ab6ced37416d4929d0507c164736f6c63430008070033", "nonce": "0x5", "to": null, "transactionIndex": "0x0", "value": "0x0", "type": "0x2", "accessList": [], "chainId": "0x58f8", "v": "0x0", "r": "0x285d9e04a338ba42bef91b35d2eb252a470b626dd4e93c530fc7b60b912bbcb9", "s": "0x1fafb42d72545deffb953d409ff44b68cff40a07454dab346df64c91f5e386fd" } } ``` ### eth\_getTransactionByBlockNumberAndIndex Returns information about a transaction by block number and transaction index position. #### Parameters 1. `QUANTITY|TAG` - a block number, or the string `"earliest"`, `"latest"` or `"pending"`, as in the [default block parameter](#the-default-block-parameter). 2. `QUANTITY` - the transaction index position. #### Returns See [eth\_getTransactionByHash](#eth_gettransactionbyhash) #### Example ```js // Request curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getTransactionByBlockNumberAndIndex","params":["0x29c", "0x0"],"id":1}' ``` Result see [eth\_getTransactionByHash](#eth_gettransactionbyhash) ### eth\_getTransactionByBlockHashAndIndex Returns information about a transaction by block hash and transaction index position. #### Parameters 1. `DATA`, 32 Bytes - hash of a block. 2. `QUANTITY` - integer of the transaction index position. #### Returns See [eth\_getTransactionByHash](#eth_gettransactionbyhash) #### Example ```js // Request curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getTransactionByBlockHashAndIndex","params":["0xc6ef2fc5426d6ad6fd9e2a26abeab0aa2411b7ab17f30a99d3cb96aed1d1055b", "0x0"],"id":1}' ``` Result see [eth\_getTransactionByHash](#eth_gettransactionbyhash) ### eth\_getTransactionCount Returns the number of transactions *sent* from an address. #### Parameters 1. `DATA`, 20 Bytes - address. 2. `QUANTITY|TAG` - integer block number, or the string `"latest"`, `"earliest"` or `"pending"`, see the [default block parameter](#the-default-block-parameter) #### Returns `QUANTITY` - integer of the number of transactions send from this address. #### Example ```js // Request curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getTransactionCount","params":["0xD13fE09E7A304709B1C4ed6Bd3a2D6C272357BBb","latest"],"id":1}' // Result { "jsonrpc": "2.0", "id": 1, "result": "0x6" } ``` ### eth\_getTransactionReceipt Returns the receipt of a transaction by transaction hash. **Note** That the receipt is not available for pending transactions. #### Parameters 1. `DATA`, 32 Bytes - hash of a transaction #### Example Parameters ```js params: [ '0xb903239f8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238' ] ``` #### Returns `Object` - A transaction receipt object, or `null` when no receipt was found: ``` - `blockHash`: `DATA`, 32 Bytes - hash of the block where this transaction was in. - `blockNumber`: `QUANTITY` - block number where this transaction was in. - `contractAddress `: `DATA`, 20 Bytes - The contract address created, if the transaction was a contract creation, otherwise `null`. - `cumulativeGasUsed `: `QUANTITY ` - The total amount of gas used when this transaction was executed in the block. - `effectiveGasPrice ` : `QUANTITY ` - effective gas price - `from`: `DATA`, 20 Bytes - address of the sender. - `to`: `DATA`, 20 Bytes - address of the receiver. null when it's a contract creation transaction. - `gasUsed `: `QUANTITY ` - The amount of gas used by this specific transaction alone. - `logs`: `Array` - Array of log objects, which this transaction generated. - `logsBloom`: `DATA`, 256 Bytes - Bloom filter for light clients to quickly retrieve related logs. - `transactionHash `: `DATA`, 32 Bytes - hash of the transaction. - `transactionIndex`: `QUANTITY` - integer of the transaction's index position in the block. - `type`: `QUANTITY` - transaction type, (0: LegacyTxType, 1: AccessListTxType, 2: DynamicFeeTxType) ``` It also returns *either* : ``` - `root` : `DATA` 32 bytes of post-transaction stateroot (pre Byzantium) - `status`: `QUANTITY` either `1` (success) or `0` (failure) ``` #### Example ```js // Request curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getTransactionReceipt","params":["0xb903239f8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238"],"id":1}' // Result { "jsonrpc": "2.0", "id": 1, "result": { "blockHash": "0xfbc61080bf5e44762b35b340d520bf729c68612ea40a8b87bfaa3120cef6901c", "blockNumber": "0x264b", "contractAddress": null, "cumulativeGasUsed": "0x5208", "effectiveGasPrice": "0x4190ab00", "from": "0xd13fe09e7a304709b1c4ed6bd3a2d6c272357bbb", "gasUsed": "0x5208", "logs": [], "logsBloom": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000", "status": "0x1", "to": "0xf0c8898b2016afa0ec5912413ebe403930446779", "transactionHash": "0xf15351ba1239fcc4452b507808cf4ec184e3c599f915eb783d05c719cf6afce4", "transactionIndex": "0x0", "type": "0x2" } } ``` ### eth\_sendTransaction Creates new message call transaction or a contract creation, if the data field contains code. #### Parameters 1. `Object` - The transaction object * `from`: `DATA`, 20 Bytes - (optional) The address the transaction is sent from. * `to`: `DATA`, 20 Bytes - The address the transaction is directed to. * `gas`: `QUANTITY` - (optional) Integer of the gas provided for the transaction execution. eth\_call consumes zero gas, but this parameter may be needed by some executions. * `gasPrice`: `QUANTITY` - (optional) Integer of the gasPrice used for each paid gas * `maxFeePerGas`: `QUANTITY` - It's just the sum of baseFeePerGas and maxPriorityFeePerGas: maxFeePerGas = baseFeePerGas + maxPriorityFeePerGas. * `maxPriorityFeePerGas`: `QUANTITY` - When you submit a transaction you will also provide a "tip" to the miner. This is the maxPriorityFeePerGas field. fork. * `value`: `QUANTITY` - (optional) Integer of the value sent with this transaction * `nonce`: `QUANTITY` - the number of transactions made by the sender prior to this one. * `data`: `DATA` - (optional) Hash of the method signature and encoded parameters * `input`: `DATA` - (optional) We accept "data" and "input" for backwards-compatibility reasons. "input" is the newer name and should be preferred by clients. #### Example Parameters ```js params: [{ "from": "0xf675187ff5b76d2430b353f6736aa051253118ee", "to": "0xD13fE09E7A304709B1C4ed6Bd3a2D6C272357BBb", "gas": "0x76c0", "gasPrice": "0x4190ab00", "value": "0xde0b6b3a7640000", "data": "0xd46e8dd67c5d32be8d46e8dd67c5d32be8058bb8eb970870f072445675058bb8eb970870f072445675" }] ``` #### Returns `DATA`, 32 Bytes - the transaction hash, or the zero hash if the transaction is not yet available. Use [eth\_getTransactionReceipt](#eth_gettransactionreceipt) to get the contract address, after the transaction was mined, when you created a contract. #### Example ```json // Request curl -X POST --data '{ "id": 1, "jsonrpc": "2.0", "method": "eth_sendTransaction", "params": [ { "from": "0xf675187ff5b76d2430b353f6736aa051253118ee", "to": "0xD13fE09E7A304709B1C4ed6Bd3a2D6C272357BBb", "gas": "0x76c0", "gasPrice": "0x4190ab00", "value": "0xde0b6b3a7640000", "data": "0xd46e8dd67c5d32be8d46e8dd67c5d32be8058bb8eb970870f072445675058bb8eb970870f072445675" } ] }' // Result { "id":1, "jsonrpc": "2.0", "result": "0xe670ec64341771606e55d6b4ca35a1a6b75ee3d5145a99d05921026d1527331" } ``` ### eth\_sign The sign method calculates an Ethereum specific signature with: sign(keccak256("\x19Ethereum Signed Message:\n" + len(message) + message))). By adding a prefix to the message makes the calculated signature recognisable as an Ethereum specific signature. This prevents misuse where a malicious DApp can sign arbitrary data (e.g. transaction) and use the signature to impersonate the victim. Note the address to sign with must be unlocked. #### Parameters account, message 1. `DATA`, 20 Bytes - address. 2. `DATA`, N Bytes - message to sign. #### Returns `DATA`: Signature #### Example ```js // Request curl -X POST --data '{"jsonrpc":"2.0","method":"eth_sign","params":["0xf675187ff5b76d2430b353f6736aa051253118ee", "0xdeadbeaf"],"id":1}' // Result { "jsonrpc": "2.0", "id": 1, "result": "0x49d04469c0671c7a8187c311cb84c2ae3d0ec4943563706699440d210a9fd15642381346c008bf034d629fb0b26aff0ede25678e3df9cafc937e1ff70b832e321c" } ``` An example how to use solidity ecrecover to verify the signature calculated with `eth_sign` can be found [here](https://gist.github.com/bas-vk/d46d83da2b2b4721efb0907aecdb7ebd). The contract is deployed on the testnet Ropsten and Rinkeby. ### eth\_signTransaction Signs a transaction that can be submitted to the network at a later time using with eth\_sendRawTransaction. #### Parameters 1. `Object` - The transaction object * `from`: `DATA`, 20 Bytes - (optional) The address the transaction is sent from. * `to`: `DATA`, 20 Bytes - The address the transaction is directed to. * `gas`: `QUANTITY` - (optional) Integer of the gas provided for the transaction execution. eth\_call consumes zero gas, but this parameter may be needed by some executions. * `gasPrice`: `QUANTITY` - (optional) Integer of the gasPrice used for each paid gas * `maxFeePerGas`: `QUANTITY` - It's just the sum of baseFeePerGas and maxPriorityFeePerGas: maxFeePerGas = baseFeePerGas + maxPriorityFeePerGas. * `maxPriorityFeePerGas`: `QUANTITY` - When you submit a transaction you will also provide a "tip" to the miner. This is the maxPriorityFeePerGas field. fork. * `value`: `QUANTITY` - (optional) Integer of the value sent with this transaction * `nonce`: `QUANTITY` - the number of transactions made by the sender prior to this one. * `data`: `DATA` - (optional) Hash of the method signature and encoded parameters * `input`: `DATA` - (optional) We accept "data" and "input" for backwards-compatibility reasons. "input" is the newer name and should be preferred by clients. #### Returns `raw`, The signed transaction object. Use [eth\_getTransactionReceipt](#eth_gettransactionreceipt) to get the contract address, after the transaction was mined, when you created a contract. #### Example ```json // Request curl -X POST --data '{ "id": 1, "jsonrpc": "2.0", "method": "eth_sendTransaction", "params": [ { "from": "0xf675187ff5b76d2430b353f6736aa051253118ee", "to": "0xD13fE09E7A304709B1C4ed6Bd3a2D6C272357BBb", "gas": "0x76c0", "gasPrice": "0x4190ab00", "value": "0xde0b6b3a7640000", "data": "0xd46e8dd67c5d32be8d46e8dd67c5d32be8058bb8eb970870f072445675058bb8eb970870f072445675" } ] }' // Result { "jsonrpc": "2.0", "id": 1, "result": { "raw": "0xf89680844190ab008276c094d13fe09e7a304709b1c4ed6bd3a2d6c272357bbb880de0b6b3a7640000a9d46e8dd67c5d32be8d46e8dd67c5d32be8058bb8eb970870f072445675058bb8eb970870f0724456758201cba046644a7e36a1bb5149d72dd093ecde55d3c0999ddac6b3a19de9960931a2bf4fa010a0312b527cef2dc5ca3f26cd70d2695624c5a3c513a9f508e7eef9a4c21772", "tx": { "type": "0x0", "nonce": "0x0", "gasPrice": "0x4190ab00", "maxPriorityFeePerGas": null, "maxFeePerGas": null, "gas": "0x76c0", "value": "0xde0b6b3a7640000", "input": "0xd46e8dd67c5d32be8d46e8dd67c5d32be8058bb8eb970870f072445675058bb8eb970870f072445675", "v": "0x1cb", "r": "0x46644a7e36a1bb5149d72dd093ecde55d3c0999ddac6b3a19de9960931a2bf4f", "s": "0x10a0312b527cef2dc5ca3f26cd70d2695624c5a3c513a9f508e7eef9a4c21772", "to": "0xd13fe09e7a304709b1c4ed6bd3a2d6c272357bbb", "hash": "0xfabcd16c9277cdc957f44554c201e71fbd4c87ca0b148c51d61d23f0363a1b45" } } } ``` ### eth\_sendRawTransaction Creates new message call transaction or a contract creation for signed transactions. #### Parameters 1. `DATA`, The signed transaction data. #### Returns `DATA`, 32 Bytes - the transaction hash, or the zero hash if the transaction is not yet available. Use [eth\_getTransactionReceipt](#eth_gettransactionreceipt) to get the contract address, after the transaction was mined, when you created a contract. #### Example ```js // Request curl -X POST --data '{"jsonrpc":"2.0","method":"eth_sendRawTransaction","params":[{see above}],"id":1}' // Result { "id":1, "jsonrpc": "2.0", "result": "0xe670ec64341771606e55d6b4ca35a1a6b75ee3d5145a99d05921026d1527331" } ``` ### eth\_newFilter Creates a filter object, based on filter options, to notify when the state changes (logs). To check if the state has changed, call [eth\_getFilterChanges](#eth_getfilterchanges). #### A note on specifying topic filters: Topics are order-dependent. A transaction with a log with topics \[A, B] will be matched by the following topic filters: * `[]` "anything" * `[A]` "A in first position (and anything after)" * `[null, B]` "anything in first position AND B in second position (and anything after)" * `[A, B]` "A in first position AND B in second position (and anything after)" * `[[A, B], [A, B]]` "(A OR B) in first position AND (A OR B) in second position (and anything after)" #### Parameters 1. `Object` - The filter options: * `fromBlock`: `QUANTITY|TAG` - (optional, default: `"latest"`) Integer block number, or `"latest"` for the last mined block or `"pending"`, `"earliest"` for not yet mined transactions. * `toBlock`: `QUANTITY|TAG` - (optional, default: `"latest"`) Integer block number, or `"latest"` for the last mined block or `"pending"`, `"earliest"` for not yet mined transactions. * `address`: `DATA|Array`, 20 Bytes - (optional) Contract address or a list of addresses from which logs should originate. * `topics`: `Array of DATA`, - (optional) Array of 32 Bytes `DATA` topics. Topics are order-dependent. Each topic can also be an array of DATA with "or" options. #### Example Parameters ```js params: [{ "fromBlock": "0x1", "toBlock": "0x2", "address": "0x8888f1f195afa192cfee860698584c030f4c9db1", "topics": ["0x000000000000000000000000a94f5374fce5edbc8e2a8697c15331677e6ebf0b", null, ["0x000000000000000000000000a94f5374fce5edbc8e2a8697c15331677e6ebf0b", "0x0000000000000000000000000aff3454fce5edbc8cca8697c15331677e6ebccc"]] }] ``` #### Returns `QUANTITY` - A filter id. #### Example ```js // Request curl -X POST --data '{"jsonrpc":"2.0","method":"eth_newFilter","params":[{"topics":["0x0000000000000000000000000000000000000000000000000000000012341234"]}],"id":1}' // Result { "jsonrpc": "2.0", "id": 1, "result": "0xed3aeb3a8c77b8826c6a8544c440d7d0" } ``` ### eth\_newBlockFilter Creates a filter in the node, to notify when a new block arrives. To check if the state has changed, call [eth\_getFilterChanges](#eth_getfilterchanges). #### Parameters None #### Returns `QUANTITY` - A filter id. #### Example ```js // Request curl -X POST --data '{"jsonrpc":"2.0","method":"eth_newBlockFilter","params":[],"id":1}' // Result { "jsonrpc": "2.0", "id": 1, "result": "0x1270b5402002ba7baf7a4d6cbe21bf2e" } ``` ### eth\_newPendingTransactionFilter Creates a filter in the node, to notify when new pending transactions arrive. To check if the state has changed, call [eth\_getFilterChanges](#eth_getfilterchanges). #### Parameters None #### Returns `QUANTITY` - A filter id. #### Example ```js // Request curl -X POST --data '{"jsonrpc":"2.0","method":"eth_newPendingTransactionFilter","params":[],"id":1}' // Result { "jsonrpc": "2.0", "id": 1, "result": "0xb392ed29025e7ccce5c6553047caee35" } ``` ### eth\_uninstallFilter Uninstalls a filter with given id. Should always be called when watch is no longer needed. Additonally Filters timeout when they aren't requested with [eth\_getFilterChanges](#eth_getfilterchanges) for a period of time. #### Parameters 1. `QUANTITY` - The filter id. #### Returns `Boolean` - `true` if the filter was successfully uninstalled, otherwise `false`. #### Example ```js // Request curl -X POST --data '{"jsonrpc":"2.0","method":"eth_uninstallFilter","params":["0x9c0f6318f321c61e29a88943072b8bfb"],"id":73}' // Result { "jsonrpc": "2.0", "id": 1, "result": true } ``` ### eth\_getFilterChanges Polling method for a filter, which returns an array of logs which occurred since last poll. #### Parameters 1. `QUANTITY` - the filter id. #### Example Parameters ```js params: [ "0x16" // 22 ] ``` #### Returns `Array` - Array of log objects, or an empty array if nothing has changed since last poll. * For filters created with `eth_newBlockFilter` the return are block hashes (`DATA`, 32 Bytes), e.g. `["0x3454645634534..."]`. * For filters created with `eth_newPendingTransactionFilter` the return are transaction hashes (`DATA`, 32 Bytes), e.g. `["0x6345343454645..."]`. * For filters created with `eth_newFilter` logs are objects with following params: * `removed`: `TAG` - `true` when the log was removed, due to a chain reorganization. `false` if its a valid log. * `logIndex`: `QUANTITY` - integer of the log index position in the block. `null` when its pending log. * `transactionIndex`: `QUANTITY` - integer of the transactions index position log was created from. `null` when its pending log. * `transactionHash`: `DATA`, 32 Bytes - hash of the transactions this log was created from. `null` when its pending log. * `blockHash`: `DATA`, 32 Bytes - hash of the block where this log was in. `null` when its pending. `null` when its pending log. * `blockNumber`: `QUANTITY` - the block number where this log was in. `null` when its pending. `null` when its pending log. * `address`: `DATA`, 20 Bytes - address from which this log originated. * `data`: `DATA` - contains the non-indexed arguments of the log. * `topics`: `Array of DATA` - Array of 0 to 4 32 Bytes `DATA` of indexed log arguments. (In *solidity*: The first topic is the *hash* of the signature of the event (e.g. `Deposit(address,bytes32,uint256)`), except you declared the event with the `anonymous` specifier.) #### Example ```js // Request curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getFilterChanges","params":["0x16"],"id":73}' // Result { "id":1, "jsonrpc":"2.0", "result": [{ "logIndex": "0x1", // 1 "blockNumber":"0x1b4", // 436 "blockHash": "0x8216c5785ac562ff41e2dcfdf5785ac562ff41e2dcfdf829c5a142f1fccd7d", "transactionHash": "0xdf829c5a142f1fccd7d8216c5785ac562ff41e2dcfdf5785ac562ff41e2dcf", "transactionIndex": "0x0", // 0 "address": "0x16c5785ac562ff41e2dcfdf829c5a142f1fccd7d", "data":"0x0000000000000000000000000000000000000000000000000000000000000000", "topics": ["0x59ebeb90bc63057b6515673c3ecf9438e5058bca0f92585014eced636878c9a5"] },{ ... }] } ``` ### eth\_getFilterLogs Returns an array of all logs matching filter with given id. #### Parameters 1. `QUANTITY` - The filter id. #### Example Parameters ```js params: [ "0x16" // 22 ] ``` #### Returns See [eth\_getFilterChanges](#eth_getfilterchanges) #### Example ```js // Request curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getFilterLogs","params":["0x16"],"id":74}' ``` Result see [eth\_getFilterChanges](#eth_getfilterchanges) ### eth\_getLogs Returns an array of all logs matching a given filter object. #### Parameters 1. `Object` - The filter options: * `fromBlock`: `QUANTITY|TAG` - (optional, default: `"latest"`) Integer block number, or `"latest"` for the last mined block or `"pending"`, `"earliest"` for not yet mined transactions. * `toBlock`: `QUANTITY|TAG` - (optional, default: `"latest"`) Integer block number, or `"latest"` for the last mined block or `"pending"`, `"earliest"` for not yet mined transactions. * `address`: `DATA|Array`, 20 Bytes - (optional) Contract address or a list of addresses from which logs should originate. * `topics`: `Array of DATA`, - (optional) Array of 32 Bytes `DATA` topics. Topics are order-dependent. Each topic can also be an array of DATA with "or" options. * `blockhash`: `DATA`, 32 Bytes - (optional) With the addition of EIP-234 (Geth >= v1.8.13 or Parity >= v2.1.0), `blockHash` is a new filter option which restricts the logs returned to the single block with the 32-byte hash `blockHash`. Using `blockHash` is equivalent to `fromBlock` = `toBlock` = the block number with hash `blockHash`. If `blockHash` is present in the filter criteria, then neither `fromBlock` nor `toBlock` are allowed. #### Example Parameters ```js params: [{ "topics": ["0x000000000000000000000000a94f5374fce5edbc8e2a8697c15331677e6ebf0b"] }] ``` #### Returns See [eth\_getFilterChanges](#eth_getfilterchanges) #### Example ```js // Request curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getLogs","params":[{"topics":["0x000000000000000000000000a94f5374fce5edbc8e2a8697c15331677e6ebf0b"]}],"id":74}' ``` Result see [eth\_getFilterChanges](#eth_getfilterchanges) ### eth\_getFilterLogs Returns an array of all logs matching filter with given id. #### Parameters 1. `QUANTITY` - The filter id. #### Returns See [eth\_getFilterChanges](#eth_getfilterchanges) #### Example ```js // Request curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getFilterLogs","params":["0x16"],"id":74}' ``` Result see [eth\_getFilterChanges](#eth_getfilterchanges) ### eth\_getLogs Returns an array of all logs matching a given filter object. #### Parameters 1. `Object` - The filter options: * `fromBlock`: `QUANTITY|TAG` - (optional, default: `"latest"`) Integer block number, or `"latest"` for the last mined block or `"pending"`, `"earliest"` for not yet mined transactions. * `toBlock`: `QUANTITY|TAG` - (optional, default: `"latest"`) Integer block number, or `"latest"` for the last mined block or `"pending"`, `"earliest"` for not yet mined transactions. * `address`: `DATA|Array`, 20 Bytes - (optional) Contract address or a list of addresses from which logs should originate. * `topics`: `Array of DATA`, - (optional) Array of 32 Bytes `DATA` topics. Topics are order-dependent. Each topic can also be an array of DATA with "or" options. * `blockhash`: `DATA`, 32 Bytes - (optional) With the addition of EIP-234 (Geth >= v1.8.13 or Parity >= v2.1.0), `blockHash` is a new filter option which restricts the logs returned to the single block with the 32-byte hash `blockHash`. Using `blockHash` is equivalent to `fromBlock` = `toBlock` = the block number with hash `blockHash`. If `blockHash` is present in the filter criteria, then neither `fromBlock` nor `toBlock` are allowed. #### Example Parameters ```js params: [{ "topics": ["0x000000000000000000000000a94f5374fce5edbc8e2a8697c15331677e6ebf0b"] }] ``` #### Returns See [eth\_getFilterChanges](#eth_getfilterchanges) #### Example ```js // Request curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getLogs","params":[{"topics":["0x000000000000000000000000a94f5374fce5edbc8e2a8697c15331677e6ebf0b"]}],"id":74}' ``` Result see [eth\_getFilterChanges](#eth_getfilterchanges) # Consensus RPC Get information on the chain about validators. ## GetSnapshot retrieves the state snapshot at a given block. **Parameters** `QUANTITY|TAG` - hexadecimal of a block number **Returns** `epoch` - The epoch number of the block number. `number` - The number of the block number. `validators` - validator\`s information of the epoch. **example** ```shell # request: curl -X POST -H "Content-Type: application/json" --data '{"jsonrpc":"2.0","method":"istanbul_getSnapshot","params":["0x1"],"id":1}' http://192.168.10.201:8545 # RESPONSE: { "jsonrpc": "2.0", "id": 1, "result": { "epoch": 20, "number": 76, "hash": "0xa599dec7072503e480da203bca5fc42ad9c9399bdb59034d2aee07bc092cb252", "validators": [ { "Address": "0x1c0edab88dbb72b119039c4d14b1663525b3ac15", "BLSPublicKey": "0x136ef6be87de9c925869387782afb4cf19496999c2684709daeb3af8d0b59d800bbe05870789f0f9b3cadababa69f5a00a38bbcba71d99c4c35d671442232c4d3017fd6b99e8356a3e4e985bdfc60bbcb8d939c87976a1ff677d7c42989b379a0b4c0f168a544c892bd2b3ec480e3d6c58c7dddb8d83677ebee2e87ab3660b8000", "BLSG1PublicKey": "0x14d44a97d2fc3ea62b6dcf2bd857079bd261993152f11aef5dd001db68b20d2d1ba45f117b6530a7aec45d7d90fd4e15d2a62f62b706eaa115aa801caeee294b0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000", "UncompressedBLSPublicKey": "E272vofenJJYaTh3gq+0zxlJaZnCaEcJ2us6+NC1nYALvgWHB4nw+bPK2rq6afWgCji7y6cdmcTDXWcUQiMsTTAX/WuZ6DVqPk6YW9/GC7y42TnIeXah/2d9fEKYmzeaC0wPFopUTIkr0rPsSA49bFjH3duNg2d+vuLoerNmC4A=" }, { "Address": "0x16fdbcac4d4cc24dca47b9b80f58155a551ca2af", "BLSPublicKey": "0x0a2e37ecad6e69bfec9fec2b345d0f8441a0f63acf8b45c0131a78e5d777d52e0a39404ca85f2c08752c1d4ff8df05c82c7880779d61fe3fabcd4fd682463c0515b1f0217561a6a72bd381da19e34c5560c6eccb08ff83d7d3f4ac6da7f5d1ed15a2780f782c1fa571fa65b99694af559b9df168b1d8745ac3bbc7d3fe550b9400", "BLSG1PublicKey": "0x15b7bcf0accf839170a5d4621282edcf14f4a438f8e53abcead5f0528cb91cb1135fd4e82ede1493ab1209af122e1dc186c885cc96d2413cbc09a58163b91eb90000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000", "UncompressedBLSPublicKey": "Ci437K1uab/sn+wrNF0PhEGg9jrPi0XAExp45dd31S4KOUBMqF8sCHUsHU/43wXILHiAd51h/j+rzU/WgkY8BRWx8CF1YaanK9OB2hnjTFVgxuzLCP+D19P0rG2n9dHtFaJ4D3gsH6Vx+mW5lpSvVZud8Wix2HRaw7vH0/5VC5Q=" }, { "Address": "0x2dc45799000ab08e60b7441c36fcc74060ccbe11", "BLSPublicKey": "0x086fac850f3a9f36e8a5107eab0ba79044043dc2cc6b897cbbd0d4bf805570ff270a98f28e2d2e70b7b2ecc41a4a13e453178354997aa2038852c5945f0564bb02cdf57642881a1b40417fe3620429fc087f8dee6a68e5d7193d3243c38a1f3827d0f4cb616722a1fa78a283a17589d7688a769ade77e9d6417c6e2a9adf59c300", "BLSG1PublicKey": "0x2fd433e93187f6b3d15664ec48073bd73d57c801c4a8bfc1e0e3abd3deefc45619d45ac7ad54df7dda5b8afd6f882c9d9f879dbc6d587f1da5da1751baac729f0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000", "UncompressedBLSPublicKey": "CG+shQ86nzbopRB+qwunkEQEPcLMa4l8u9DUv4BVcP8nCpjyji0ucLey7MQaShPkUxeDVJl6ogOIUsWUXwVkuwLN9XZCiBobQEF/42IEKfwIf43uamjl1xk9MkPDih84J9D0y2FnIqH6eKKDoXWJ12iKdpred+nWQXxuKprfWcM=" }, { "Address": "0x6c5938b49bacde73a8db7c3a7da208846898bff5", "BLSPublicKey": "0x03fea7bc386ea24aaa19c563a4f26f38cbc2ce172ba2310587405f4f05777fb911a4c3553b7b6529ea02a9da3ae2df6f70c3409105b39e1930d6a6ae8344fc221f5dfb2e73cc8ce434d1af33d95366796bdec26ca7cfcc0a03867fabf471884206db6b9e175a131995bd0c70b93a6f2eec96d831ad0c42d13d334f780d57883400", "BLSG1PublicKey": "0x1b037f39d9f8e74b608a898249cc3d156ff1f0051026388366b85a84aac43bb4068275cd909e16b29f1b3bc97e91ec0a8b95a11b8a574cbc2c9ea142d26c8a490000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000", "UncompressedBLSPublicKey": "A/6nvDhuokqqGcVjpPJvOMvCzhcrojEFh0BfTwV3f7kRpMNVO3tlKeoCqdo64t9vcMNAkQWznhkw1qaug0T8Ih9d+y5zzIzkNNGvM9lTZnlr3sJsp8/MCgOGf6v0cYhCBttrnhdaExmVvQxwuTpvLuyW2DGtDELRPTNPeA1XiDQ=" } ] } } ``` ## GetValidators retrieves the list validators that must sign a given block. **Parameters** `QUANTITY|TAG` - hexadecimal of a block number **Returns** address of these validators **example** ```shell # request: curl -X POST -H "Content-Type: application/json" --data '{"jsonrpc":"2.0","method":"istanbul_getValidators","params":["0x1"],"id":1}' http://192.168.10.201:8545 # RESPONSE: { "jsonrpc": "2.0", "id": 1, "result": [ "0x1c0edab88dbb72b119039c4d14b1663525b3ac15", "0x16fdbcac4d4cc24dca47b9b80f58155a551ca2af", "0x2dc45799000ab08e60b7441c36fcc74060ccbe11", "0x6c5938b49bacde73a8db7c3a7da208846898bff5" ] } ``` ## GetValidatorsBLSPublicKeys retrieves the list of validators BLS public keys that must sign a given block. **Parameters** `QUANTITY|TAG` - hexadecimal of a block number **Returns** blsPublicKeys of these validators **example** ```shell # request: curl -X POST -H "Content-Type: application/json" --data '{"jsonrpc":"2.0","method":"istanbul_getValidatorsBLSPublicKeys","params":["0x1"],"id":1}' http://192.168.10.201:8545 # RESPONSE: { "jsonrpc": "2.0", "id": 1, "result": [ "0xbe77f945929d5dd3fe99aa825df0f5b1e8ea11786333b4492a8624a4d08dcee0e89df327359e8ec3f2d8ae01e938b7003414aa2d6523ffa02fde42b278cbae311fd39f1fbcad8e3188442ea31dee662389599751f8e73b99215cefc2e0003f81", "0x4f38a71fb13ab20f7bbfc2749ab15d775b7729842d967ca4f4115d1fcb3f378c892d073344f84e2abd8995a16eeee8004f4e588c30261e08a5dae70c581f904ea86b574bfe279222cf6b7913bebb0d3bd6c2bbe2e2ea1d338f145c4d95b99201", "0x8cf3bfcbfc76e9a99b70cad65ae51f8a8972e3e230445a55c8cf6b96dea7a2d0d970e3545e1316554d5d3b0a53582800ad4de92e3b06b62aa6f7677fdc2885a90b75fd80e2db2775512d8f3d3900aabae5b0525786d65615994b07afe7f69481", "0x1bbb8eb14a7f5dddc9de3356ce4247dab8e554fa83cd33e663db148b5d2dd14485f090978c84074154b450329de06b018eac04113ede1eedadf891ee862877af92a648c162be62182db90e8c83f8fd154fc14f13676bcb1fe3503260b6261a01" ] } ``` ## GetProposer GetProposer retrieves the proposer for a given block number (i.e. sequence) and round. **Parameters** * `sequence` - hexadecimal of a block number. * `round` - The Number of rotations **Returns** proposer address of this block number **example** ```shell # request: curl -X POST -H "Content-Type: application/json" --data '{"jsonrpc":"2.0","method":"istanbul_getProposer","params":["0x21",0],"id":1}' http://192.168.10.201:8545 # RESPONSE: { "jsonrpc": "2.0", "id": 1, "result": "0x6c5938b49bacde73a8db7c3a7da208846898bff5" } ``` ## IsValidating returns true if this node is participating in the consensus protocol. **Parameters** none **Returns** bool value about this node is participating in the consensus protocol. **example** ```shell # request: curl -X POST -H "Content-Type: application/json" --data '{"jsonrpc":"2.0","method":"istanbul_isValidating","id":1}' http://192.168.10.201:8545 # RESPONSE: { "jsonrpc": "2.0", "id": 1, "result": false } ``` ## GetLookbackWindow GetLookbackWindow retrieves A fixed value about lookbackWindow check whether the validator has signed in a fixed interval. **Parameters** none **Returns** interval value about lookbackWindow . **example** ```shell # request: curl -X POST -H "Content-Type: application/json" --data '{"jsonrpc":"2.0","method":"istanbul_getLookbackWindow","params":["0x1"],"id":1}' http://192.168.10.201:8545 # RESPONSE: { "jsonrpc": "2.0", "id": 1, "result": 12 } ``` ## GetValEnodeTable Retrieve the Validator Enode Table. **Parameters** none **Returns** validators Enode Table **example** ```shell # request: curl -X POST -H "Content-Type: application/json" --data '{"jsonrpc":"2.0","method":"istanbul_getValEnodeTable","id":1}' http://192.168.10.201:8545 # RESPONSE: { "jsonrpc": "2.0", "id": 1, "result": { "0x16FdBcAC4D4Cc24DCa47B9b80f58155a551ca2aF": { "publicKey": "0x03e7678fb997c00d5998f79413d73ebde98865cd0d7fa82e2ab6d0920a72204d8c", "enode": "enode://7c5b11c810839a9a68306f701790cdf04bf34cfeead6f02dbc6139290a9175cc2ce535b59d7d1829c7cb3edba395871667f1ba0af0441945e3679be36ff5ff7f@127.0.0.1:31001", "version": 1646035550, "highestKnownVersion": 1646035550, "numQueryAttemptsForHKVersion": 0, "lastQueryTimestamp": "2022-02-28 16:07:35.1808733 +0800 CST" }, "0x2dC45799000ab08E60b7441c36fCC74060Ccbe11": { "publicKey": "0x02ec7664543f2dae218176a072ca7bfc16632438793077c06cf05975cc1302ee60", "enode": "enode://181cf6e375f502137074b65e8ba339eb7be85b430777bb267a9db96772dfb8182b684b2e8228464e99c22b31934ddad4b15d6709cfe667d740a0cbe07d3ac482@127.0.0.1:31002", "version": 1646035556, "highestKnownVersion": 1646035556, "numQueryAttemptsForHKVersion": 0, "lastQueryTimestamp": "2022-02-28 16:06:35.1831069 +0800 CST" }, "0x6C5938B49bACDe73a8Db7C3A7DA208846898BFf5": { "publicKey": "0x02ef2af91ba2fc2b04bc47c7d59d6d07a0dea2a62c5b537d4a83a387bee4424531", "enode": "enode://ec7664543f2dae218176a072ca7bfc16632438793077c06cf05975cc1302ee60c27f29e2cc3b64ffbaa69d2939e937f99a7bf93d7c5fa59bffbcd769e4f234e8@127.0.0.1:31003", "version": 1646035561, "highestKnownVersion": 1646035561, "numQueryAttemptsForHKVersion": 0, "lastQueryTimestamp": "2022-02-28 16:07:35.1808733 +0800 CST" } } } ``` ## GetVersionCertificateTableInfo Retrieve the Validator Signature timestamp. **Parameters** none **example** ```shell # request: curl -X POST -H "Content-Type: application/json" --data '{"jsonrpc":"2.0","method":"istanbul_getVersionCertificateTableInfo","id":1}' http://192.168.10.201:8545 # RESPONSE: { "jsonrpc": "2.0", "id": 1, "result": { "0x16FdBcAC4D4Cc24DCa47B9b80f58155a551ca2aF": { "address": "0x16FdBcAC4D4Cc24DCa47B9b80f58155a551ca2aF", "version": 1646035850 }, "0x1c0eDab88dbb72B119039c4d14b1663525b3aC15": { "address": "0x1c0eDab88dbb72B119039c4d14b1663525b3aC15", "version": 1646035835 }, "0x2dC45799000ab08E60b7441c36fCC74060Ccbe11": { "address": "0x2dC45799000ab08E60b7441c36fCC74060Ccbe11", "version": 1646035856 }, "0x6C5938B49bACDe73a8Db7C3A7DA208846898BFf5": { "address": "0x6C5938B49bACDe73a8Db7C3A7DA208846898BFf5", "version": 1646035861 } } } ``` ## GetCurrentRoundState retrieves the current IBFT RoundState **Parameters** none **example** ```shell # request: curl -X POST -H "Content-Type: application/json" --data '{"jsonrpc":"2.0","method":"istanbul_getCurrentRoundState","id":1}' http://192.168.10.201:8545 # RESPONSE: { "jsonrpc": "2.0", "id": 1, "result": { "state": "Accept request", "sequence": 382, "round": 0, "desiredRound": 0, "pendingRequestHash": null, "validatorSet": [ "0x1c0edab88dbb72b119039c4d14b1663525b3ac15", "0x16fdbcac4d4cc24dca47b9b80f58155a551ca2af", "0x2dc45799000ab08e60b7441c36fcc74060ccbe11", "0x6c5938b49bacde73a8db7c3a7da208846898bff5" ], "proposer": "0x16fdbcac4d4cc24dca47b9b80f58155a551ca2af", "prepares": [], "commits": [], "parentCommits": [ "0x2dc45799000ab08e60b7441c36fcc74060ccbe11", "0x16fdbcac4d4cc24dca47b9b80f58155a551ca2af", "0x1c0edab88dbb72b119039c4d14b1663525b3ac15", "0x6c5938b49bacde73a8db7c3a7da208846898bff5" ], "preprepare": null, "preparedCertificate": null } } ``` ## ForceRoundChange Force current node timeout **Parameters** none **example** ```shell # request: curl -X POST -H "Content-Type: application/json" --data '{"jsonrpc":"2.0","method":"istanbul_forceRoundChange","id":1}' http://192.168.10.201:8545 # RESPONSE: {"jsonrpc":"2.0","id":1,"result":true} ``` ## GetCurrentReplicaState retrieves the current replica state **Parameters** none **example** ```shell # request: curl -X POST -H "Content-Type: application/json" --data '{"jsonrpc":"2.0","method":"istanbul_getCurrentReplicaState","id":1}' http://192.168.10.201:8545 # RESPONSE: { "jsonrpc": "2.0", "id": 1, "result": { "state": "Primary", "isPrimary": true, "startValidatingBlock": null, "stopValidatingBlock": null } } ``` # TSS RPC TSS (Threshold Signature Scheme) related RPC methods for MAP Protocol v2. ## tss\_getVault Retrieves vault information for a specific epoch or the latest epoch. ### Parameters | Parameter | Type | Description | | --------- | ---------------------- | ------------------------------------------------------ | | `epoch` | `QUANTITY` or `String` | Epoch ID (hexadecimal) or `"latest"` for current epoch | ### Returns `Array` - Array of vault objects: | Field | Type | Description | | ------------ | ---------- | ----------------------------------------- | | `epoch` | `QUANTITY` | The epoch number | | `public_key` | `String` | TSS public key for this epoch | | `status` | `String` | Vault status (`active`, `inactive`, etc.) | | `chains` | `Array` | List of supported chain names | | `addresses` | `Array` | Chain-specific vault addresses | **addresses object:** | Field | Type | Description | | --------- | -------- | -------------------------------- | | `chain` | `String` | Chain name (e.g., `BTC`, `DOGE`) | | `address` | `String` | Vault address on the chain | ### Example **Request (by epoch ID):** ```shell curl -X POST -H "Content-Type: application/json" \ --data '{"jsonrpc":"2.0","method":"tss_getVault","params":["0x1"],"id":1}' \ http://localhost:8545 ``` **Request (latest):** ```shell curl -X POST -H "Content-Type: application/json" \ --data '{"jsonrpc":"2.0","method":"tss_getVault","params":["latest"],"id":1}' \ http://localhost:8545 ``` **Response:** ```json { "jsonrpc": "2.0", "id": 1, "result": [ { "epoch": 1, "public_key": "0xdddc5378e96320f465f1bf8ab228c8d88ec4cff6a32f76ac066a9fd28cd614433f16b5fc49053ecd6d46a13948896f397fdc15cbb50a3a2092eda3379b536c8f", "status": "active", "chains": [ "BTC", "DOGE" ], "addresses": [ { "chain": "BTC", "address": "bc1q86m6d8fmlvan8r9pypd4p592xtcpfkn6ezxj3t" } ] } ] } ``` # TSS Cross-chain API TSS cross-chain API returns TSS cross-chain data, and provides the following interfaces. * [getChainTxHeight](#getChainTxHeight) * [getOrderSetByChainHeight](#getOrderSetByChainHeight) * [getRecordByOrderId](#getRecordByOrderId) * [getRecordByTxHash](#getRecordByTxHash) * [getChainPendingTxs](#getChainPendingTxs) ## getChainTxHeight Get the current scan height of the chain based on the specified blockchain ID. * **Method**: `GET` * **Path**: `/cross/chain/height` * **Describe**: Query the current scan height of a specified blockchain。 ### Parameters | Parameter | Type | Requied | Description | | --------- | ------ | ------- | ------------------------------- | | `chainId` | string | Yes | Unique Identifier of Blockchain | ### Returns ``` return string of chain height ``` ### Example * **Request**: ```bash curl -X GET "https://tss-api.chainservice.io/cross/chain/height?chainId=22776" ``` * **Response**: ```json { "code": 0, "data": { "height": "22099966" }, "msg": "success" } ``` ## getOrderSetByChainHeight Based on the blockchain ID and block height, retrieve the set of all cross-chain transaction order IDs scanned at that height. * **Method**: `GET` * **Path**: `/cross/chain/height/orders` * **Describe**: Query all cross-chain transaction orders that occurred at a specific block height. ### Parameters | Parameter | Type | Requied | Description | | --------- | ------ | ------- | ----------- | | chainId | string | Yes | 22776 | | height | string | Yes | 12245 | ### Returns ``` `Array` - Array of string ``` ### Example * **Request**: ```bash curl -X 'GET' \ 'https://tss-api.chainservice.io/cross/chain/height/orders?chainId=22776&height=22099953' \ -H 'accept: application/json' ``` * **Response**: ```json { "code": 0, "data": { "height": "22099966", "set": [ "0x4acc386427ec855298c70442167cad7c51a614e1d2392c85013761296da490bd", "0xe2cb120be5c7c03c600e3a202a2b4a5bdf69410db5b0a67a2be4a7d2a81cb141" ] }, "msg": "success" } ``` ## getRecordByOrderId Retrieve the complete cross-chain status record of a transaction using the unique ID of the cross-chain order. * **Method**: `GET` * **Path**: `/cross/order` * **Describe**: Query detailed transaction information across the entire chain based on cross-chain order ID. ### Parameters | Parameter | Type | Requied | Description | | --------- | ------ | ------- | ---------------------------------------- | | orderId | string | Yes | Unique Identifier for Cross-Chain Orders | ### Returns #### CrossSignel * **CrossSet** A cross-chain transaction dataset describes the state of a cross-chain transaction across the entire chain. | Field | Type | Description | | ---------- | ----------- | ------------------------------------------------------------------------------------------------------------- | | `src` | `CrossData` | src chain tx info | | `dest` | `CrossData` | dst chain tx info | | `map_dest` | `CrossData` | relay dst tx info | | `relay` | `CrossData` | relay tx info | | `status` | `string` | Cross-chain transaction status, the meaning of its numerical values can be found in the `status` enumeration. | | `order_id` | `string` | order id | | `now` | `integer` | Current timestamp. | * **CrossData** Transaction data details on a single chain. | Field | Type | Description | | --------------------- | --------- | ------------------------------------------------------- | | `chain` | `string` | chain id | | `tx_hash` | `string` | tx hash | | `height` | `integer` | tx on height | | `log_index` | `integer` | log in block index | | `timestamp` | `integer` | tx timestamp | | `topic` | `string` | tx topic | | `order_id` | `string` | tx orderId | | `chain_and_gas_limit` | `string` | Chain identifier and Gas limit combination information. | * **status** | Number | Name | | ------ | ------------------- | | `0` | `StatusOfInit` | | `1` | `StatusOfPending` | | `2` | `StatusOfSend` | | `3` | `StatusOfCompleted` | | `4` | `StatusOfFailed` | ### Example * **Request**: ```shell curl -X 'GET' \ 'https://tss-api.chainservice.io/cross/order?orderId=0x4acc386427ec855298c70442167cad7c51a614e1d2392c85013761296da490bd' \ -H 'accept: application/json' ``` * **Response**: ```json { "code": 0, "data": { "data": { "src": { "tx_hash": "0x3851dfca6deef8095bce53a6b63230359d9dc3a9e944d5827ab36df387b2fea7", "topic": "0x2b44f5da40771b7770f8469714d202f01aa69c410bd79a5dd86f9562413c3fca", "height": 22099953, "order_id": "0x4acc386427ec855298c70442167cad7c51a614e1d2392c85013761296da490bd", "log_index": 6, "chain": "22776", "chain_and_gas_limit": "142967269125167041077142995715525384507308163214988674526560832", "timestamp": 1768802635, "is_memoized": false }, "relay": { "tx_hash": "0x3851dfca6deef8095bce53a6b63230359d9dc3a9e944d5827ab36df387b2fea7", "topic": "0x2b44f5da40771b7770f8469714d202f01aa69c410bd79a5dd86f9562413c3fca", "height": 22099953, "order_id": "0x4acc386427ec855298c70442167cad7c51a614e1d2392c85013761296da490bd", "log_index": 6, "chain": "22776", "chain_and_gas_limit": "142967269125167041077142995715525384507308163214988674526560832", "timestamp": 1768802635, "is_memoized": false }, "relay_signed": { "tx_hash": "0x3b26fe78cc8b3c336a68ece04dd08ffe1f03e0e2a69784b9e5f2fa4baf9b07cf", "topic": "0x0bbc5d146426ff8f68e7bcd94bd95e273fabd90609e118badb81428405e38107", "height": 22099955, "order_id": "0x4acc386427ec855298c70442167cad7c51a614e1d2392c85013761296da490bd", "log_index": 11, "chain": "22776", "chain_and_gas_limit": "142967269125167041077142995715525384507308163214988674526560832", "timestamp": 1768802645, "is_memoized": false }, "dest": { "tx_hash": "0xa7186bd57ed3a5c7a7f3fc4651e33de1ab0939c6c08b9db25a1c19368335bc12", "topic": "0x8104943fdd0997a3240b59b381251572ac6ac81941e1af29845de70edca938a4", "height": 76128655, "order_id": "0x4acc386427ec855298c70442167cad7c51a614e1d2392c85013761296da490bd", "log_index": 213, "chain": "56", "chain_and_gas_limit": "142967269125167041077142995715525384507308163214988674526560832", "timestamp": 1768802651, "is_memoized": false }, "map_dest": { "tx_hash": "0x394326d2b4a54b18f72aea913775b965b76b92a57d738a5bd989078ca3c3040b", "topic": "0x298a40641bd31f72c733761e0e85a6bd8a36909666ac2ed63a42c8015d025638", "height": 22099966, "order_id": "0x4acc386427ec855298c70442167cad7c51a614e1d2392c85013761296da490bd", "log_index": 2, "chain": "22776", "chain_and_gas_limit": "142967269125167041077142995715525384507308163214988674526560832", "timestamp": 1768802700, "is_memoized": false }, "now": 0, "status": 3, "status_str": "completed", "order_id": "" } }, "msg": "success" } ``` ## getRecordByTxHash Retrieve the complete record of the cross-chain order to which a single transaction belongs by using its hash value. * **Method**: `GET` * **Path**: `/cross/tx` * **Describe**: Based on the transaction hash on any chain, trace back the entire cross-chain process associated with it.。 ### Parameters | Parameter | Type | Requied | Description | | --------- | ------ | ------- | ----------------------------- | | tx | string | Yes | Transaction hash on any chain | ### Returns [CrossSignel](#CrossSignel) ### Example * **Request**: ```shell curl -X 'GET' \ 'https://tss-api.chainservice.io/cross/tx?tx=0x3851dfca6deef8095bce53a6b63230359d9dc3a9e944d5827ab36df387b2fea7' \ -H 'accept: application/json' ``` * **Response**: ```json { "code": 0, "data": { "data": { "src": { "tx_hash": "0x3851dfca6deef8095bce53a6b63230359d9dc3a9e944d5827ab36df387b2fea7", "topic": "0x2b44f5da40771b7770f8469714d202f01aa69c410bd79a5dd86f9562413c3fca", "height": 22099953, "order_id": "0x4acc386427ec855298c70442167cad7c51a614e1d2392c85013761296da490bd", "log_index": 6, "chain": "22776", "chain_and_gas_limit": "142967269125167041077142995715525384507308163214988674526560832", "timestamp": 1768802635, "is_memoized": false }, "relay": { "tx_hash": "0x3851dfca6deef8095bce53a6b63230359d9dc3a9e944d5827ab36df387b2fea7", "topic": "0x2b44f5da40771b7770f8469714d202f01aa69c410bd79a5dd86f9562413c3fca", "height": 22099953, "order_id": "0x4acc386427ec855298c70442167cad7c51a614e1d2392c85013761296da490bd", "log_index": 6, "chain": "22776", "chain_and_gas_limit": "142967269125167041077142995715525384507308163214988674526560832", "timestamp": 1768802635, "is_memoized": false }, "relay_signed": { "tx_hash": "0x3b26fe78cc8b3c336a68ece04dd08ffe1f03e0e2a69784b9e5f2fa4baf9b07cf", "topic": "0x0bbc5d146426ff8f68e7bcd94bd95e273fabd90609e118badb81428405e38107", "height": 22099955, "order_id": "0x4acc386427ec855298c70442167cad7c51a614e1d2392c85013761296da490bd", "log_index": 11, "chain": "22776", "chain_and_gas_limit": "142967269125167041077142995715525384507308163214988674526560832", "timestamp": 1768802645, "is_memoized": false }, "dest": { "tx_hash": "0xa7186bd57ed3a5c7a7f3fc4651e33de1ab0939c6c08b9db25a1c19368335bc12", "topic": "0x8104943fdd0997a3240b59b381251572ac6ac81941e1af29845de70edca938a4", "height": 76128655, "order_id": "0x4acc386427ec855298c70442167cad7c51a614e1d2392c85013761296da490bd", "log_index": 213, "chain": "56", "chain_and_gas_limit": "142967269125167041077142995715525384507308163214988674526560832", "timestamp": 1768802651, "is_memoized": false }, "map_dest": { "tx_hash": "0x394326d2b4a54b18f72aea913775b965b76b92a57d738a5bd989078ca3c3040b", "topic": "0x298a40641bd31f72c733761e0e85a6bd8a36909666ac2ed63a42c8015d025638", "height": 22099966, "order_id": "0x4acc386427ec855298c70442167cad7c51a614e1d2392c85013761296da490bd", "log_index": 2, "chain": "22776", "chain_and_gas_limit": "142967269125167041077142995715525384507308163214988674526560832", "timestamp": 1768802700, "is_memoized": false }, "now": 0, "status": 3, "status_str": "completed", "order_id": "" } }, "msg": "success" } ``` ## getChainPendingTxs Gets a list of cross-chain transaction hashes with a status of "Pending" on a specified chain. * **Method**: `GET` * **Path**: `/cross/pending/tx` * **Describe**: Queries all cross-chain transactions on a given chain that have not yet been uploaded to the chain. ### Parameters | Parameter | Type | Requied | Description | | --------- | ------ | ------- | ----------------------------- | | chainId | string | Yes | Transaction hash on any chain | ### Returns ``` Array of transaction hashes. ``` ### Example * **Request**: ```shell curl -X 'GET' \ 'https://tss-api.chainservice.io/cross/pending/tx?chainId=1360095883558914' \ -H 'accept: application/json' ``` * **Response**: ```json { "code": 0, "data": { "txs": ["8c2d4520b91d4407c542256d46eace870b012704e10712ad220619af6b195780"] }, "msg": "success" } ``` # Cross-chain SDK This document will guide developers on how to integrate our service into their applications to facilitate querying the best route from token1 on Chain A to token2 on Chain B and assembling transactions. ### Installation To interact with SDK, we recommend installing through the [npm package](https://www.npmjs.com/package/@mapprotocol/routekits) ![Version](https://img.shields.io/badge/Version-1.0.0-blue) ![ES Version](https://img.shields.io/badge/ES-2020-yellow) ![Node Version](https://img.shields.io/badge/node-20.x-green) ```shell npm install @mapprotocol/routekits ``` ### Initialize During initialization, two nodes are required: `router` and `common`, as well as a set of developer-private `API keys` and `secret`, which we need to obtain. ```typescript import { Client } from '@maplabs/routekits'; const initClient = () => { const endpoint = { routes:"https://...", common:"https://...", } //for test const apikey = '3d30ba954f8f2c9...20e27'; const secret = 'ce34985d95c985b...c4baf0fc4fe012d0a865be3349da' const client = new Client({routes,common},{apikey,secret}) return client; } const client = initClient(); ``` ### Integration Steps * To query route transaction data, the ***routes node*** needs to be set during initialization. #### 1.Query Supported Chain Info Use the `getChains` function to query the list of all supported chains by this service. You will receive a list of blockchains' information. ```typescript const response = await client.getChains(); ``` > Note: the chain info list may change over time as new chains are added or removed from the Router's support, please request this endpoint to get the latest supported chain info. #### 2. Query Best Routes Use the `getRoutes` function to query the best routes from token1 on Chain A to token2 on Chain B. These routes are sorted by totalAmountOut of token2 in descending order. E.g. find the best swap route from 1 ETH on Ethereum to USDT on BSC with 1% slippage and test as the entrance. ```typescript const response = await client.getRoutes({...}) ``` #### 3. Assemble Transaction Data Based on Selected Route Use the `getOrders` function to assemble transaction data based on the selected route hash from the `getRoutes` response. E.g. assemble the transaction data based on the route hash `0x632f11788f1dc471afe15......6339d65fe03ad27a6b4daa75dc0ba` with the slippage of 1% and the sender address `Address1.....` and the receiver address `Address2.....` . ```typescript const response = await client.getOrders({...}) ``` ### Query * To query detail data, the ***common node*** needs to be set during initialization. #### 1. Transaction Detail Use `getTransaction` function to retrieve the details of successfully sent transactions by using the transaction `hash` from the source chain. ```typescript const response = await client.getTransaction({...}) ``` #### 2. Transaction List Use `getTransactions` function to retrieve a list of successfully sent transactions from the `wallet address` on the source chain. ```typescript const response = await client.getTransactions({...}) ``` ### Finally #### Congratulations! You have successfully used the SDK to complete the transaction and query the transaction data. # Overview ## Introduction This guide covers running MAP Relay Chain (Atlas) nodes. Different node types serve different purposes in the network. ## Node Types | Type | Purpose | Storage | Use Case | | -------------- | ------------------ | ------------ | --------------------- | | Full Node | Validate and relay | Pruned state | General participation | | Archive Node | Store full history | Full state | Historical queries | | RPC Node | Serve API requests | Pruned/Full | DApp backends | | Validator Node | Produce blocks | Pruned state | Network security | ## Quick Comparison ``` ┌─────────────────────────────────────────────────────────────────┐ │ Node Types │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ Full Node Archive Node RPC Node │ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │ │ Pruned │ │ Full │ │ Pruned/ │ │ │ │ State │ │ History │ │ Full │ │ │ └─────────┘ └─────────┘ └─────────┘ │ │ │ │ │ │ │ ▼ ▼ ▼ │ │ P2P Network Query History Serve APIs │ │ │ │ Validator Node │ │ ┌─────────┐ │ │ │ Produce │ │ │ │ Blocks │ │ │ └─────────┘ │ │ │ │ │ ▼ │ │ Earn Rewards │ │ │ └─────────────────────────────────────────────────────────────────┘ ``` ## Hardware Requirements ### Minimum Requirements | Component | Full Node | Archive Node | RPC Node | | --------- | ---------- | ------------ | ---------- | | CPU | 4 cores | 8 cores | 4 cores | | RAM | 8 GB | 16 GB | 8 GB | | Storage | 500 GB SSD | 2 TB SSD | 500 GB SSD | | Network | 25 Mbps | 25 Mbps | 100 Mbps | ### Recommended Requirements | Component | Full Node | Archive Node | RPC Node | | --------- | --------- | ------------ | --------- | | CPU | 8 cores | 16 cores | 8 cores | | RAM | 16 GB | 32 GB | 16 GB | | Storage | 1 TB NVMe | 4 TB NVMe | 1 TB NVMe | | Network | 100 Mbps | 100 Mbps | 1 Gbps | ## Software Requirements * **OS**: Ubuntu 20.04/22.04 LTS (recommended) * **Go**: 1.21+ * **Git**: Latest version ## Network Information ### Mainnet | Parameter | Value | | --------- | ------------------------ | | Chain ID | 22776 | | RPC | | | Explorer | | ### Testnet (Makalu) | Parameter | Value | | --------- | -------------------------------- | | Chain ID | 212 | | RPC | | | Explorer | | ## Quick Start ### 1. Install Atlas ```bash # Clone repository git clone https://github.com/mapprotocol/atlas.git cd atlas # Build make atlas # Verify installation ./build/bin/atlas version ``` ### 2. Initialize Node ```bash # Create data directory mkdir -p ~/.atlas # Initialize with genesis ./build/bin/atlas --datadir ~/.atlas init genesis.json ``` ### 3. Start Node ```bash # Start full node ./build/bin/atlas --datadir ~/.atlas \ --networkid 22776 \ --syncmode full ``` ## Next Steps * [Installation Guide](/run-node/install) - Detailed installation instructions * [Node Types](/run-node/node-types) - Learn about different node configurations (Full Node, Archive Node, RPC Node) * [Become Validator](/validator/become-validator) - Run a validator node # Installation ## Overview This guide covers installing MAP Relay Chain (Atlas) node software on Linux systems. ## Prerequisites ### System Requirements * **OS**: Ubuntu 20.04 or 22.04 LTS * **CPU**: 4+ cores * **RAM**: 8+ GB * **Storage**: 500+ GB SSD * **Network**: Stable internet connection ### Install Dependencies ```bash # Update system sudo apt update && sudo apt upgrade -y # Install required packages sudo apt install -y build-essential git curl wget ``` ### Install Go Atlas requires Go 1.21 or higher: ```bash # Download Go wget https://go.dev/dl/go1.21.0.linux-amd64.tar.gz # Install Go sudo rm -rf /usr/local/go sudo tar -C /usr/local -xzf go1.21.0.linux-amd64.tar.gz # Add to PATH echo 'export PATH=$PATH:/usr/local/go/bin' >> ~/.bashrc echo 'export GOPATH=$HOME/go' >> ~/.bashrc echo 'export PATH=$PATH:$GOPATH/bin' >> ~/.bashrc source ~/.bashrc # Verify installation go version ``` ## Installation Methods ### Method 1: Build from Source (Recommended) ```bash # Clone repository git clone https://github.com/mapprotocol/atlas.git cd atlas # Checkout latest stable release git checkout v1.0.0 # Replace with actual version # Build make atlas # Verify build ./build/bin/atlas version ``` ### Method 2: Download Binary ```bash # Download latest release wget https://github.com/mapprotocol/atlas/releases/download/v1.0.0/atlas-linux-amd64.tar.gz # Extract tar -xzf atlas-linux-amd64.tar.gz # Move to bin sudo mv atlas /usr/local/bin/ # Verify atlas version ``` ## Initial Configuration ### Create Data Directory ```bash # Create directory mkdir -p ~/.atlas # Set permissions chmod 700 ~/.atlas ``` ## Create Systemd Service For production nodes, use systemd for process management: ```bash # Create service file sudo tee /etc/systemd/system/atlas.service > /dev/null < eth.syncing # Check block number > eth.blockNumber # Check peers > admin.peers.length ``` ### Check via RPC ```bash # Check block number curl -X POST -H "Content-Type: application/json" \ --data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' \ http://localhost:8545 ``` ## Troubleshooting ### Node Not Starting ```bash # Check logs for errors journalctl -u atlas -n 50 # Common issues: # - Port already in use # - Insufficient permissions # - Missing genesis file ``` ### Not Finding Peers ```bash # Add bootnodes manually atlas --datadir ~/.atlas \ --bootnodes "enode://xxx@ip:port" ``` ### Sync Stuck ```bash # Try different sync mode atlas --datadir ~/.atlas --syncmode fast # Or clean and restart rm -rf ~/.atlas/atlas/chaindata atlas --datadir ~/.atlas init ~/.atlas/genesis.json ``` ## Next Steps * [Node Types](/run-node/node-types) - Configure different node types (Full Node, Archive Node, RPC Node) * [Become Validator](/validator/become-validator) - Run a validator node # Node Types This guide covers running different types of MAP Relay Chain (Atlas) nodes. ## Full Node A full node validates and relays transactions, participating in the P2P network with moderate resource requirements. ### Running a Full Node ```bash # Basic full node atlas --datadir ./node console # With network ID specified atlas --datadir ./node --networkid 22776 --syncmode full ``` ### Single-Node Network (Development) For testing and development: ```bash # Single node mode atlas --datadir ./node --single console # With HTTP RPC enabled atlas --datadir ./node --single --http --http.addr "127.0.0.1" --http.port 7445 console ``` ## Archive Node An archive node stores complete blockchain history, including all historical states. It's useful for: * Block explorers * Historical data queries * Research and analytics * Auditing and compliance ### What is an Archive Node? A full node only keeps recent states (last \~128 blocks) and prunes older data. An archive node stores every historical state after each block, trading disk space for quick access to historical data. ### Hardware Requirements Archive nodes require significantly more storage: * **Storage**: 2-4 TB SSD (and growing) * **RAM**: 16+ GB recommended * **CPU**: Faster CPU helps with initial sync ### Running an Archive Node ```bash atlas --datadir ./node --syncmode "full" --gcmode "archive" ``` ## RPC Node An RPC node serves JSON-RPC API requests for decentralized applications (DApps). ### How RPC Nodes Work RPC nodes use the JSON-RPC protocol to: * Receive requests from client applications * Query blockchain data * Execute and broadcast transactions * Return results in JSON format ### Running an RPC Node ```bash # Basic RPC node atlas --datadir ./node --syncmode "full" --http --http.addr "127.0.0.1" --http.port 7445 # With more API modules atlas --datadir ./node --syncmode "full" \ --http --http.addr "0.0.0.0" --http.port 8545 \ --http.api eth,net,web3,txpool ``` ### RPC Configuration Options | Option | Description | | ------------------- | ----------------------------- | | `--http` | Enable HTTP-RPC server | | `--http.addr` | HTTP-RPC listen address | | `--http.port` | HTTP-RPC port (default: 8545) | | `--http.api` | APIs offered over HTTP-RPC | | `--http.corsdomain` | Allowed CORS domains | ## Comparison | Feature | Full Node | Archive Node | RPC Node | | ------------------ | ----------------- | ------------- | --------------- | | State Storage | Pruned | Complete | Pruned/Complete | | Disk Usage | \~500 GB | 2-4 TB | \~500 GB | | Historical Queries | Limited | Full | Depends on mode | | API Access | Console | Console | HTTP/WS | | Use Case | P2P participation | Data services | DApp backends | # Glossary # Links # Changelog