From 66a542275b6bcd2010845802ed126ec84a6a6047 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Mon, 18 Mar 2024 09:11:04 -0300 Subject: [PATCH 01/15] chore(deps): bump follow-redirects from 1.15.4 to 1.15.6 in /website (#1821) Bumps [follow-redirects](https://github.com/follow-redirects/follow-redirects) from 1.15.4 to 1.15.6. - [Release notes](https://github.com/follow-redirects/follow-redirects/releases) - [Commits](https://github.com/follow-redirects/follow-redirects/compare/v1.15.4...v1.15.6) --- updated-dependencies: - dependency-name: follow-redirects dependency-type: indirect ... Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --- website/yarn.lock | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/website/yarn.lock b/website/yarn.lock index 0c743f0d042..fb130254cea 100644 --- a/website/yarn.lock +++ b/website/yarn.lock @@ -6762,9 +6762,9 @@ flat@^5.0.2: integrity sha512-b6suED+5/3rTpUBdG1gupIl8MPFCAMA0QXwmljLhvCUKcUvdE4gWky9zpuGCcXHOsz4J9wPGNWq6OKpmIzz3hQ== follow-redirects@^1.0.0, follow-redirects@^1.14.0, follow-redirects@^1.15.4: - version "1.15.4" - resolved "https://registry.yarnpkg.com/follow-redirects/-/follow-redirects-1.15.4.tgz#cdc7d308bf6493126b17ea2191ea0ccf3e535adf" - integrity sha512-Cr4D/5wlrb0z9dgERpUL3LrmPKVDsETIJhaCMeDfuFYcqa5bldGV6wBsAN6X/vxlXQtFBMrXdXxdL8CbDTGniw== + version "1.15.6" + resolved "https://registry.yarnpkg.com/follow-redirects/-/follow-redirects-1.15.6.tgz#7f815c0cda4249c74ff09e95ef97c23b5fd0399b" + integrity sha512-wWN62YITEaOpSK584EZXJafH1AGpO8RVgElfkuXbTOrPX4fIfOyEpW/CsiNd8JdYrAoOvafRTOEnvsO++qCqFA== for-each@^0.3.3: version "0.3.3" From 009c03606ddb7de3f7efe6d0d3b6d2da10522037 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dami=C3=A1n=20Parrino?= Date: Mon, 18 Mar 2024 09:15:03 -0300 Subject: [PATCH 02/15] Apply suggestions from code review --- docs/1.concepts/abstraction/relayers.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/1.concepts/abstraction/relayers.md b/docs/1.concepts/abstraction/relayers.md index 92bde9e1bb6..b93685b959d 100644 --- a/docs/1.concepts/abstraction/relayers.md +++ b/docs/1.concepts/abstraction/relayers.md @@ -11,9 +11,9 @@ A relayer is a simple web service that receives signed transactions from NEAR us ![relayer-overview](/docs/assets/welcome-pages/relayer-overview.png) -Relayers are a natural consequence of [NEP-366: Meta Transactions](https://github.com/near/NEPs/blob/master/neps/nep-0366.md), a special type of transaction which can be best understood as an intent. +Relayers are a natural consequence of [Meta Transactions](meta-tx.md) ([NEP-366](https://github.com/near/NEPs/blob/master/neps/nep-0366.md)), a special type of transaction that can be best understood as an intent. -The user expresses: "I want to do a specific action on chain" and signs this intent **off-chain**, but does not send it to the network. Instead, they send the intent to a `Relayer`, which wraps the message into an actual transaction, attaches the necessary funds, and sends it to the network. +The user expresses: _"I want to do a specific action on chain"_ and signs this intent **off-chain**, but does not send it to the network. Instead, they send the intent to a `Relayer`, which wraps the message into an actual transaction, attaches the necessary funds, and sends it to the network.
Technical Details From 1c0e236f1628fdcef939de2be6d11872abe6e6af Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dami=C3=A1n=20Parrino?= Date: Mon, 18 Mar 2024 09:17:21 -0300 Subject: [PATCH 03/15] Update docs/2.develop/relayers/welcome.md --- docs/2.develop/relayers/welcome.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/2.develop/relayers/welcome.md b/docs/2.develop/relayers/welcome.md index 8e4a5be5c8b..f856c9d2bc6 100644 --- a/docs/2.develop/relayers/welcome.md +++ b/docs/2.develop/relayers/welcome.md @@ -9,7 +9,7 @@ import {CodeTabs, Language, Github} from "@site/src/components/codetabs" Relayers serve to delegate gas fees to a web service, allowing users to transact on NEAR without the need to acquire the token themselves while still retaining the security of signing their own transactions. This guide will lead you through the components necessary to construct a relayer capable of handling meta transactions. -If you're already aquainted with the technology you can fast track to a [working open source example](https://github.com/SurgeCode/near-relay-example) +If you're already acquainted with the technology, you can fast track to a [working open source example](https://github.com/SurgeCode/near-relay-example) For other languages you can check out [Python](https://github.com/here-wallet/near-relay), [Rust](https://github.com/near/pagoda-relayer-rs) From fbaac33b9d5cdb1c50fa01af16237fd8828e9444 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dami=C3=A1n=20Parrino?= Date: Tue, 19 Mar 2024 07:57:56 -0300 Subject: [PATCH 04/15] Apply suggestions from code review --- docs/2.develop/relayers/welcome.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/2.develop/relayers/welcome.md b/docs/2.develop/relayers/welcome.md index f856c9d2bc6..a2ea9fb512f 100644 --- a/docs/2.develop/relayers/welcome.md +++ b/docs/2.develop/relayers/welcome.md @@ -9,8 +9,12 @@ import {CodeTabs, Language, Github} from "@site/src/components/codetabs" Relayers serve to delegate gas fees to a web service, allowing users to transact on NEAR without the need to acquire the token themselves while still retaining the security of signing their own transactions. This guide will lead you through the components necessary to construct a relayer capable of handling meta transactions. +:::tip + If you're already acquainted with the technology, you can fast track to a [working open source example](https://github.com/SurgeCode/near-relay-example) +::: + For other languages you can check out [Python](https://github.com/here-wallet/near-relay), [Rust](https://github.com/near/pagoda-relayer-rs) From 684e28b1f4d5526733ad7780b338cfc972bf0b2b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dami=C3=A1n=20Parrino?= Date: Tue, 19 Mar 2024 07:59:43 -0300 Subject: [PATCH 05/15] Update welcome.md --- docs/2.develop/relayers/welcome.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/2.develop/relayers/welcome.md b/docs/2.develop/relayers/welcome.md index a2ea9fb512f..205423dc871 100644 --- a/docs/2.develop/relayers/welcome.md +++ b/docs/2.develop/relayers/welcome.md @@ -34,7 +34,7 @@ The client can then generate a `SignedDelegateAction` (signed message that isn't - Here a simple express endpoint deserializes the body, instantiates the relayer account and then sends the transaction. + Here's a simple express endpoint deserializes the body, instantiates the relayer account and then sends the transaction. @@ -43,15 +43,15 @@ The client can then generate a `SignedDelegateAction` (signed message that isn't - :::info +:::info The code in the example only works from the following versions onwards - "near-api-js": "3.0.4" - - "@near-js/transactions": "1.1.2", - - "@near-js/accounts": "1.0.4" +``` +"near-api-js": "3.0.4" +"@near-js/transactions": "1.1.2", +"@near-js/accounts": "1.0.4" +``` ::: From bfafad9f39cd4c1c4e8cfe6f35a9c84b4e48a720 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dami=C3=A1n=20Parrino?= Date: Tue, 19 Mar 2024 08:06:39 -0300 Subject: [PATCH 06/15] Update welcome.md --- docs/2.develop/relayers/welcome.md | 24 ++++++++++-------------- 1 file changed, 10 insertions(+), 14 deletions(-) diff --git a/docs/2.develop/relayers/welcome.md b/docs/2.develop/relayers/welcome.md index 205423dc871..a55c3d14281 100644 --- a/docs/2.develop/relayers/welcome.md +++ b/docs/2.develop/relayers/welcome.md @@ -17,20 +17,16 @@ If you're already acquainted with the technology, you can fast track to a [worki For other languages you can check out [Python](https://github.com/here-wallet/near-relay), [Rust](https://github.com/near/pagoda-relayer-rs) - - ## How it works - ![relayer-overview-technical](/docs/assets/welcome-pages/relayer-overview-technical.png) A basic relayer consists of a web server housing a funded NEAR account. This account receives an encoded signed transaction, which can subsequently be decoded into a `SignedDelegate` format and transmitted on-chain. -The client can then generate a `SignedDelegateAction` (signed message that isn't yet sent), encode it, and transmit it to this server, where it will be relayed onto the blockchain. +The client can then generate a `SignedDelegateAction` (a signed message that hasn't yet been sent), encode it, and transmit it to this server, where it will be relayed onto the blockchain. ## Relayer (server) - @@ -82,12 +78,12 @@ The client can then generate a `SignedDelegateAction` (signed message that isn't - As mentioned in the above note in order to be able to relay on the client side its necessary to have access to signing transactions directly on the client. Luckily leveraging the near biometric library its possible to do so in a non custodial way. + As mentioned in the above note in order to be able to relay on the client side it's necessary to have access to signing transactions directly on the client. Luckily leveraging the near biometric library it's possible to do so in a non custodial way. - By calling this method and passing in the url for the account creation endpoint (mentioned in the server section) as well as the accoundId everything is handled under the hood to successfully create an account. + By calling this method and passing in the URL for the account creation endpoint (mentioned in the server section) as well as the `accoundId` everything is handled under the hood to successfully create an account. - On the client side you just need to create an `Action` and pass it into the `relayTransaction` method along with the url of the relayer endpoint discussed in the server section and the id of the receiverId. + On the client side, you just need to create an `Action` and pass it into the `relayTransaction` method along with the URL of the relayer endpoint discussed in the server section and the id of the `receiverId`. @@ -104,8 +100,10 @@ The client can then generate a `SignedDelegateAction` (signed message that isn't ### Gating the relayer -In most production applications its expected to want to be able to gate the relayer to only be used in certain cases. By taking apart the `delegateAction` object inside the `SignedDelegate`on the server this can be done simply. -``` +In most production applications it's expected that you want to be able to gate the relayer to only be used in certain cases. +By taking apart the `delegateAction` object inside the `SignedDelegate`on the server this can be done simply. + +```typescript export declare class DelegateAction extends Assignable { senderId: string; receiverId: string; @@ -115,7 +113,8 @@ export declare class DelegateAction extends Assignable { publicKey: PublicKey; } ``` -We can for example gate by some particular user or contract + +You can, for example, gate by some particular user or contract: ```typescript const serializedTx: Buffer = req.body; @@ -146,6 +145,3 @@ JSON.parse(Buffer.from(args_base64 || "", "base64").toString()) - - - From 2779bb3439b26ab8cdd53e60e981c1b5c6cda750 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dami=C3=A1n=20Parrino?= Date: Tue, 19 Mar 2024 08:07:28 -0300 Subject: [PATCH 07/15] Update welcome.md --- docs/2.develop/relayers/welcome.md | 7 ------- 1 file changed, 7 deletions(-) diff --git a/docs/2.develop/relayers/welcome.md b/docs/2.develop/relayers/welcome.md index a55c3d14281..8b71fec268a 100644 --- a/docs/2.develop/relayers/welcome.md +++ b/docs/2.develop/relayers/welcome.md @@ -138,10 +138,3 @@ You can decode the args using: ``` JSON.parse(Buffer.from(args_base64 || "", "base64").toString()) ``` - - - - - - - From 54f9975b5a33586be6c6114e50cc8c9104e32cdc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dami=C3=A1n=20Parrino?= Date: Wed, 20 Mar 2024 14:39:26 -0300 Subject: [PATCH 08/15] Add example about multi chain relayer + gas station (#1819) --- docs/2.develop/relayers/gas-station.md | 29 ++++ docs/2.develop/relayers/multichain-server.md | 11 +- .../2.develop/relayers/relayer-gas-example.md | 156 ++++++++++++++++++ website/sidebars.js | 1 + 4 files changed, 194 insertions(+), 3 deletions(-) create mode 100644 docs/2.develop/relayers/relayer-gas-example.md diff --git a/docs/2.develop/relayers/gas-station.md b/docs/2.develop/relayers/gas-station.md index e518397b7b0..abac52fb1b7 100644 --- a/docs/2.develop/relayers/gas-station.md +++ b/docs/2.develop/relayers/gas-station.md @@ -30,6 +30,35 @@ Transaction breakdown: 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. + +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 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 ## Contract Interactions diff --git a/docs/2.develop/relayers/multichain-server.md b/docs/2.develop/relayers/multichain-server.md index 8e163a5ccd0..2a406857289 100644 --- a/docs/2.develop/relayers/multichain-server.md +++ b/docs/2.develop/relayers/multichain-server.md @@ -26,6 +26,12 @@ Below is a design diagram of the entire multichain relayer system: - This multichain relayer server focuses on the purple/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 that's happening in the yellow box is currently manual and will be automated in the future. +## 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. ## System workflow @@ -47,9 +53,8 @@ Below is a design diagram of the entire multichain relayer system: ## Supported Chains - BSC testnet -- BSC Mainnet (March 31 2024) -- Solana Testnet (March 31 2024) -- Solana Mainnet (March 31 2024) +- BSC Mainnet (March 27 2024) +- Ethereum Mainnet (March 27 2024) - More chains coming soon! :::info diff --git a/docs/2.develop/relayers/relayer-gas-example.md b/docs/2.develop/relayers/relayer-gas-example.md new file mode 100644 index 00000000000..aa22882d038 --- /dev/null +++ b/docs/2.develop/relayers/relayer-gas-example.md @@ -0,0 +1,156 @@ +--- +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. + +:::info Required tools + +For this tutorial, you'll need to have installed: + + - [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) + +::: + +## Setup + +Before you start testing, set up your local environment and install the Relayer server, the Event indexer and NEAR CLI. + +### 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 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 and activate a Python virtual environment: + ```sh + pip install requirements.txt + ``` + +3. Update the [`config.toml`](https://github.com/near/gas-station-event-indexer/blob/main/config.toml) configuration file with appropriate values + ``` + network = "testnet" + # gas station contract account id + contract_id = "canhazgas.testnet" + ``` + +4. Run the indexer: + ```sh + python3 gas-station-event-indexer.py + ``` + +:::tip + +Find the Gas Station Event indexer source code in [this GitHub repository](https://github.com/near/gas-station-event-indexer). + +::: + +## Running tests + +The gas station contract supports EIP-1559 transactions. + +1. Set the transaction details of the EVM transaction you want to send in [`generate_rlp_evm_txn.py`](https://github.com/near/multichain-relayer-server/blob/5b040611f2dc6c6b405b5ec00d5102e3cc27a65c/integration_tests/generate_rlp_evm_txn.py), run the script, and save the RLP hex string output. + +:::note + +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/5b040611f2dc6c6b405b5ec00d5102e3cc27a65c/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/5b040611f2dc6c6b405b5ec00d5102e3cc27a65c/integration_tests/generate_rlp_evm_txn.py#L7) + +::: + + + + + + + + + + +2. Ensure the [Multichain Relayer server](#multichain-relayer-server) is configured correctly and running. + +3. Ensure the [Gas Station indexer](#gas-station-event-indexer) is running locally. + +4. 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. + Example below: + ```sh + near contract call-function as-transaction canhazgas.testnet create_transaction json-args '{"transaction_rlp_hex":"eb80851bf08eb000825208947b965bdb7f0464843572eb2b8c17bdf27b720b14872386f26fc1000080808080","use_paymaster":true}' prepaid-gas '100.000 TeraGas' attached-deposit '0.5 NEAR' sign-as nomnomnom.testnet network-config testnet sign-with-keychain send + ``` + +5. Get the `"id"` from the receipts from the call in step 4, and use that to call `sign_next` twice: + ```sh + near contract call-function as-transaction canhazgas.testnet sign_next json-args '{"id":"16"}' prepaid-gas '300.0 Tgas' attached-deposit '0 NEAR' sign-as nomnomnom.testnet network-config testnet sign-with-keychain send + ``` + +## Options 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: + +```sh +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 417b3e9265a..64cea3377c7 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -147,6 +147,7 @@ const sidebar = { "Multichain Gas Relayer": [ "develop/relayers/multichain-server", "develop/relayers/gas-station", + "develop/relayers/relayer-gas-example", ] }, ] From 9caaacda65d7974c566ddd78ec977eaec3805193 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dami=C3=A1n=20Parrino?= Date: Wed, 20 Mar 2024 14:39:54 -0300 Subject: [PATCH 09/15] Update frontend.md (#1826) --- docs/2.develop/integrate/frontend.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/docs/2.develop/integrate/frontend.md b/docs/2.develop/integrate/frontend.md index 596ed2808aa..a9c9f5c749c 100644 --- a/docs/2.develop/integrate/frontend.md +++ b/docs/2.develop/integrate/frontend.md @@ -57,7 +57,7 @@ To create a wallet, simply import the `Wallet` object from the module and initia @@ -112,10 +112,10 @@ For this, override the `window.onload` method with a function that calls the `wa @@ -133,10 +133,10 @@ Because of their read-only nature, view methods are **free** to call, and do **n @@ -160,10 +160,10 @@ Signing in is as simple as requesting the `wallet` object to `signIn`, the same @@ -179,7 +179,7 @@ If you instantiated the `Wallet` passing an account for the `createAccessKeyFor` @@ -205,10 +205,10 @@ It is important to notice that, if you ask for money to be attached in the call, @@ -232,10 +232,10 @@ If the method invoked returned a result, you can use the transaction hash to ret From af8378717b8dc85bcd38c12c92442e09eaa430a3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dami=C3=A1n=20Parrino?= Date: Thu, 21 Mar 2024 10:01:51 -0300 Subject: [PATCH 10/15] Update DA light client docs (#1818) * Update light-client.md --- docs/data-availability/light-client.md | 87 +++++++++++++++++++++++++- 1 file changed, 85 insertions(+), 2 deletions(-) diff --git a/docs/data-availability/light-client.md b/docs/data-availability/light-client.md index 0c92bc4fbf2..0e1694380f9 100644 --- a/docs/data-availability/light-client.md +++ b/docs/data-availability/light-client.md @@ -3,8 +3,28 @@ id: light-client title: Light Client --- +# NEAR light client + A trustless off-chain light client for NEAR with DA-enabled features, such as KZG commitments, Reed-Solomon erasure coding & storage connectors. + +## Features + +A fully featured, injectable, dependable implementation of the NEAR light client protocol. + +- **Injectable**: Interoperability with dependencies is very hard to maintain and eventually falls by the wayside. +With the light client being injectable, developers can inject cryptographic semantics and the light client logic should be the same, with the only difference being what environment the application uses. +- **Robust**: With an open source, contributor-friendly effort, stringent semantic versioning and audits, we can be sure that the light client will be robust and maintainable. +- **Dependable**: The Protocol itself should not be dependent on many dependencies which would detract from its usability. Ideally, the light client should be `#[no_std]`, and it should be environment-agnostic. + +:::info + +To learn more, check the [Near light client specification](https://nomicon.io/ChainSpec/LightClient). + +::: + +## Blob verification + The light client provides easy access to transaction and receipt inclusion proofs within a block or chunk. This is useful for checking any dubious blobs which may not have been submitted or validating that a blob has been submitted to NEAR. @@ -15,6 +35,69 @@ A blob submission can be verified by: - once you have the inclusion proof, you can ask the light client to verify the proof for you, or advanced users can manually verify it themselves. - armed with this knowledge, rollup providers can have advanced integration with light clients and build proving systems around it. -In the future, we will provide extensions to light clients such that non-interactive proofs can be supplied for blob commitments and other data availability features. +## Implementations + +At present, there are currently two implementations of the light client. The `std` and the `zk` version. + +### Off-chain client + +This is the first light client that was used to build on the logic of the protocol, it has the greatest environment assumptions and a bunch of dependencies. + +The [off-chain light client](https://github.com/near/near-light-client/tree/master/bin/client), which syncs with the final head of the chain, applies the sync protocol and stores the block producers and the next header. +This is the most basic way to run the light client, you can configure the `${ENVIRONMENT}.toml` to set your trusted checkpoints, state and the host exposed and this will work out of the box, syncing with the state and catching up if needed. + +#### State + +It also stores some information in the state database. This contains a few tries in `sled`, namely block producers, headers and any cachable information used for verification. + +#### Interface + +It exposes an HTTP interface for querying state and providing proofs. +It exposes a JSON-RPC implementation to be more compatible with users already aware of [NEAR RPC](../5.api/rpc/introduction.md) nodes. + +### ZK client + +It's a fully featured light client protocol, providing sync and transaction verification. It exploits STARK acceleration for the STARK-friendly functionality and parallel proving for the Merkle verification. +We aim to also fold verification and syncing with proof recursion so the light client can act lazily, syncing when needed, vs syncing eagerly. + +:::tip + +Check out the ZK light client on the [Succinct network here](https://alpha.succinct.xyz/near/near-light-client). + +::: + +The initial implementation of the ZK light client protocol can be [found here](https://github.com/near/near-light-client/tree/master/nearx). It leverages [Succinct's prover network](https://alpha.succinct.xyz/) and [plonky2x SDK](https://github.com/succinctlabs/succinctx) as a proving system. +This will allow developers to pay for proof generation from the proof market. + + +#### Circuits + +Below are the current circuits for the ZK light client. + +:::note +The current circuits serve only a "one-shot" command style for syncing/verification and no autonomous proving. +::: + +Since the ZK client integrates with a Solidity Contract on chain and the circuit must have a statically aligned size, we have to minimize as much call data as possible, opting to witness verification in the circuit rather than store information. + +##### Sync + +Syncs to the next `head`, either the last header of the next epoch or the next header in the current epoch. + +Public inputs: +- `trusted_header_hash`: This is the last header that was synced or the checkpoint header. We use this to query the header info and witness the header is valid, as well as to ensure the header was once synced. + +Public Outputs: +- `next_header_hash`: The header hash of the next header that has been synced in the protocol. + +##### Verify + +Verifies a batch of transactions/receipts, this wraps the Merkle proof verification of multiple transactions in a parallelised circuit. +This allows us to witness the verification of arbitrary amounts of transactions and only pay for verification on Ethereum once, with the relay of the results for the transactions/receipts calldata being the most fees. + +Public inputs: +- `trusted_header_hash`: The last header that was synced. We can use this to also determine if we need to sync in this verification. And to query the header information. +- `transaction_or_receipt_ids`: The transactions or receipts to be verified. -It's also possible that the light client may be on-chain for the header syncing and inclusion proof verification, but this is a low priority right now. \ No newline at end of file +Public Outputs: +- `transaction_or_receipt_results`: The IDs and the result of their verification From 97c71aa57c126893a99fe0b1216cd08a5f51bc5c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dami=C3=A1n=20Parrino?= Date: Thu, 21 Mar 2024 10:17:20 -0300 Subject: [PATCH 11/15] Update wallet.md (#1829) --- docs/8.abstraction/chain-signatures/wallet.md | 40 ++++++++++++++----- 1 file changed, 29 insertions(+), 11 deletions(-) diff --git a/docs/8.abstraction/chain-signatures/wallet.md b/docs/8.abstraction/chain-signatures/wallet.md index dd88be8dd63..b1fc402158f 100644 --- a/docs/8.abstraction/chain-signatures/wallet.md +++ b/docs/8.abstraction/chain-signatures/wallet.md @@ -43,29 +43,47 @@ The user would approve the `SOL` transaction but the attacker would also get the This can be solved by having different keys for any chains that you can't prove could have ambiguous transactions. This means that while an attacker may create ambiguous transactions, it will only be for wallets without assets on the target chain. -## Structure +## Serialization format -This is the chain signature key format structure: +We're using the following format for our derivations paths. +```typescript +{ + chain: number, // SLIP-44 coin type unsigned integer + domain: String, // The domain that owns this key + meta: any, // Catch all data structure +} ``` -| account | chain | domain | subkey | -"david.near,bitcoin,near.org,somedata" -``` -:::warning Under development +This is encoded in canonical [JSON RFC 8785](https://www.rfc-editor.org/rfc/rfc8785). + +:::info +If you are not using a field don't make it `null`, don't include the key instead. +::: + +### User-defined fields -Please keep in mind that this format is under development and changes could be added in the future. +For user-defined fields, the `meta` field can include any data you like. +:::tip +Do not add any extra fields at the top level, as that may clash with future versions of this specification. If needed, put them in the `meta` field instead. ::: +For example, a simple way of selecting alternate keys will be using an object with an `ID` field: + +```typescript +{ + meta: {id: 10}, // Pick the tenth bitcoin key + chain: 0, +} +``` + ### Examples | Key | Description | |-----|-------------| -| `david.near,,,` | Personal untyped key, probably never used by a client | -| `david.near,bitcoin,,` | Personal bitcoin key | -| `david.near,bitcoin,near.org,` | A bitcoin key used on `near.org` | -| `david.near,,near.org,` | An untyped key used on `near.org` | +| `{chain: 0, domain: "near.org"}` | A bitcoin key used on `near.org` | +| `{chain: 0, meta: {id: 3}}` | Use the third bitcoin key | ## Example user flows From 0a03d403f1bbdb0cea5487ac0012b04b0a925188 Mon Sep 17 00:00:00 2001 From: Josh Ford Date: Thu, 21 Mar 2024 19:52:57 -0700 Subject: [PATCH 12/15] add alpha tag to chain signatures & multichain relayer (#1835) --- docs/1.concepts/abstraction/chain-signatures.md | 6 ++++++ docs/1.concepts/abstraction/signatures/use-case.md | 6 ++++++ docs/2.develop/relayers/gas-station.md | 5 +++++ docs/2.develop/relayers/multichain-server.md | 6 ++++++ docs/2.develop/relayers/relayer-gas-example.md | 6 ++++++ docs/8.abstraction/chain-signatures.md | 6 ++++++ docs/8.abstraction/chain-signatures/wallet.md | 6 ++++++ 7 files changed, 41 insertions(+) diff --git a/docs/1.concepts/abstraction/chain-signatures.md b/docs/1.concepts/abstraction/chain-signatures.md index 510bdac2c0d..59b8c74b0ed 100644 --- a/docs/1.concepts/abstraction/chain-signatures.md +++ b/docs/1.concepts/abstraction/chain-signatures.md @@ -4,6 +4,12 @@ title: What are Chain Signatures? sidebar_label: What are Chain Signatures? --- +:::caution + +This technology is currently in `Alpha` and should only be used in a `testnet` environment. + +::: + Chain signatures enable NEAR accounts, including smart contracts, to sign and execute transactions across many blockchain protocols. This unlocks the next level of blockchain interoperability by giving ownership of diverse assets, cross-chain accounts, and data to a single NEAR account. diff --git a/docs/1.concepts/abstraction/signatures/use-case.md b/docs/1.concepts/abstraction/signatures/use-case.md index 5a7f5cbf533..9f474157feb 100644 --- a/docs/1.concepts/abstraction/signatures/use-case.md +++ b/docs/1.concepts/abstraction/signatures/use-case.md @@ -4,6 +4,12 @@ title: Use cases for Chain Signatures sidebar_label: Use cases --- +:::caution + +This technology is currently in `Alpha` and should only be used in a `testnet` environment. + +::: + Chain signatures enable you to implement multichain and cross-chain workflows in a simple way. Take a look at a few possible use cases: diff --git a/docs/2.develop/relayers/gas-station.md b/docs/2.develop/relayers/gas-station.md index abac52fb1b7..36f1a792759 100644 --- a/docs/2.develop/relayers/gas-station.md +++ b/docs/2.develop/relayers/gas-station.md @@ -3,6 +3,11 @@ id: gas-station title: Multichain Gas Station Contract sidebar_label: Multichain Gas Station --- +:::caution + +This technology is currently in `Alpha` and should only be used in a `testnet` environment. + +::: 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. diff --git a/docs/2.develop/relayers/multichain-server.md b/docs/2.develop/relayers/multichain-server.md index 2a406857289..249e912d0aa 100644 --- a/docs/2.develop/relayers/multichain-server.md +++ b/docs/2.develop/relayers/multichain-server.md @@ -4,6 +4,12 @@ title: Multichain Relayer Server sidebar_label: Multichain Relayer Server --- +:::caution + +This technology is currently in `Alpha` and should only be used in a `testnet` environment. + +::: + The [Multichain Relayer Server](https://github.com/near/multichain-relayer-server) facilitates cross-chain transactions and enables Chain Abstraction. ## Overview diff --git a/docs/2.develop/relayers/relayer-gas-example.md b/docs/2.develop/relayers/relayer-gas-example.md index aa22882d038..fb329fd31d6 100644 --- a/docs/2.develop/relayers/relayer-gas-example.md +++ b/docs/2.develop/relayers/relayer-gas-example.md @@ -7,6 +7,12 @@ import {CodeTabs, Language, Github} from "@site/src/components/codetabs" import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; +:::caution + +This technology is currently in `Alpha` and should only be used in a `testnet` environment. + +::: + In this article you'll learn how to run end-to-end tests on the entire Multichain Relayer system. :::info Required tools diff --git a/docs/8.abstraction/chain-signatures.md b/docs/8.abstraction/chain-signatures.md index e28d344b76a..fbb48703b84 100644 --- a/docs/8.abstraction/chain-signatures.md +++ b/docs/8.abstraction/chain-signatures.md @@ -7,6 +7,12 @@ import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import {CodeTabs, Language, Github} from "@site/src/components/codetabs" +:::caution + +This technology is currently in `Alpha` and should only be used in a `testnet` environment. + +::: + Chain signatures enable NEAR accounts, including smart contracts, to sign and execute transactions across many blockchain protocols. This unlocks the next level of blockchain interoperability by giving ownership of diverse assets, cross-chain accounts, and data to a single NEAR account. diff --git a/docs/8.abstraction/chain-signatures/wallet.md b/docs/8.abstraction/chain-signatures/wallet.md index b1fc402158f..e4775779459 100644 --- a/docs/8.abstraction/chain-signatures/wallet.md +++ b/docs/8.abstraction/chain-signatures/wallet.md @@ -3,6 +3,12 @@ id: wallet title: Wallet Chain Key Rules --- +:::caution + +This technology is currently in `Alpha` and should only be used in a `testnet` environment. + +::: + ## Overview In this article you'll find details on how to parse and present multichain transactions to the user so they can take an informed decision about their wallet's assets, while minimizing the number of times the user has to consent. From 4689ab8c75ef079e8ca61d206c94dc3d70134eb0 Mon Sep 17 00:00:00 2001 From: Josh Ford Date: Thu, 21 Mar 2024 19:58:19 -0700 Subject: [PATCH 13/15] update Ripple to XRP Ledger (#1836) --- docs/1.concepts/abstraction/signatures/use-case.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/1.concepts/abstraction/signatures/use-case.md b/docs/1.concepts/abstraction/signatures/use-case.md index 9f474157feb..76b5e52bec2 100644 --- a/docs/1.concepts/abstraction/signatures/use-case.md +++ b/docs/1.concepts/abstraction/signatures/use-case.md @@ -86,7 +86,7 @@ This allows easy on-boarding to decentralized apps. The accounts are initially r ## DeFi on Bitcoin (and other non-smart contract chains). -Using chain signatures, smart contracts on NEAR can control externally-owned accounts on non-smart contract chains like Bitcoin, Dogecoin, Ripple, Bittensor, Cosmos Hub, etc. This enables developers to use NEAR as a smart contract β€œlayer” for chains that do not support this functionality natively. +Using chain signatures, smart contracts on NEAR can control externally-owned accounts on non-smart contract chains like Bitcoin, Dogecoin, XRP Ledger, Bittensor, Cosmos Hub, etc. This enables developers to use NEAR as a smart contract β€œlayer” for chains that do not support this functionality natively. For example, a developer can build a decentralized exchange for Bitcoin Ordinals, using a smart contract on NEAR to manage deposits (into Bitcoin addresses controlled by the contract) and to verify and execute swaps when two users agree to trade BTC for an Ordinal or BRC20 token. From d2720b76030f73a2a2fcf4a36339009c1579d41d Mon Sep 17 00:00:00 2001 From: matiasbenary Date: Fri, 22 Mar 2024 07:42:44 -0300 Subject: [PATCH 14/15] feat: update rs counter example (#1809) Co-authored-by: Matias Benary --- docs/3.tutorials/examples/count-near.md | 16 ++++++---------- 1 file changed, 6 insertions(+), 10 deletions(-) diff --git a/docs/3.tutorials/examples/count-near.md b/docs/3.tutorials/examples/count-near.md index 0a086583309..19a13fc04c2 100644 --- a/docs/3.tutorials/examples/count-near.md +++ b/docs/3.tutorials/examples/count-near.md @@ -56,14 +56,10 @@ The example is divided in two main components: ```bash -β”Œβ”€β”€ sandbox-ts # sandbox testing -β”‚ β”œβ”€β”€ src -β”‚ β”‚ └── main.ava.ts -β”‚ β”œβ”€β”€ ava.config.cjs -β”‚ └── package.json -β”œβ”€β”€ src # contract's code +β”Œβ”€β”€ src # contract's code β”‚ └── lib.rs -β”œβ”€β”€ build.sh # build script +β”œβ”€β”€ tests # sandbox test +β”‚ └── test_basics.rs β”œβ”€β”€ Cargo.toml # package manager β”œβ”€β”€ README.md └── rust-toolchain.toml @@ -129,7 +125,7 @@ The contract presents 4 methods: `get_num`, `increment`, `decrement`, and `reset + start="22" end="47" /> @@ -153,7 +149,7 @@ yarn test ```bash cd contract-rs - ./test.sh + cargo test ``` @@ -192,7 +188,7 @@ near create-account --useFaucet # Deploy the contract cd contract-rs -./build.sh +cargo build near deploy ./target/wasm32-unknown-unknown/release/counter.wasm ``` From 5a6b835454abb17059a9b4911a25082464a10d71 Mon Sep 17 00:00:00 2001 From: Joe <103778941+joe-rlo@users.noreply.github.com> Date: Fri, 22 Mar 2024 06:43:11 -0400 Subject: [PATCH 15/15] Updated intro.md commands (#1830) Updated the commands for create-near-app to match the current flag choices --- docs/sdk/rust/intro.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/sdk/rust/intro.md b/docs/sdk/rust/intro.md index 74e6fe18942..dfd0c1bb17c 100644 --- a/docs/sdk/rust/intro.md +++ b/docs/sdk/rust/intro.md @@ -24,10 +24,10 @@ rustup target add wasm32-unknown-unknown ## Create a new project -The best way to create a new NEAR app connected with a frontend is through [create-near-app](https://github.com/near/create-near-app). When initializing the project, be sure to include the `--contract=rust` flag to use the Rust SDK. Add `--frontend=react` to use react. Default is vanilla HTML. +The best way to create a new NEAR app connected with a frontend is through [create-near-app](https://github.com/near/create-near-app). When initializing the project, your option are `npx create-near-app [--frontend next|vanilla|none] [--contract rs|ts|none --tests rs|ts|none]`. ```bash -npx create-near-app my-project --contract rust --frontend none --tests rust +npx create-near-app my-project --contract rs --frontend none --tests rs ``` If you only wish to develop and deploy a Rust contract, the [status message example](https://github.com/near-examples/rust-status-message) is great to use as a template or through [cargo-generate](https://github.com/cargo-generate/cargo-generate).