From 09193f3ef8561f066bdea33000fadd3c8f3b8101 Mon Sep 17 00:00:00 2001 From: garikbesson Date: Fri, 13 Sep 2024 19:37:05 +0200 Subject: [PATCH 1/2] removing multichain gas relayer section from sidebar --- website/sidebars.js | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/website/sidebars.js b/website/sidebars.js index 2c72e8e241..966ed72d60 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -101,20 +101,20 @@ const sidebar = { ] }, // 'build/chain-abstraction/wallet', - { - "type": "category", - "label": "Multichain Gas Relayer", - "link": { - "type": "doc", - "id": "build/chain-abstraction/multichain-gas-relayer/getting-started" - }, - "items": [ - "build/chain-abstraction/multichain-gas-relayer/overview", - "build/chain-abstraction/multichain-gas-relayer/gas-station", - "build/chain-abstraction/multichain-gas-relayer/multichain-server", - "build/chain-abstraction/multichain-gas-relayer/relayer-gas-example", - ] - }, + // { + // "type": "category", + // "label": "Multichain Gas Relayer", + // "link": { + // "type": "doc", + // "id": "build/chain-abstraction/multichain-gas-relayer/getting-started" + // }, + // "items": [ + // "build/chain-abstraction/multichain-gas-relayer/overview", + // "build/chain-abstraction/multichain-gas-relayer/gas-station", + // "build/chain-abstraction/multichain-gas-relayer/multichain-server", + // "build/chain-abstraction/multichain-gas-relayer/relayer-gas-example", + // ] + // }, 'build/chain-abstraction/fastauth-sdk', "build/chain-abstraction/data-availability", ] From 37f24fa9016e449610ddeda26909b6fb7c62ac08 Mon Sep 17 00:00:00 2001 From: garikbesson Date: Tue, 17 Sep 2024 15:18:41 +0200 Subject: [PATCH 2/2] removed multichain gas relayer content --- blog/2024-08-13.md | 2 +- .../chain-signatures/chain-signatures.md | 2 - .../multichain-gas-relayer/gas-station.md | 137 ------- .../multichain-gas-relayer/getting-started.md | 71 ---- .../multichain-server.md | 117 ------ .../multichain-gas-relayer/overview.md | 69 ---- .../relayer-gas-example.md | 383 ------------------ website/sidebars.js | 15 - 8 files changed, 1 insertion(+), 795 deletions(-) delete mode 100644 docs/2.build/1.chain-abstraction/multichain-gas-relayer/gas-station.md delete mode 100644 docs/2.build/1.chain-abstraction/multichain-gas-relayer/getting-started.md delete mode 100644 docs/2.build/1.chain-abstraction/multichain-gas-relayer/multichain-server.md delete mode 100644 docs/2.build/1.chain-abstraction/multichain-gas-relayer/overview.md delete mode 100644 docs/2.build/1.chain-abstraction/multichain-gas-relayer/relayer-gas-example.md diff --git a/blog/2024-08-13.md b/blog/2024-08-13.md index 450d320cfa..64dcd82fb6 100644 --- a/blog/2024-08-13.md +++ b/blog/2024-08-13.md @@ -33,7 +33,7 @@ The Infrastructure Committee feels that Pagoda's fully-subsidized near.org RPC s ### Chain Abstraction Services -[Chain Signatures](https://docs.near.org/concepts/abstraction/chain-signatures), [Multichain Gas Relayer](https://docs.near.org/build/chain-abstraction/multichain-gas-relayer/overview), and [FastAuth](https://docs.near.org/build/chain-abstraction/fastauth-sdk) will continue to be developed by Pagoda, then will be taken over by the new Chain Abstraction / Multichain spinout from Pagoda and Proximity. More information will be shared in September or October 2024. +[Chain Signatures](https://docs.near.org/concepts/abstraction/chain-signatures), Multichain Gas Relayer, and [FastAuth](https://docs.near.org/build/chain-abstraction/fastauth-sdk) will continue to be developed by Pagoda, then will be taken over by the new Chain Abstraction / Multichain spinout from Pagoda and Proximity. More information will be shared in September or October 2024. ### Pagoda Operations & Ecosystem Services diff --git a/docs/2.build/1.chain-abstraction/chain-signatures/chain-signatures.md b/docs/2.build/1.chain-abstraction/chain-signatures/chain-signatures.md index 5a427e8f08..79e4555e18 100644 --- a/docs/2.build/1.chain-abstraction/chain-signatures/chain-signatures.md +++ b/docs/2.build/1.chain-abstraction/chain-signatures/chain-signatures.md @@ -43,14 +43,12 @@ _Diagram of a chain signature in NEAR_ If you want to try things out, these are the smart contracts available on `testnet`: - `v1.signer-prod.testnet`: [MPC signer](https://github.com/near/mpc/tree/v0.2.0/contract) contract, latest release, made up of 8 MPC nodes -- `canhazgas.testnet`: [Multichain Gas Station](../multichain-gas-relayer/gas-station.md) contract ::: :::info MPC mainnet contracts - `v1.signer`: [MPC signer](https://github.com/near/mpc/tree/v0.2.0/contract) contract, latest release, made up of 8 MPC nodes -- `canhazgas.near`: [Multichain Gas Station](../multichain-gas-relayer/gas-station.md) contract ::: --- diff --git a/docs/2.build/1.chain-abstraction/multichain-gas-relayer/gas-station.md b/docs/2.build/1.chain-abstraction/multichain-gas-relayer/gas-station.md deleted file mode 100644 index 841cb6133f..0000000000 --- a/docs/2.build/1.chain-abstraction/multichain-gas-relayer/gas-station.md +++ /dev/null @@ -1,137 +0,0 @@ ---- -id: gas-station -title: Multichain Gas Station Contract -sidebar_label: Multichain Gas Station Contract ---- - -The [multichain gas station smart contract](https://github.com/near/multichain-gas-station-contract) accepts payments in NEAR tokens in exchange for gas funding on non-NEAR foreign chains. Part of the NEAR Multichain effort, it works in conjunction with the [MPC recovery service](https://github.com/near/mpc-recovery) to generate on-chain signatures. - -## What is it? - -This smart contract is a piece of the NEAR Multichain project, which makes NEAR Protocol an effortlessly cross-chain network. This contract accepts EVM transaction request payloads and facilitates the signing, gas funding, and relaying of the signed transactions to their destination chains. It works in conjunction with a few different services, including: - -- The [MPC recovery service](https://github.com/near/mpc-recovery), also called the _"MPC signer service"_, includes a network of trusted MPC signers, which hold keyshares and cooperatively sign transactions on behalf of the MPC network. It also includes an on-chain component, called the _"MPC signer contract,"_ which accepts on-chain signature requests and returns signatures computed by the MPC network. -- The [multichain relayer server](multichain-server.md) scans this smart contract for signed transaction payloads and emits them to foreign chain RPCs. - -## How it works - -Currently, relaying one transaction to a foreign chain requires three transactions. -Three transactions are required because of the gas restrictions imposed by the protocol. Currently (pre-NEP-516), the MPC signing function requires a _lot_ of gas, so dividing up the signing process into three parts is required to maximize the amount of gas available to each signing call. - -:::info -[NEP-516 (delayed receipts / runtime triggers)](https://github.com/near/NEPs/issues/516) will reduce the required transactions to one. -::: - -Transaction breakdown: - -1. The first transaction is a call to the `create_transaction` function. This function accepts an EVM transaction request payload and a deposit amount (to pay for gas on the foreign chain) and returns an `id` and a `pending_transactions_count`. -2. The second transaction is a call to the `sign_next` function. This function accepts the `id` returned in step 1 and returns a signed payload. This payload is the gas funding transaction, transferring funds from a paymaster account on the foreign chain to the user's account on the foreign chain. It must be submitted to the foreign chain before the second signed payload. -3. The third transaction is another call to the `sign_next` function, identical to the one before. This function accepts an `id` and returns a signed payload. This payload is the signed user transaction. - -Once this service and its supporting services are live, the multichain relayer server will be monitoring this gas station contract and relaying the signed transactions in the proper order as they become available, so it will not be strictly necessary for the users of this contract to ensure that the transactions are properly relayed, unless the user wishes to relay the transactions using their own RPC (e.g. to minimize latency). - -## Variable Gas fees - -There's a premium on the Gas Station in `NEAR` for what the gas will cost on the foreign chain to account for variation in both the exchange rate between transactions, settlement between chains, and to account for variation in gas costs until the transaction is confirmed. - -### BSC - -This is the formula for calculating the gas fee: - -`(gas_limit_of_user_transaction + 21000) * gas_price_of_user_transaction * near_tokens_per_foreign_token * 1.2` - -:::note - -- `21000` is the exact amount of gas necessary to transfer funds on `BSC`. -- `1.2` is an arbitrage fee: charge 20% more than market rate to discourage people from using the Gas Station as an arbitrage/DEX. - -::: - -## Settlement - -Settlement is needed because the Gas Station contract is accumulating NEAR, while the [Paymaster accounts](multichain-server.md#paymaster) on foreign chains are spending native foreign chain gas tokens (`ETH`, `BNB`, `SOL`, etc). - -### Manual settlement - -Manual Settlement involves several steps: - -1. Withdrawing the NEAR held in the gas station contract and swapping for a token that can be bridged. - This may be the native gas token of the foreign chain, another token like USDC that has wide bridge support, or NEAR. - -2. Bridging the token from NEAR to the foreign chain. - - Here's an [overview of bridging related to NEAR](https://knotty-marsupial-f6d.notion.site/NEAR-Bridging-Guides-f4359bd35c794dc184b098f7ed00c4ce). - -3. Sending the native gas tokens to the paymaster accounts on the foreign chains. - - A swap from the bridged token to the native gas token before sending to the paymaster accounts is necessary if the token that was bridged was not the foreign chain native gas token - -### Automated settlement - -Automated settlement is available for select partners based on their cross-chain transaction volume. -When using automated settlement, a Market Maker facilitates the settlement of assets between a partner’s gas station contract and their paymaster accounts on destination chains. - -:::info Contact us - -If you're interested in using the automated settlement service, please [contact us](https://forms.gle/7z9nKVd4VH3qxbny6) by filling out [this form](https://forms.gle/7z9nKVd4VH3qxbny6). - -::: - -## Contract Interactions - -:::tip -You can review the complete smart contract source code in [this GitHub repository](https://github.com/near/multichain-gas-station-contract). -::: - -### Setup and Administration - -1. Initialize the contract with a call to `new`. The [owner](https://github.com/near/near-sdk-contract-tools/blob/develop/src/owner.rs) is initialized as the predecessor of this transaction. All of the following transactions must be called by the owner. -2. Refresh the MPC contract public key by calling `refresh_signer_public_key`. -3. Set up foreign chain configurations with `add_foreign_chain`. - - When performing the function call for `add_foreign_chain`, the chain ID and oracle price ID must be updated appropriately: - - Specific chain IDs (e.g. BSC, Base, Optimism, Arbitrum) can be [found here](https://chainlist.org/) - - Pyth oracle price fee IDs can be [found here](https://pyth.network/developers/price-feed-ids) -4. Add paymasters to each foreign chain with `add_paymaster`. - -### Price Pusher - -In order to get up-to-date information on gas prices for foreign chains, a price pusher service must be run, either on demand or as a `cron` job. - -Suggested tools: -- [Pyth Price Pusher](https://github.com/pyth-network/pyth-crosschain/tree/main/apps/price_pusher): this price pusher supports `BNB` and `ETH` - -:::tip -A separate price pusher should be used for each token. -::: - -### Usage - -Users who wish to get transactions signed and relayed by this contract and its accompanying infrastructure should perform the following steps: - -1. Construct an unsigned transaction payload for the foreign chain they wish to interact with, e.g. Ethereum. -2. Call `create_transaction` on this contract, passing in that payload and activating the `use_paymaster` toggle in the case that the user wishes to use a paymaster. - - If the user uses a paymaster, he must attach a sufficient quantity of NEAR tokens to this transaction to pay for the gas + service fee. - - This function call returns an `id` and a `pending_transactions_count`. -3. Call `sign_next`, passing in the id value obtained in the previous step. This transaction should be executed with the maximum allowable quantity of gas (i.e. 300 TGas). - - This transaction will return a signed payload, part of the sequence of transactions necessary to send the user's transaction to the foreign chain. - - Repeat `pending_transactions_count` times. -4. Relay each signed payload to the foreign chain RPC in the order they were requested. - -:::tip Contract address - -If you want to try things out, this smart contract is available on: -- testnet: `canhazgas.testnet` -- mainnet: `canhazgas.near` - -::: - -## Limitations - -When using the Multichain Gas relayer solution, some limitations should be consider. Here's a list of potential issues you might encounter, and suggested ways to mitigate them: -- Not enough gas for a cross-chain transaction to get included in time. - - **Solution:** overcharge for gas at the gas station and when constructing the transaction include more than the average gas price. -- Slippage violations causing the gas token or foreign chain Fungible Token to get refunded to the user's foreign chain address. - - **Solution:** encourage your users to use high slippage settings in volatile or low liquidity market conditions. - - **Solution:** if such error occurs, make the user aware of what happened and that funds were not lost. - - **Note:** in future versions the solution will support retrying transactions. -- Nonce issues if Paymaster rotation isn't done properly. This issue is a function of concurrent usage, blockchain finality time, and number of paymaster treasury accounts that the [Gas Station](gas-station.md) is rotating through. - - **Solution:** use a blockchain that has faster finality. - - **Solution:** increase the number of paymaster treasury accounts that the gas station rotates through. diff --git a/docs/2.build/1.chain-abstraction/multichain-gas-relayer/getting-started.md b/docs/2.build/1.chain-abstraction/multichain-gas-relayer/getting-started.md deleted file mode 100644 index fb7feca4e5..0000000000 --- a/docs/2.build/1.chain-abstraction/multichain-gas-relayer/getting-started.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -id: getting-started -title: "Multichain Gas Relayer: Getting Started Guide" ---- - -[Chain Signatures](../chain-signatures/getting-started.md) lets users manage remote accounts and transact on any blockchain from a single NEAR account. The Multichain Gas Relayer further simplifies this process by eliminating the need for users to acquire the tokens needed in the foreign chain to execute their transactions. - -![img](https://pages.near.org/wp-content/uploads/2024/02/acct-abstraction-blog-1.png) - -In other words, the Multichain Gas Relayer provides gas abstraction for foreign chains, allowing NEAR accounts to pay for the gas needed in the target chain using our native token (NEAR) and fungible tokens (e.g. USDC and USDT). - - ---- - -## Why a Multichain Gas Relayer? - -NEAR's mission is to build blockchain infrastructure for Chain Abstracted applications. Chain abstraction aims to make blockchain technology more user-friendly by simplifying interactions. - -A key step in achieving this is reducing the complexity of paying for transaction gas across different blockchains. Users should be able to pay for cross-chain transactions with a single asset or have the gas fees fully sponsored on their behalf. - ---- - -## How Does it Work? - -The Multichain Gas Relayer has 3 core components: - -1. **Gas Station Smart Contract**: A smart contract on NEAR that manages the creation, signing, of transactions to foreign chains. It also handles gas fee calculations and collects NEAR tokens for gas payments on foreign chains - -2. **Multichain Relayer Server**: This server coordinates the relaying of transactions between NEAR and other blockchains. It listens for signed transaction payloads and submits them to the appropriate foreign chain RPCs - -3. **Chain Signatures**: A network of distributed Multi-Party Computation (MPC) signers that cooperatively sign transactions. This ensures secure transaction signing and validation on the NEAR blockchain before relaying to foreign chains - -#### System Workflow - -![chain-signatures](/docs/assets/welcome-pages/multi-chain-gas-diagram.png) -_Diagram of a chain signature in NEAR with gas being covered by the Relayer_ - -1. **Transaction Creation**: An account sends a transaction to the Gas Station Contract, specifying the foreign chain transaction and attaching NEAR tokens to cover gas fees on the foreign chain. - -2. **Transaction Signing**: The Gas Station Contract invokes Chain Signatures MPC signing service to sign the transaction. This step may require multiple calls due to gas limitations on NEAR, especially for complex transactions - -3. **Event Emission and Indexing**: Once the transactions are signed, the Gas Station Contract emits an event. The Gas Station Event Indexer picks up this event and triggers the Multichain Relayer Server to relay the signed transactions - -4. **Relaying Transactions**: The Multichain Relayer Server first sends a funding transaction to ensure the user’s account on the foreign chain has sufficient gas. Once confirmed, it sends the user’s originally intended signed transaction to the foreign chain for execution - ---- - -## Example Real-World Flow - -* Alice has an `alice.near` account that maps to a remote Optimism (OP) address, `0xabc` -* Alice wants to interact with a Farcaster application on OP using her NEAR account, but she prefers to pay for gas with assets she has on hand, specifically USDT -* Alice initiates an on-chain action on Farcaster from her NEAR account. She sends the transaction to a gas station smart contract, including the OP transaction payload in the arguments and attaching the necessary USDT amount for the cross-chain gas payment -* The transaction bundle is sent to the NEAR gas station contract, which then forwards it to the NEAR MPC signing service. This bundle includes (1) the transaction to fund the user's `0xabc` address with the ETH needed for gas, and (2) the user's original transaction to take action on the Farcaster application -* The MPC service will sign both transactions and forward the signed transactions back to the gas station contract -* The relayer operator will observe the events (signed transactions) emitted from the gas station contract and submit them to the Optimism network. This process starts by initiating a fund transfer from a treasury paymaster account on Optimism that holds ETH. The paymaster account will transfer ETH to the user's `0xabc` address, equivalent to the USDT originally sent by the user -* Then the relayer will submit the final transaction, and the originally intended Farcaster transaction will be executed from the user's `0xabc` address, using ETH to cover the gas - ---- - -## What chains are supported? - -Currently, the Multichain Gas Relayer supports [Base](https://www.base.org/), [Optimism](https://www.optimism.io/), [Arbitrum](https://arbitrum.io/) and [Binance Smart Chain](https://www.bnbchain.org/en/bnb-smart-chain), and [Ethereum](https://ethereum.org/en/). - -These chains were selected based on multiple factors including interest from key partners, low gas fees, and fast finality for transactions. Support for EDDSA chains like [Solana](https://solana.com/) will be coming soon in conjunction with EDDSA support for NEAR chain signatures. - ---- - -## Where can I go to learn more? - -* Visit our [docs](./overview.md) to learn more about how to integrate the Multichain Gas Relayer into your product -* Join the NEAR Chain Abstraction [developer group](https://t.me/chain\_abstraction) on Telegram to ask questions and discuss ideas with other developers. \ No newline at end of file diff --git a/docs/2.build/1.chain-abstraction/multichain-gas-relayer/multichain-server.md b/docs/2.build/1.chain-abstraction/multichain-gas-relayer/multichain-server.md deleted file mode 100644 index 9b9f826593..0000000000 --- a/docs/2.build/1.chain-abstraction/multichain-gas-relayer/multichain-server.md +++ /dev/null @@ -1,117 +0,0 @@ ---- -id: multichain-server -title: Multichain Relayer Server -sidebar_label: Multichain Relayer Server ---- - -The [Multichain Relayer Server](https://github.com/near/multichain-relayer-server) facilitates cross-chain transactions and enables Chain Abstraction. - -## Overview - -The main function of this server is interfacing with foreign chain RPCs sending both presigned funding transactions to cover gas and the actual presigned transaction once the funding is done. - -Although the multichain relayer is a server in current design of this system, the goal is to package this as a library that can be called on the client side of the wallet. This will make the system more decentralized. - -:::tip -The Multichain Relayer is meant to be deployed alongside the [Gas Station Event Indexer](https://github.com/near/gas-station-event-indexer) on the same server so that the Gas Station event indexer can call the Multichain Relayer server via IPC instead of having to send the request over the network introducing extra latency to the system. -::: - -## Paymaster - -A paymaster represents an address on a destination chain that holds a balance of that chain’s native gas token: -- User addresses on destination chains will be funded directly from paymaster accounts. -- Partners that want to integrate with the Multichain Gas Relayer service need to create, fund, and manage paymaster accounts on the destination chains that they want to have support for. -- [Manual settlement](gas-station.md#settlement) between the [NEAR Gas Station contract](gas-station.md) and paymaster accounts are also required on a regular basis to ensure a consistent balance of funds. - -### Multiple Paymaster accounts - -If the relayer or transaction forwarder is fast enough, having only one Paymaster account _might_ be enough. - -:::info -Currently we don't have actual performance or usage data, so it's difficult to offer recommendations about multiple paymaster accounts. -::: - -For independent deployments of gas station contracts, generally, nonce synchronicity should be addressed using these three measures, in this order of preference: - -1. Users and clients of the smart contract submit signed payloads independently. - - This is the least reliable option; it is not wise to leave this up to the users, but it is potentially the lowest-latency option. Therefore, while this should be the first option in order of precedence, it must not be the only option. -2. The relayer service picks up signed payloads and submits them to the remote chain. - - This relayer service provides the guarantee to the smart contract that signed payloads _will_ make it to the remote chain and update the nonce. -3. Using multiple paymaster accounts. - - This is a stopgap measure that essentially only serves as a small buffer in case the relayer service falls behind, or some of the paymaster nonces (temporarily) get out-of-sync. Adding more paymasters will not eliminate nonce synchronicity issues if they exist; it will only reduce latency for users while the system is working and experiencing high traffic. - -## System workflow - -[![multichain_relayer_technical_design.png](/docs/multichain_relayer_technical_design.png)](/docs/multichain_relayer_technical_design.png) - -1. The wallet sends a NEAR transaction to the gas station contract that contains 2 actions: - 1. A transfer of `NEAR` (or FT Transfer in the future) to cover gas on the foreign chain - 2. A `create_transaction` function call to the gas station contract `canhazgas.testnet` containing the unsigned foreign chain transaction to be signed by the MPC signing service, assuming the unsigned transaction passes validation. - > (note: `mainnet` contract address is `canhazgas.near`) -2. The Gas Station Contract calls the MPC signing service to sign both a funding transaction, which ensures the user's foreign chain account has sufficient gas to execute the desired transaction, and signs the unsigned foreign chain transaction. -3. Upon receipt of both the signed transactions, the Gas Station Contract emits an event which is picked up by the indexer, which then calls the `/send_funding_and_user_signed_txns` with the 2 signed transactions from the indexer. -4. The multichain relayer server sends the funding transaction to the foreign chain RPC to fund the user's account with gas. -5. After the gas funding transaction is confirmed, the multichain relayer server calls the foreign chain RPC again to send the signed transaction initiated by the user in step 1. -6. The [cross-chain settlement](gas-station.md#settlement) takes care of selling the extra `NEAR` being sent to the gas station contract for gas tokens on foreign chains as well as bridging the tokens to the other chains. This process is currently manual, but will be automated in partnership with market makers in the future. - -## Relayer Server Endpoints - -1. `/send_funding_and_user_signed_txns` which handles both - 1. Funding the user's XChain account with gas from the paymaster treasury account, which is provided as a raw signed transaction - 2. Sending the user's raw signed transaction (in hexadecimal in EVM case) after the funding transaction has been confirmed on the foreign chain - -## Supported Chains - -#### Testnet - -- Arbitrum (Ethereum Sepolia) -- Base (Ethereum Sepolia) -- BSC -- Ethereum (Sepolia) -- Optimism (Ethereum Sepolia) - -#### Mainnet - -- Arbitrum (Ethereum L2) -- Base (Ethereum L2) -- BSC -- Ethereum -- Optimism (Ethereum L2) - -:::info -Check the Relayer's [GitHub repository](https://github.com/near/multichain-relayer-server) to learn more about upcoming features and updates. -::: - -## Limitations - -When using the Multichain Gas relayer solution, some limitations should be considered. Here's a list of potential issues you might encounter, and suggested ways to mitigate them: -- Not enough gas for a cross-chain transaction to get included in time. - - **Solution:** overcharge for gas at the gas station and when constructing the transaction include more than the average gas price. -- Slippage violations causing the gas token or foreign chain Fungible Token to get refunded to the user's foreign chain address. - - **Solution:** encourage your users to use high slippage settings in volatile or low liquidity market conditions. - - **Solution:** if such error occurs, make the user aware of what happened and that funds were not lost. - - **Note:** in future versions the solution will support retrying transactions. -- Nonce issues if Paymaster rotation isn't done properly. This issue is a function of concurrent usage, blockchain finality time, and the number of paymaster treasury accounts that the [Gas Station](gas-station.md) is rotating through. - - **Solution:** use a blockchain that has faster finality. - - **Solution:** increase the number of paymaster treasury accounts through which the gas station rotates. - -## Total Time expectations for end users - -It depends on the chain, but in our current estimation 50-90% of the time will be on NEAR calling and waiting for the signing to complete on the MPC service. -The signing service will take 15-30 seconds. -We assume that both the signing of the foreign chain transaction and the gas funding transaction happen in parallel. - -### BSC - -On BSC mainnet (not `beaconchain` which has 1 second finality) with 3 second blocktimes there should be 2 blocks for confirmation optimistically bringing the total to 6 seconds optimistically/transaction on BSC. -We need to make 2 transactions, so that's 12-24 seconds on BSC assuming 2-4 blocks for finality. Add in some network overhead for each step in the process, especially the indexer picking up the emitted event (~5-7 seconds), and we're at 30-60 seconds/transaction on BSC. - -### Solana - -For Solana it would be closer to 20-30 seconds (0.4 second block time, 1 block confirmation). See [table 1](https://usa.visa.com/solutions/crypto/deep-dive-on-solana.html) for more confirmation times. - -### Ethereum L2s - -L2 real finality times can be over a day for finality, unless we trust a centralized sequencer for soft confirmations, which may be as fast as a few seconds as in the case of [zksync era](https://docs.zksync.io/zk-stack/concepts/finality#instant-confirmations). - -The difference between optimistic or soft confirmations vs real finality is something we are considering. We may get better finalized guarantees when the [Eigenlayer-Near Partnership is live](https://near.org/blog/near-foundation-and-eigen-labs-partner-to-enable-faster-cheaper-web3-transactions-for-ethereum-rollups-via-eigenlayer/). 3-4 second finality for all Ethereum L2s is much more manageable. diff --git a/docs/2.build/1.chain-abstraction/multichain-gas-relayer/overview.md b/docs/2.build/1.chain-abstraction/multichain-gas-relayer/overview.md deleted file mode 100644 index e5187dfbec..0000000000 --- a/docs/2.build/1.chain-abstraction/multichain-gas-relayer/overview.md +++ /dev/null @@ -1,69 +0,0 @@ ---- -id: overview -title: Multichain Gas Relayer Overview -sidebar_label: Overview ---- - -The Multichain Gas Relayer on NEAR is designed to facilitate cross-chain transactions by managing gas fees and transaction relays across different blockchain networks. - -## What is it? - -The Multichain Gas Relayer is a mechanism designed to enable gas fee payments and transaction relays across multiple blockchains. Gas fees are transaction fees paid to miners or validators to execute operations on a blockchain network. These fees can vary significantly across different blockchains and can pose a barrier to interoperability and seamless transactions between them. - -### Benefits - -1. **Interoperability**: Enables seamless interaction and transactions between different blockchains without the need for users to hold native tokens of each blockchain for gas fees. - -2. **Cost Efficiency**: Reduces the overall cost of cross-chain transactions by optimizing gas fee management and leveraging economies of scale. - -3. **User Experience**: Improves the user experience by abstracting the complexity of managing gas fees across multiple blockchains. - -## System Design - -This section provides an overview of the system design, including the main components, a technical diagram, and a high-level workflow of the Multichain Relayer system. - -### System Components - -1. [**Multichain Relayer Server**](multichain-server.md): This server coordinates the relaying of transactions between NEAR and other blockchains. It listens for signed transaction payloads and submits them to the appropriate foreign chain RPCs. - -2. [**Gas Station Contract**](gas-station.md): A smart contract on NEAR that manages the creation, signing, and relaying of transactions to foreign chains. It also handles gas fee calculations and collects NEAR tokens for gas payments on foreign chains. - -3. [**MPC Signing Service**](../chain-signatures/chain-signatures.md): A network of trusted Multi-Party Computation (MPC) signers that cooperatively sign transactions. This ensures secure transaction signing and validation on the NEAR blockchain before relaying to foreign chains. - -### Technical Diagram - -Below is a design diagram of the entire Multichain Relayer system: - -[![multichain_relayer_technical_design.png](/docs/multichain_relayer_technical_design.png)](/docs/multichain_relayer_technical_design.png) - -:::note - -- The [gas station contract](gas-station.md) and the [MPC signing service contract](https://github.com/near/mpc-recovery/tree/main/contract) are in the green box which take place on NEAR. -- The [multichain relayer server](multichain-server.md) focuses on the blue _Multichain Relayer Core Backend Services_ box in the middle and the connections to the XChain systems in the red box via RPCs. -- The [XChain Settlement](gas-station.md#settlement) process happening in the yellow box can be either manual or automated. [Automated settlement](gas-station.md#automated-settlement) is available for select partners based on their xChain transaction volume. - -::: - -### Workflow - -1. **Transaction Creation**: Users initiate a transaction on NEAR, specifying the foreign chain transaction and attaching NEAR tokens to cover gas fees on the foreign chain. This transaction is sent to the Gas Station Contract. - -2. **Transaction Signing**: The Gas Station Contract invokes the MPC signing service to sign the transaction. This step may require multiple calls due to gas limitations on NEAR, especially for complex transactions. - -3. **Event Emission and Indexing**: Once the transactions are signed, the Gas Station Contract emits an event. The Gas Station Event Indexer picks up this event and triggers the Multichain Relayer Server to relay the signed transactions. - -4. **Relaying Transactions**: The Multichain Relayer Server first sends a funding transaction to ensure the user’s account on the foreign chain has sufficient gas. Once confirmed, it sends the user’s signed transaction to the foreign chain. - ---- - -## Key Features - -- **Paymaster Accounts**: These are accounts on the destination chains that hold the native gas tokens. They ensure users have enough gas to complete their transactions on foreign chains. -- **xChain Settlement**: regular [cross-chain settlement](gas-station.md#settlement) is needed to ensure paymaster accounts have sufficient funds. This can be manual or automated, and involves swapping NEAR tokens for foreign chain tokens and transferring them to the paymaster accounts. - - [Automated settlement](gas-station.md#automated-settlement) is available for select partners based on their cross-chain transaction volume. -- **Supported Chains**: Initially supports BSC, Ethereum, Base, Arbitrum, and Optimism with plans to expand to other chains. - -## Limitations and Considerations - -- **Gas and Slippage**: Users must account for potential gas and slippage issues when using the service. It’s recommended to overestimate gas fees and use high slippage settings in volatile markets. -- **Nonce Management**: Proper management of nonce values is crucial to avoid transaction failures, particularly with concurrent transactions and multiple paymaster accounts. diff --git a/docs/2.build/1.chain-abstraction/multichain-gas-relayer/relayer-gas-example.md b/docs/2.build/1.chain-abstraction/multichain-gas-relayer/relayer-gas-example.md deleted file mode 100644 index 38bfd7c87c..0000000000 --- a/docs/2.build/1.chain-abstraction/multichain-gas-relayer/relayer-gas-example.md +++ /dev/null @@ -1,383 +0,0 @@ ---- -id: relayer-gas-example -title: Multichain Relayer and Gas Station example -sidebar_label: Relayer + Gas Station ---- -import {CodeTabs, Language, Github} from "@site/src/components/codetabs"; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - -In this article you'll learn how to run end-to-end tests on the entire Multichain Relayer system. -You'll find two tests available: an integrated test and a manual test. -The [integration test](#integration-test) is the best way to check that all multichain gas relayer systems are working well together. -[Manual testing](#manual-testing) is a good way to debug issues if any individual part of the system isn't working. - -## Requirements - -Before you start testing, set up your local environment and install the [Relayer server](multichain-server.md), the [Event indexer](https://github.com/near/gas-station-event-indexer) and [NEAR CLI](https://github.com/near/near-cli-rs). - -:::info Required tools - -For this tutorial, you need to have installed: - - - [Python](https://python.org) >=3.10 - - [Rust](https://rust-lang.org) - - [Multichain Relayer Server](https://github.com/near/multichain-relayer-server) - - [Gas Station Event indexer](https://github.com/near/gas-station-event-indexer) - - [NEAR CLI RS](https://github.com/near/near-cli-rs): Make sure to configure it with the correct network and account. - -::: - -## Integration test - -:::tip -This test is the best way to verify that all multichain gas relayer systems are working well together. -::: - -In separate terminals, you need to run the following tools: - -1. [Multichain Relayer server](#multichain-relayer-server), with a valid `config.toml` configuration file -2. [Gas Station indexer](#gas-station-event-indexer), with correct values in `config.toml` -3. [Python integration test script](#run-integration-test) - -### Multichain Relayer server - -The main function of this server is interfacing with foreign chain RPCs sending both pre-signed funding transactions to cover gas and the actual pre-signed transaction once the funding is done. - -To run the [Multichain Relayer Server](https://github.com/near/multichain-relayer-server): - -1. Configure the Multichain Relayer by editing the [`config.toml`](https://github.com/near/multichain-relayer-server/blob/main/config.toml) file -2. Start the multichain relayer server: - ```sh - cargo run - ``` - -:::tip - -Find the Multichain Relayer server source code in [this GitHub repository](https://github.com/near/multichain-relayer-server). - -::: - -### Gas Station Event indexer - -The event indexer is a Python script that picks up events emitted from the [gas station contract](gas-station.md) used for generating signed foreign chain transactions and calls the multichain relayer `/send_funding_and_user_signed_txns` endpoint locally. - -To run the [Gas Station indexer](https://github.com/near/gas-station-event-indexer): - -1. Ensure you have the [Multichain Relayer Server](#multichain-relayer-server) running on `localhost:3030` -2. Create the virtual environment and install requirements: - ```sh - make install - ``` - -3. Update the [`config.toml`](https://github.com/near/gas-station-event-indexer/blob/main/config.toml) configuration file with appropriate values (use `canhazgas.near` for mainnet) - ``` - network = "testnet" - # gas station contract account id - contract_id = "canhazgas.testnet" - ``` - -4. Populate the [environment file](https://github.com/near/gas-station-event-indexer/blob/main/.env.sample) containing AWS credentials for reading from [Near Lake](../../6.data-infrastructure/lake-framework/near-lake.md) - ```sh - cp .env.sample .env - ``` - -4. Run the indexer script: - ```sh - make run - ``` - -:::tip - -Find the Gas Station Event indexer source code in [this GitHub repository](https://github.com/near/gas-station-event-indexer). - -::: - -### Run integration test - -To run the integration test, switch to the `multichain-relayer-server` repository folder and execute the Python script: - -```sh -python3 integration_tests/integration_test.py -``` - -:::tip - -You can use the optional `--verbose` flag to print subprocess output: - -```sh -python3 integration_tests/integration_test.py --verbose -``` - -::: - -## Manual testing - -This section offers instructions on how to manually perform end-to-end tests on the entire multichain relayer system including the gas station contract, indexer, and relayer server. - -:::tip -This test is a good way to debug issues if any individual part of the system isn't working. -::: - -### Test setup - -The following instructions are only need to be called once to initialize the account on the Gas Station. Make sure to replace the `` (string) with the account you want to initialize and `` (integer) with the token id of the NFT you minted in step 2: - -1. Registration / Storage Deposit: - - - - ```bash - near call v2.nft.kagi.testnet storage_deposit '{}' --deposit 1 --gas 100000000000000 --accountId .testnet - ``` - - - - - ```bash - near contract call-function as-transaction v2.nft.kagi.testnet \ - storage_deposit json-args {} prepaid-gas '100.0 Tgas' attached-deposit '1 NEAR' \ - sign-as .testnet network-config testnet sign-with-keychain send - ``` - - -2. Mint NFT - make sure to save the token id from the logs of this call - - - - ```bash - near call v2.nft.kagi.testnet mint '{}' --gas 100000000000000 --accountId .testnet - ``` - - - - - ```bash - near contract call-function as-transaction v2.nft.kagi.testnet \ - mint json-args {} prepaid-gas '100.0 Tgas' attached-deposit '0 NEAR' \ - sign-as .testnet network-config testnet sign-with-keychain send - ``` - - -3. Approve the Gas Station for this Token (use or use `canhazgas.near` for mainnet): - - - - ```bash - near call v2.nft.kagi.testnet ckt_approve_call '{"token_id":"","account_id":"canhazgas.testnet","msg":""}' --gas 100000000000000 --accountId .testnet - ``` - - - - - ```bash - near contract call-function as-transaction v2.nft.kagi.testnet \ - ckt_approve_call json-args '{"token_id":"","account_id":"canhazgas.testnet","msg":""}' \ - prepaid-gas '100.0 Tgas' attached-deposit '0 NEAR' \ - sign-as .testnet network-config testnet sign-with-keychain send - ``` - - - -### Manual test steps - -1. Get paymaster info for the chain you want to send to from the gas station contract, then optionally manually set nonces (use `canhazgas.near` for mainnet): - - - - ```bash - near call canhazgas.testnet get_paymasters '{"chain_id": ""}' --gas 100000000000000 --accountId .testnet - ``` - - - - - ```bash - near contract call-function as-transaction canhazgas.testnet \ - get_paymasters json-args '{"chain_id": ""}' \ - prepaid-gas '100.0 Tgas' attached-deposit '0 NEAR' \ - sign-as .testnet network-config testnet sign-with-keychain send - ``` - - - which returns something like: - ```js - --- Result ------------------------- - [ - { - "foreign_address": "0x98c6C99176911AD4E7fc7413eDF09956B2D7F0F8", - "minimum_available_balance": "99886599999948172000", - "nonce": 28, - "token_id": "1" - } - ] - ------------------------------------ - ``` - 1. You may need to manually set the nonce for the paymaster to be able to send the transaction (use `canhazgas.near` for mainnet): - - - - ```bash - near call canhazgas.testnet get_paymasters '{"chain_id": ""}' --gas 100000000000000 --accountId .testnet - ``` - - - - - ```bash - near contract call-function as-transaction canhazgas.testnet \ - get_paymasters json-args '{"chain_id": ""}' \ - prepaid-gas '100.000 Tgas' \ - attached-deposit '0 NEAR' \ - sign-as .testnet \ - network-config testnet \ - sign-with-keychain send - ``` - - -2. Update the transaction details of the EVM transaction you want to send in `generate_eip1559_rlp_hex()` test in [`tests/tests.rs`](https://github.com/near/multichain-relayer-server/blob/main/tests/tests.rs) then run the script and save the RLP hex string output. - 1. If that doesn't work, try running [`generate_rlp_evm_txn.py`](https://github.com/near/multichain-relayer-server/blob/main/integration_tests/generate_rlp_evm_txn.py) - -:::info - -Python and Rust output different hex RLP encoded transactions. - - If you're using Rust, use [`generate_eip1559_rlp_hex()`](https://github.com/near/multichain-relayer-server/blob/main/tests/tests.rs#L24). - - If you're using Python, use [`generate_rlp_encoded_transaction(is_eip_1559=true)`](https://github.com/near/multichain-relayer-server/blob/main/integration_tests/generate_rlp_evm_txn.py#L7) - - - - - - - - - - -::: - -3. Ensure the [Multichain Relayer server](#multichain-relayer-server) is configured correctly (`config.toml`) and running: - ```sh - cargo run - ``` - -4. Ensure the [Gas Station indexer](#gas-station-event-indexer) is running locally with the correct values in the `config.toml` file - -5. Construct the signed transaction using the [near-cli-rs](https://github.com/near/near-cli-rs). - The receiver account ID should be the gas station contract. - You will need 2 actions if you want the gas station to cover your gas cost on the foreign chain: - - 1 action to send the NEAR equivalent - - 1 function call to the gas station. - - You should transfer the amount of `NEAR` that's needed to cover gas both on NEAR and on the foreign chain. - You also need to paste in the RLP generated hex for the EVM transaction you want on the other chain generated in step 1. - When it asks you to send or display, choose send. - For example (use `canhazgas.near` for mainnet): - - - - - ```bash - near call canhazgas.testnet create_transaction '{"transaction_rlp_hex":"eb80851bf08eb000825208947b965bdb7f0464843572eb2b8c17bdf27b720b14872386f26fc1000080808080","use_paymaster":true,"token_id":""}' --deposit --gas 100000000000000 --accountId .testnet - ``` - - - - - ```bash - near contract call-function as-transaction canhazgas.testnet \ - create_transaction json-args '{"transaction_rlp_hex":"eb80851bf08eb000825208947b965bdb7f0464843572eb2b8c17bdf27b720b14872386f26fc1000080808080","use_paymaster":true,"token_id":""}' \ - prepaid-gas '100.000 TeraGas' attached-deposit ' NEAR' \ - sign-as .testnet \ - network-config testnet sign-with-keychain send - ``` - - - - which returns something like: - ``` - --- Result ------------------------- - { - "id": "29", - "pending_signature_count": 2 - } - ------------------------------------ - ``` -6. Get the `"id"` from the receipts from the result in the previous step, and use that to call `sign_next` twice (use `canhazgas.near` for mainnet): - - - - ```bash - near call canhazgas.testnet sign_next '{"id":""}' --gas 300000000000000 --accountId .testnet - ``` - - - - - ```bash - near contract call-function as-transaction canhazgas.testnet \ - sign_next json-args '{"id":""}' \ - prepaid-gas '300.0 Tgas' \ - attached-deposit '0 NEAR' \ - sign-as .testnet \ - network-config testnet \ - sign-with-keychain send - ``` - - - - > **Note:** this step will be updated soon, as support for yield/resume calls is implemented on MPC contract. - -7. Watch the output of the [gas station event indexer](https://github.com/near/gas-station-event-indexer) to see the transactions being emitted by the gas station contract. - -8. Watch the output of the [multichain relayer server](https://github.com/near/multichain-relayer-server) to see the transactions being sent to the foreign chain. - - - -### Optional for testing purposes - -Instead of creating a signed transaction and calling the gas station contract to sign it, you can get the recently signed transactions by calling the contract while replacing the `blockheight` with a more recent block height (use `canhazgas.near` for mainnet): - - - - - ```bash - near view canhazgas.testnet list_signed_transaction_sequences_after '{"block_height":"157111000"}' --networkId testnet - ``` - - - - - ```bash - near contract call-function as-read-only canhazgas.testnet list_signed_transaction_sequences_after json-args '{"block_height":"157111000"}' network-config testnet now - ``` - - - -This will return something like the output below. Take an individual entry in the list of JSONs and send that as the payload of a `POST` request to the `/send_funding_and_user_signed_txns` endpoint: - -```jsx -[ - { - "created_by_account_id": "b807806adcb73f6aecb5ed98bb8bd7bbe7bbf8ed342596ab700ef6b050abc4c3", - "foreign_chain_id": "97", - "signed_transactions": [ - "0x02f873610385174876e80085174876e80082520894c89663ac6d169bc3e2e0a99d9fe96f2e82bcc307870eebe0b40e800080c080a0712d44ba4cd7567764231e21f054c5e7d008055222820e9d5ba148ede48755f7a06e8b812d37047593fc51fce7254ea7aef89927cada729bc903cd36fa9659dce4", - "0x02f873618085174876e80085174876e80082520894ef55a8bdf4498ea0af88bc54efb29608bb25e130872aa1efb94e000080c080a017d7024fe9e32ad8da1181729fac7e6a45311c47bf59f2b5a8b5e9fe002c0617a04ad725b362cf12c6e066c5b0b7ecbbf08f5e4d0a240337e6ddc8076f0528e3e5" - ] - }, -... - { - "created_by_account_id": "b807806adcb73f6aecb5ed98bb8bd7bbe7bbf8ed342596ab700ef6b050abc4c3", - "foreign_chain_id": "97", - "signed_transactions": [ - "0x02f873610185174876e80085174876e80082520894c89663ac6d169bc3e2e0a99d9fe96f2e82bcc307870eebe0b40e800080c001a0ff19fe769246de8483b986e5aeaa3360bfb74f238e2a91ea353dac9aad9e24a0a020485dcd2c64172b9bc058b7813646dafbf2f27d51aae388b074e514fdb6de05", - "0x02f873618085174876e80085174876e80082520894ef55a8bdf4498ea0af88bc54efb29608bb25e130872e2f6e5e14800080c001a0dac67c383e8de3211f3c5d360cc2e9a21d160711fc3f80113ac525169317e2eca07140a1d0d1528b6eaf9fac4bb1bd44c1c4f63bb956292b0211a0dad1748e2eea" - ] - } -] -``` - diff --git a/website/sidebars.js b/website/sidebars.js index 966ed72d60..323a5d4b54 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -100,21 +100,6 @@ const sidebar = { // 'build/chain-abstraction/nft-chain-keys', ] }, - // 'build/chain-abstraction/wallet', - // { - // "type": "category", - // "label": "Multichain Gas Relayer", - // "link": { - // "type": "doc", - // "id": "build/chain-abstraction/multichain-gas-relayer/getting-started" - // }, - // "items": [ - // "build/chain-abstraction/multichain-gas-relayer/overview", - // "build/chain-abstraction/multichain-gas-relayer/gas-station", - // "build/chain-abstraction/multichain-gas-relayer/multichain-server", - // "build/chain-abstraction/multichain-gas-relayer/relayer-gas-example", - // ] - // }, 'build/chain-abstraction/fastauth-sdk', "build/chain-abstraction/data-availability", ]