diff --git a/docs/2_System Design/5_neox-integration.md b/docs/2_System Design/5_neox-integration.md new file mode 100644 index 0000000..fa9efc2 --- /dev/null +++ b/docs/2_System Design/5_neox-integration.md @@ -0,0 +1,107 @@ +--- +--- + +# NeoX Integration + +## Overview + +GrantShares extends beyond Neo N3 to support cross-chain functionality with NeoX, an EVM-compatible sidechain. This integration enables the DAO to create and execute proposals on NeoX, bridging assets between Neo N3 and NeoX seamlessly. + +The NeoX integration consists of three primary components: +- **GrantSharesRelayer** (Solidity) - Deployed on NeoX +- **GrantSharesBridgeAdapter** (neow3j) - Deployed on Neo N3 +- **Backend Event Monitor** - Monitors NeoX events and triggers N3 transactions + +## Architecture + +### High-Level Flow Diagram + +``` +┌──────────────┐ ┌──────────────────┐ ┌─────────────────┐ ┌───────────────┐ +│ User/dApp │ │ NeoX │ │ Backend │ │ Neo N3 │ +│ │ │ │ │ │ │ │ +│ │────1───▶│ Relayer Contract │ │ │ │ │ +│ │ propose │ Emits Event │────2───▶│ Event Monitor │ │ │ +│ │ │ │ │ │────3───▶│ GrantSharesGov│ +│ │ │ │ │ Calls N3 │ │ createProposal│ +│ │ │ │ │ │ │ │ +│ │ │ │ │ │ │ │ +│ │────4───▶│ Relayer Contract │ │ │ │ [Voting...] │ +│ │ execute │ Emits Event │────5───▶│ Event Monitor │ │ │ +│ │ │ │ │ │────6───▶│ GrantSharesGov│ +│ │ │ │ │ Calls N3 │ │ execute() │ +│ │ │ │ │ │ │ │ │ +│ │ │ │ │ │ │ ▼ │ +│ │ │ │ │ │ │ Treasury │ +│ │ │ │ │ │ │ │ │ +│ │ │ │ │ │ │ ▼ │ +│ │ │ │ │ │ │ BridgeAdapter │ +│ │ │ │ │ │ │ │ │ +│ │ │ ◀────────────────┼─────────┼─────────────────┼─────────┤ ▼ │ +│ │◀────7───│ Funds Received │ │ │ │ Neo X Bridge │ +└──────────────┘ └──────────────────┘ └─────────────────┘ └───────────────┘ +``` + +### Flow Description + +#### Proposal Creation Flow + +1. **Event Emission on NeoX**: User or dApp calls `propose()` on the `GrantSharesRelayer` contract + - Pays `proposalFee` in ETH + - Emits `CreateProposal` event with: + - `sender`: Address of proposer (indexed) + - `proposal`: Struct containing `intents`, `offchainUri`, and `linkedProposal` + +2. **Backend Captures Event**: The backend's `ChainMonitorService` monitors NeoX blocks + - Listens for `CreateProposal` events using Web3j event filtering + - Validates the event data via `EvmEventValidatorService` + - Extracts proposal data including `offchainUri` (GitHub issue URL) and `linkedProposal` ID + +3. **Backend Calls N3 Contract**: The `NeoTransactionService` creates and sends a transaction + - Calls `createProposal()` on the `GrantSharesGov` contract + - Parameters: proposer address, intents, offchainUri, linkedProposal + - Uses backend account credentials for signing + - Proposal enters standard GrantShares voting workflow + +#### Proposal Execution Flow + +4. **Event Emission on NeoX**: User or dApp calls `execute()` on the `GrantSharesRelayer` contract + - Pays `executionFee` in ETH + - Emits `ExecuteProposal` event with: + - `proposalId`: On-chain ID of proposal to execute (indexed) + +5. **Backend Captures Event**: The backend's `ChainMonitorService` monitors NeoX blocks + - Listens for `ExecuteProposal` events + - Validates the event and retrieves the corresponding proposal from database + - Verifies proposal is in `Accepted` state and ready for execution + +6. **Backend Calls N3 Contract**: The `NeoTransactionService` executes the proposal + - Calls `execute()` on the `GrantSharesGov` contract with the proposal ID + - Uses special signers configuration: + - `AccountSigner.none(backendAccount)` - Backend account + - `ContractSigner.calledByEntry(BridgeAdapter)` - Allows bridge adapter to call GAS/NEO contracts + - The execution triggers the proposal's intents in sequence: + +7. **Funds Transfer and Bridging**: + - **Treasury Transfer**: Tokens move from `GrantSharesTreasury` to `GrantSharesBridgeAdapter` + - **Bridge Call**: The adapter calls `bridge(token, to, amount)`: + - Validates token type (GAS or NEO only) + - Checks balance is sufficient for amount + bridge fees + - Calls the Neo X Bridge contract: + - `depositNative()` for GAS tokens + - `depositToken()` for NEO tokens + - Validates no excess tokens remain (except up to `maxFee` for GAS) + - **Bridge Processing**: Neo X Bridge ensures funds arrive at the recipient's NeoX address + - **Recipient Receives**: Funds become available on the NeoX address specified in the proposal + +### Components + +#### 1. GrantSharesRelayer (NeoX - Solidity) + +The **GrantSharesRelayer** is an upgradeable Solidity contract deployed on NeoX that serves as an event emitter and fee gate for cross-chain proposals. + +**Key Features:** +- **Event-based Architecture**: Emits events captured by the backend for relay to Neo N3 +- **Fee System**: Requires payment of configurable fees to prevent spam +- **Pausable**: Can be paused by the contract owner in case of emergencies +- **Upgradeable**: Uses UUPS (Universal Upgradeable Proxy Standard) upgrade pattern diff --git a/docs/3_Implementation/1_structure.md b/docs/3_Implementation/1_structure.md index 0e8f82e..1c81132 100644 --- a/docs/3_Implementation/1_structure.md +++ b/docs/3_Implementation/1_structure.md @@ -3,6 +3,8 @@ # Code Structure +## Neo N3 Contracts + The [smart contract repository](https://github.com/axlabs/grantshares-contracts) has three source sets: `main`, `test`, and `deploy`. @@ -16,4 +18,18 @@ Contains automated contract tests. The tests make use of neow3j's test library. docs](https://neow3j.io) for more information. **deploy** -The deploy source set contains code for manually deploying and invoking the contracts on a private net, testnet and mainnet. \ No newline at end of file +The deploy source set contains code for manually deploying and invoking the contracts on a private net, testnet and mainnet. + +## NeoX Contracts + +In addition to the Neo N3 contracts, GrantShares includes smart contracts for NeoX integration located in the same repository: + +**Solidity Contracts** (in `src/main/solidity/`) + +- **GrantSharesRelayer.sol**: An upgradeable Solidity contract deployed on NeoX that serves as an event relayer for cross-chain proposals. It uses OpenZeppelin's upgradeable contract patterns (UUPS proxy) and includes pausability and ownership controls. + +**Bridge Adapter** (in `src/main/java/com/axlabs/neo/grantshares/`) + +- **GrantSharesBridgeAdapter.java**: A NeoVM smart contract that interfaces between the GrantShares governance system and the Neo X Bridge. It handles the secure transfer of assets from Neo N3 to NeoX as part of proposal execution. + +These contracts work together to enable cross-chain proposal execution and asset transfers. See the [NeoX Integration](../2_System%20Design/5_neox-integration.md) section for detailed architecture information. diff --git a/docs/3_Implementation/2_methods.md b/docs/3_Implementation/2_methods.md index a195369..3fe457f 100644 --- a/docs/3_Implementation/2_methods.md +++ b/docs/3_Implementation/2_methods.md @@ -45,6 +45,18 @@ The `removeWhitelistedToken` method on `GrantShraresTreasury` allows removing a The `setFundersMultiSigThresholdRatio` method on `GrantSharesTreasury` allows setting the ratio used when calculating the funders multi-sig threshold. E.g., if it is set to 50, the threshold will be half of the number of funders. +**Bridge Assets to NeoX** + +The `bridge` method on `GrantSharesBridgeAdapter` enables transferring tokens from Neo N3 to NeoX via the Neo X Bridge. This method can only be invoked by the `GrantSharesGov` contract as part of a proposal execution. It supports bridging GAS and NEO tokens to specified NeoX addresses. + +Parameters: +- `token`: The Hash160 of the token to bridge (GAS or NEO) +- `to`: The recipient address on NeoX +- `amount`: The amount of tokens to bridge + +The method automatically handles bridge fees and validates that no excess tokens remain in the adapter after the transfer (except for an allowed `maxFee` amount in GAS). + + ## Methods to be invoked by the member or funder multi-sig address Because of security considerations we decided to have several methods that can be called by GrantShares members and funders directly and don’t require a proposal. Of course these methods cannot be executed by single addresses. The authorisation is only given to the multi-sig address made up of all member public keys for `GrantSharesGov` and all funder public keys for `GrantSharesTreasury`. The signing threshold of these multi-sig addresses is determined by parameters set in the contracts’ storages. The methods that can be invoked by the multi-sig addresses are the following. @@ -67,4 +79,4 @@ Some proposal related methods can be called by anyone: `createProposal` and `exe The rest of the proposal related methods can only be called by the GrantShares members: `endorseProposal` and `vote`. -The method `voteCommitteeMemberWithLeastVotes` on `GrantSharesTreasury` can be called by anyone. Its only effect is that it revotes on the Neo committee member with the least votes. \ No newline at end of file +The method `voteCommitteeMemberWithLeastVotes` on `GrantSharesTreasury` can be called by anyone. Its only effect is that it revotes on the Neo committee member with the least votes. diff --git a/docs/3_Implementation/3_configuration.md b/docs/3_Implementation/3_configuration.md index af53b2a..dbe1a41 100644 --- a/docs/3_Implementation/3_configuration.md +++ b/docs/3_Implementation/3_configuration.md @@ -18,4 +18,25 @@ Both contracts have to be configured at deploy time. The configuration can later - Funders: The addresses and public keys of the funders that are allowed to send tokens to the treasury contract. A funder can be a multi-sig address. On registration all the involved public keys of the multi-sig address are necessary because they will be used in the funders multi-sig address. - Whitelisted tokens with maximum funding amounts: Funders are only allowed to send whitelisted tokens to the treasury. Each whitelisted token is associated with a maximum funding amount that cannot be exceeded in a proposal. -- Signing threshold ratio for the funders multi-sig address: This is a percentage of the total number of funders (rather, their public keys). It determining the threshold of the multi-sig address, e.g., necessary for draining the treasury’s funds. \ No newline at end of file +- Signing threshold ratio for the funders multi-sig address: This is a percentage of the total number of funders (rather, their public keys). It determining the threshold of the multi-sig address, e.g., necessary for draining the treasury’s funds. + +**Bridge Adapter Contract** + +The `GrantSharesBridgeAdapter` requires the following configuration at deployment: + +- Initial Owner: The address with administrative control over the adapter +- GrantSharesGov Contract: The hash of the governance contract (only this contract can invoke the bridge function) +- GrantSharesTreasury Contract: The hash of the treasury contract (can send tokens to the adapter) +- Bridge Contract: The hash of the Neo X Bridge contract to interact with +- Initial Max Fee: The maximum amount of GAS that can remain in the adapter after bridging (to cover variable bridge fees) +- Initial Whitelisted Funder: An address allowed to send GAS to the adapter for bridge fee funding + +**Relayer Contract (NeoX)** + +The `GrantSharesRelayer` on NeoX requires configuration at initialization: + +- Initial Owner: The address with administrative control (for pause, unpause, fee updates, withdrawals) +- Proposal Fee: The amount of ETH required to create a proposal on NeoX +- Execution Fee: The amount of ETH required to execute a proposal on NeoX + +Both fee amounts can be updated later by the owner via `setProposalFee` and `setExecutionFee` methods. diff --git a/docs/4_User Manual/1_Project-Proposals.md b/docs/4_User Manual/1_Project-Proposals.md index d7c4b10..8cffd4c 100644 --- a/docs/4_User Manual/1_Project-Proposals.md +++ b/docs/4_User Manual/1_Project-Proposals.md @@ -5,6 +5,8 @@ The most important functionality of GrantShrares is explained here: **How to create a successful project proposal?** +For projects that require deployment on NeoX, see more details in the dedicated [Cross-Chain Proposals](4_Cross-Chain-Proposals.md) guide. Cross-chain proposals enable transferring assets from Neo N3 to NeoX via the Neo X Bridge as part of the proposal execution. + ## Prerequisites ### GitHub Authentication diff --git a/docs/4_User Manual/4_Cross-Chain-Proposals.md b/docs/4_User Manual/4_Cross-Chain-Proposals.md new file mode 100644 index 0000000..5d126ff --- /dev/null +++ b/docs/4_User Manual/4_Cross-Chain-Proposals.md @@ -0,0 +1,143 @@ +# Creating Cross-Chain Proposals + +This guide explains how to create a proposal that bridges assets from Neo N3 to NeoX and executes actions on the NeoX network. + +## What is a Cross-Chain Proposal? + +A cross-chain proposal enables the GrantShares DAO to fund projects building on NeoX by transferring funds from the Neo N3 treasury to NeoX + +The proposal goes through the same voting process as regular proposals but includes additional steps to bridge assets and relay execution to NeoX. + +## Prerequisites + +Before creating a cross-chain proposal, ensure you have: + +1. A **NeoX wallet address** where you want to receive funds +2. **Clear project requirements** that specify why NeoX funding is needed +3. Understanding of **NeoX-specific development** considerations +4. **ETH on NeoX** for paying proposal and execution fees (if you plan to execute the proposal yourself) + +## Creating Your Proposal + +### Step 1: Proposal Details + +When creating your proposal in the GrantShares app: + +1. Select **"Request for funding"** as the proposal type +2. In the **Title** and **Proposal details**, state: + - That this is a NeoX-based project + - Why the project requires deployment on NeoX + +3. In the funding request section: + - Enter the amount in GAS or NEO + - **Important**: Enter your **NeoX address** (0x... format), not a Neo N3 address + - The system will automatically configure the bridge intents + +### Step 2: Understanding the Intents + +Your cross-chain proposal will include multiple intents that execute in sequence: + +1. **Transfer fee from Treasury to Bridge Adapter**: Moves GAS tokens from the treasury to the bridge adapter contract +2. **Transfer requested funds from Treasury to Bridge Adapter**: Moves requested tokens from the treasury to the bridge adapter contract +3. **Bridge to NeoX**: Calls the bridge adapter to transfer tokens to NeoX + + +You don't need to manually specify these intents—the GrantShares backend generates them automatically for cross-chain proposals. + +## Voting and Execution + +### Voting Phase + +The voting process is identical to standard proposals: +- Requires endorsement from a GrantShares member +- 7-day voting period +- Requires quorum and acceptance rate to pass +- 3-day time lock after approval + +### Execution + +After the time lock period: + +1. Navigate to your proposal page +2. Click **"Execute Proposal"** +3. Confirm the transaction in your wallet (requires GAS for transaction fees) +4. The execution will: + - Emit events for NeoX relayer + - Initiate the N3 execution of the intents: + - Transfer fee from treasury to bridge adapter + - Transfer requested tokens from treasury to bridge adapter + - Initiate the cross-chain bridge transfer + +After the Neo N3 execution completes you will have to wait for the bridge transfer to complete (up to a few minutes), then your tokens will be available at the specified NeoX address + +## Fees and Costs + +### For Proposers + +- **NeoX Fees**: You'll need GAS (native coin) on NeoX for: + - Proposal creation fee (configurable, check current rates) + - Execution fee (configurable, check current rates) +These fees are paid on NeoX and are used to offset the costs of the relayer sending the N3 transactions. Proposers must ensure they have sufficient GAS on NeoX to cover these fees. + +### For the DAO + +- **Neo N3 Transaction Fees**: Small amount of GAS (typically < 0.1 GAS) to create and execute the proposal on N3 +- **Bridge Fees**: The Neo X Bridge charges fees for cross-chain transfers (paid in GAS from the treasury) +- **Relayer Fees**: Operational costs for the off-chain relayer service + +## Example Use Case + +**Scenario**: A developer wants 100 GAS to build a DeFi dApp on NeoX. + +1. Developer creates a proposal with: + - Title: "Build DEX Aggregator on NeoX" + - Details: Project description, milestones, NeoX deployment benefits + - Amount: 100 GAS + - Recipient: `0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb` (NeoX address) + +2. Proposal goes through discussion, endorsement, and voting + +3. After approval and time lock, developer executes the proposal + +4. Tokens are bridged to NeoX and appear at the developer's NeoX address + +5. Developer builds and deploys the dApp on NeoX + +## Troubleshooting + +**"Bridge transfer hasn't arrived"** +- Check the Neo X Bridge explorer for transfer status +- Bridge transfers may sometimes take 5-15 minutes +- Contact GrantShares via the GitHub discussions if the transfer is delayed beyond 30 minutes + +**"Insufficient GAS for execution"** +- Ensure your wallet has enough GAS for transaction fees on N3 +- For NeoX execution, ensure you have sufficient ETH + +**"Invalid NeoX address"** +- Verify your address starts with `0x` and is a valid Ethereum-style address +- NeoX addresses are different from Neo N3 addresses +- If an EVM wallet is connected, the recipient address will be auto-completed with the connected wallet address, but you can edit it if needed + +## Best Practices + +1. **Double-Check Addresses**: Ensure your NeoX address is correct—blockchain transactions are irreversible +2. **Monitor Bridge Status**: Keep track of your bridge transfer using the Neo X Bridge explorer +3. **Account for Fees**: Request slightly more than your project requires to account for bridge fees +4. **Document Your Project**: Provide clear documentation of why NeoX is necessary for your project + +## Additional Resources + +- [Neo X Bridge Documentation](https://xdocs.ngd.network/bridge/general) +- [NeoX Explorer](https://xexplorer.neo.org/) + +## FAQ + +**Q: Can I bridge NEO tokens to NeoX?** +A: Yes, the bridge adapter supports both GAS and NEO. Specify NEO as your token type when creating the proposal. + +**Q: Who pays for the relayer fees?** +A: The user creating the proposal pays the NeoX proposal and execution fees in GAS on NeoX. The DAO covers the Neo N3 transaction fees and bridge transfer fees. + +**Q: How long does the entire cross-chain process take?** +A: From proposal being put on-chain to receiving tokens on NeoX typically takes 10 days (7-day voting, 3-day time-lock, plus a small bridge transfer time). This does not include the time for discussions before the proposal is put on chain and, of course, assuming the proposal is endorsed.