diff --git a/docs/3.tutorials/multichain-dao/0-intro.md b/docs/3.tutorials/multichain-dao/0-intro.md new file mode 100644 index 00000000000..d492663e65c --- /dev/null +++ b/docs/3.tutorials/multichain-dao/0-intro.md @@ -0,0 +1,71 @@ +--- +id: introduction +title: Near Multi-Chain DAO Governance +sidebar_label: Introduction +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +Welcome! In this guide, you’ll learn how to effortlessly leverage Near Multi-Chain DAO Contract to sign an EIP-1559 transaction on behalf of decentralized organizations like DAOs or multisigs. + +## Overview + +The [Near Multi-Chain DAO Contract](https://github.com/nearuaguild/abstract-dao) is designed to act as an intermediary between Decentralized Organizations and a Multi-Party Computation (MPC) contract. Its primary purpose is to streamline the governance process for DAO councils by allowing them to vote on proposals once and automatically generate the necessary signatures for the same payload across multiple Ethereum Virtual Machine (EVM) compatible chains — differing only by the chain ID and Gas. + +### Environments + +Currently, there're 2 environments: + +1. Testnet: `abstract-dao.testnet` +2. Dev (unstable): `dev.abstract-dao.testnet` + +### Use Case + +Imagine you are part of a Decentralized Organization that needs to transfer funds across multiple EVM-compatible chains. With the traditional approach, your organization would need to vote separately for each chain, making the process repetitive and time-consuming. + +Here’s how it works with Near Multi-chain DAO: + +1. **Craft an EIP-1559 Payload**: You create the transaction details (the payload), which specify the parameters such as the recipient address, nonce, value, and the data you want to send. This payload remains the same across all chains, with only the chain ID and Gas Fees differing. + +2. **Choose a Single Allowed Account**: As part of the voting process, your organization chooses an "allowed account," which is the member who will be responsible for generating signatures for the transaction across different chains. + +3. **Vote on the Request**: Your decentralized organization votes once to approve this request. Each member can review the transaction, then cast their vote to confirm or reject it. + +4. **Generate Signatures**: Once the request has enough confirmations, the transaction is approved. And the allowed account can proceed with generating signatures for the transaction on as many EVM-compatible chains as needed. + +The result is a drastically simplified governance process (one vote, one confirmation) and the ability to sign and execute transactions across multiple chains in a coordinated manner. + +--- + +## Prerequisites + +To complete this tutorial successfully, you'll need [Near CLI](/tools/near-cli#installation) to be installed. + +Also this guide assumes you will be using a Multisig contract as the Decentralized Organization (DAO) for signing EIP-1559 transactions. + +:::info Deploy Multisig +If you don't have one so far, please download [compiled Wasm file](https://github.com/near/core-contracts/raw/refs/heads/master/multisig2/res/multisig2.wasm) from the repository and deploy it to newly created account. + +::: + +--- + +## Next steps + +This guide significantly overlaps with concepts related to [Chain Signatures](/build/chain-abstraction/chain-signatures/getting-started). Please review it first to gain a better understanding of what's happening if you haven't already. + +Ready to start? Let's jump to the [Signature Generation](./1-signing.md) and begin your learning journey! + +--- + +:::note Versioning for this article + +- near-cli: `0.12.0` +- rustc: `1.78.0` +- cargo: `1.80.1` +- cargo-near: `0.6.2` +- rustc: `1.78.0` +- node: `21.6.1` + +::: diff --git a/docs/3.tutorials/multichain-dao/1-signing.md b/docs/3.tutorials/multichain-dao/1-signing.md new file mode 100644 index 00000000000..d0829e44f7e --- /dev/null +++ b/docs/3.tutorials/multichain-dao/1-signing.md @@ -0,0 +1,189 @@ +--- +id: signing +title: Signing EIP-1559 Transaction +sidebar_label: Signing EIP-1559 Transaction +--- + +In the previous section, we explored the principles and concepts behind the Near Multi-Chain DAO Governance Contract. Now, it's time to put that knowledge into action by actually generating a signature. + +## Step 1: Crafting the EIP-1559 Transaction Payload + +The `register_signature_request` function on the Multi-Chain DAO Governance Contract is used to record the intent to generate a signature for a specific transaction payload. This function allows you to define who can sign the transaction and what the transaction contains. + +Here’s the sample payload you will submit to the contract: + +```json +{ + "request": { + "allowed_account_id": "executor.testnet", + "derivation_seed_number": 0, + "transaction_payload": { + "to": "0xe2a01146FFfC8432497ae49A7a6cBa5B9Abd71A3", + "nonce": "0", + "function_data": { + "function_abi": { + "inputs": [ + { + "internalType": "uint256", + "name": "_num", + "type": "uint256" + } + ], + "name": "set", + "outputs": [], + "stateMutability": "nonpayable", + "type": "function" + }, + "arguments": [ + { + "Uint": "A97" + } + ] + } + } + } +} +``` + +#### Arguments + +- `allowed_account_id`: This is the account allowed to sign the transaction later. It grants permission to this account to generate the required signatures for the transaction. + +- `derivation_seed_number`: This number is used to craft the derivation path along with predecessor account id. Learn more about derivation paths [here](/concepts/abstraction/chain-signatures#derivation-paths-one-account-multiple-chains). + +- `transaction_payload`: This is the actual payload of the transaction that will become EIP-1559 compatible later. In this case, it contains the following: + + - `to`: The recipient address of the transaction. + - `nonce`: The transaction nonce, used to ensure uniqueness. + - `function_data`: (optional) Defines the function that will be called on the recipient's contract. It includes: + - `function_abi`: The ABI of the function being called. + - `arguments`: The input arguments for the function, encoded appropriately. + +:::note +Integer arguments must be base64 encoded +::: + +## Step 2: Creating a Request on the Multisig Contract + +To call `register_signature_request` on the Multi-Chain DAO Governance Contract, you need to submit a request through your Multisig contract. This ensures that the decision to generate a signature is confirmed by the necessary members. + +```bash +near contract call-function as-transaction multisignature.testnet add_request json-args '{ + "request": { + "receiver_id": "abstract-dao.testnet", + "actions": [ + { + "type": "FunctionCall", + "method_name": "register_signature_request", + "args": { + "request": { + "allowed_account_id": "executor.testnet", + "derivation_seed_number": 0, + "transaction_payload": { + "to": "0xe2a01146FFfC8432497ae49A7a6cBa5B9Abd71A3", + "nonce": "0", + "function_data": { + "function_abi": { + "inputs": [ + { + "internalType": "uint256", + "name": "_num", + "type": "uint256" + } + ], + "name": "set", + "outputs": [], + "stateMutability": "nonpayable", + "type": "function" + }, + "arguments": [ + { + "Uint": "A97" + } + ] + } + } + } + }, + "gas": "100000000000000", + "deposit": "0.1" + } + ] + } +}' prepaid-gas '100.0 Tgas' attached-deposit '1 yoctoNEAR' sign-as executor.testnet network-config testnet +``` + +## Step 3: Voting on the Request + +Once the request is submitted, members of the multisig contract have a set amount of time to vote to either Confirm or Reject the request. Each member needs to cast their vote using the following command: + +```bash +near contract call-function as-transaction multisignature.testnet confirm json-args '{"request_id": 1}' prepaid-gas '100.0 Tgas' attached-deposit '1 yoctoNEAR' sign-as account.testnet network-config testnet +``` + +:::note +Replace provided `request_id` with value retrieved from the response when creating the request +::: + +Once the request has received enough confirmations, it will be automatically executed. At this point, the signature request is successfully registered on the Multi-Chain DAO Governance Contract. + +:::info + +Response example returned by Multi-chain DAO Contract + +```json +{ + "allowed_account_id": "denbite.testnet", + "deadline": 1728986555728267025, + "derivation_path": "denbite.testnet-0", + "mpc_account_id": "v1.signer-prod.testnet", + "request_id": 1 +} +``` + +Please pay attention to `deadline` field, which represents the Unix timestamp in the future until which the `get_signature` function is allowed to be executed. Usually, the window is 24 hours after the signature request is registered. + +::: + +Now, the allowed account (specified in the request) can generate signatures for the transaction. + +## Step 4: Signing the Transaction For Different Chain IDs + +To sign a transaction for a specific chain, the following command can be used + +```bash +near contract call-function as-transaction abstract-dao.testnet get_signature json-args '{ + "request_id": 1, + "other_payload": { + "chain_id": 11155111, + "max_fee_per_gas": "1000000000", + "max_priority_fee_per_gas": "100000000" + } +}' prepaid-gas '300.0 Tgas' attached-deposit '0.05 NEAR' sign-as executor.testnet network-config testnet +``` + +:::note + +- Replace provided `request_id` with value returned from `register_signature_request` function (see the response example above). +- Replace provided `chain_id` with destination chain that best fits your case (in this example 11155111 stands for Sepolia Testnet) + +::: + +:::info + +Signature response is going to look similar to the following + +```json +{ + "signature": { + "big_r": { + "affine_point": "02D532992B0ECBF67800DB14E04530D9BA55609AD31213CC7ABDB554E8FDA986D3" + }, + "recovery_id": 1, + "s": { + "scalar": "40E81711B8174712B9F34B2540EE0F642802387D15543CBFC84211BB04B83AC3" + } + }, + "tx": "0x02f85083aa36a702850485034c878517a4eb0789829dd094e2a01146fffc8432497ae49a7a6cba5b9abd71a380a460fe47b1000000000000000000000000000000000000000000000000000000000000a84bc0" +} +``` diff --git a/docs/3.tutorials/multichain-dao/2-relaying.md b/docs/3.tutorials/multichain-dao/2-relaying.md new file mode 100644 index 00000000000..9c73840a6dd --- /dev/null +++ b/docs/3.tutorials/multichain-dao/2-relaying.md @@ -0,0 +1,77 @@ +--- +id: relaying +title: Relaying EIP-1559 Transaction to EVM Network +sidebar_label: Relaying Transaction +--- + +At the end of the previous section, we obtained a signed transaction payload using the Near Multi-Chain DAO Governance Contract. For your use case, it will definitely contain different data, but the structure in general must be similar to the following: + +```json +{ + "signature": { + "big_r": { + "affine_point": "02D532992B0ECBF67800DB14E04530D9BA55609AD31213CC7ABDB554E8FDA986D3" + }, + "recovery_id": 1, + "s": { + "scalar": "40E81711B8174712B9F34B2540EE0F642802387D15543CBFC84211BB04B83AC3" + } + }, + "tx": "0x02f85083aa36a702850485034c878517a4eb0789829dd094e2a01146fffc8432497ae49a7a6cba5b9abd71a380a460fe47b1000000000000000000000000000000000000000000000000000000000000a84bc0" +} +``` + +Now that we have this signed transaction, we need to relay it to the target EVM chain. However, manually sending a transaction to a network doesn't sound exciting for people to do. That's why was developed a [script](https://github.com/nearuaguild/multichain-dao-scripts) to automate this process. + +### Key Advantages + +The script handles all the complexity behind the scenes, ensuring your transactions are sent to the correct network with minimal effort. It does the following: + +- Tranforms signature response of Near Multi-chain DAO Contract into EVM-compatible data format +- Detects Chain ID from the provided transaction data +- Finds an available RPC on the destination chain + +Let's explore further how it can be used. + +### Setting Up + +To use the script, it's needed to be set up on your local machine. Run the following commands to install: + +```bash +git clone https://github.com/nearuaguild/multichain-dao-scripts.git +cd multichain-dao-scripts +yarn install +``` + +### Running the script + +Once the setup is complete, you can use the script to relay your signed transaction to the EVM chain. All you need to do is copy the JSON signature response from the previous section and pass it to the script in single quotes. + +```bash +node relay.mjs '{ + "signature": { + "big_r": { + "affine_point": "02D532992B0ECBF67800DB14E04530D9BA55609AD31213CC7ABDB554E8FDA986D3" + }, + "recovery_id": 1, + "s": { + "scalar": "40E81711B8174712B9F34B2540EE0F642802387D15543CBFC84211BB04B83AC3" + } + }, + "tx": "0x02f85083aa36a702850485034c878517a4eb0789829dd094e2a01146fffc8432497ae49a7a6cba5b9abd71a380a460fe47b1000000000000000000000000000000000000000000000000000000000000a84bc0" +}' +``` + +This process can be repeated as many times as needed for different transactions/chains. + +### Conclusion + +Congratulations on making it through the tutorial! + +Feel free to reach out if you have any questions or feedback. Happy building, and best of luck with your projects! + +:::info + +- [Telegram Chat](https://t.me/neardev) + +::: diff --git a/website/sidebars.js b/website/sidebars.js index 4c3538e9011..f6b0ce220c4 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -505,6 +505,13 @@ const sidebar = { } ] }, + { + "Multi-Chain DAO Governance": [ + "tutorials/multichain-dao/introduction", + "tutorials/multichain-dao/signing", + "tutorials/multichain-dao/relaying", + ] + }, ], "tools": [ "tools/welcome",