From 7de0c8193f0f698961d547b81c4bcdbb1c081094 Mon Sep 17 00:00:00 2001 From: MoD Date: Fri, 29 Nov 2024 18:42:57 +0200 Subject: [PATCH] State Channels Abstraction Protocol --- ERCS/erc-7824.md | 146 ++++++++++++++++++++++++++++++++++++++++++ ERCS/erc-7825.md | 160 +++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 306 insertions(+) create mode 100644 ERCS/erc-7824.md create mode 100644 ERCS/erc-7825.md diff --git a/ERCS/erc-7824.md b/ERCS/erc-7824.md new file mode 100644 index 0000000000..f3630ca3b4 --- /dev/null +++ b/ERCS/erc-7824.md @@ -0,0 +1,146 @@ +--- +eip: 7824 +title: ERC for Exit Format in State Channels +description: A standard for defining outcomes and asset allocations in state channels using the Exit Format. +author: State Channels (@statechannels), Layer-3 Foundation (@layer-3), Louis Bellet (@mod) +discussions-to: https://ethereum-magicians.org/c/ercs/57 (Coming soon) +status: Draft +type: Standards Track +category: ERC +created: 2024-11-22 +--- + +## Abstract + +This ERC defines a standard **Exit Format** for specifying outcomes and asset allocations in state channels. The Exit Format supports diverse token types (native tokens, ERC20, and others) and accommodates both simple and advanced allocation mechanisms. The standard ensures interoperability and clarity in the distribution of locked assets upon channel finalization, particularly in protocols like Nitro. + +## Motivation + +State channels rely on clear and interoperable methods for redistributing locked assets when a channel closes. Current implementations lack a standardized format for defining these outcomes, leading to inefficiencies and integration challenges. This ERC introduces a unified **Exit Format** that can be adopted across state channel implementations, improving compatibility and simplifying on-chain interactions. + +## Specification + +### Key Structs and Enums + +#### `Outcome` +Defines the result of asset redistribution upon channel closure. + +```solidity +struct Outcome { + SingleAssetExit[] singleAssetExits; // Array of asset-specific exits +} +``` + +#### `SingleAssetExit` +Represents allocations for a single asset. + +```solidity +struct SingleAssetExit { + address asset; // Asset type (e.g., native token or ERC20) + bytes assetMetadata; // Metadata for non-standard assets + Allocation[] allocations; // Distribution rules for this asset +} +``` + +#### `Allocation` +Details how an asset is distributed. + +```solidity +struct Allocation { + bytes32 destination; // Address or channel ID receiving the funds + uint256 amount; // Amount to allocate + uint8 allocationType; // Type of allocation (e.g., simple or guarantee) + bytes metadata; // Additional data for advanced allocations +} +``` + +### Allocation Types + +1. **Simple Allocation (`allocationType = 0`)** + Basic asset transfer to external addresses or channels. + +2. **Guarantee Allocation (`allocationType = 1`)** + Conditional transfer based on secondary channels or other criteria. + +```solidity +enum AllocationType { + Simple, + Guarantee +} +``` + +### Advanced Metadata Example: Guarantees + +For `Guarantee` allocations, the `metadata` encodes the following structure: + +```solidity +struct Guarantee { + bytes32 left; // Left participant in the guarantee + bytes32 right; // Right participant in the guarantee +} +``` + +### Example Usage + +#### Example 1: Simple ETH Allocation +"5 ETH to Alice, 5 ETH to Bob." + +```solidity +SingleAssetExit ethExit = SingleAssetExit({ + asset: address(0), // Native token (ETH) + assetMetadata: "", + allocations: [ + Allocation({ + destination: 0x...AliceAddress, + amount: 5 ether, + allocationType: AllocationType.Simple, + metadata: "" + }), + Allocation({ + destination: 0x...BobAddress, + amount: 5 ether, + allocationType: AllocationType.Simple, + metadata: "" + }) + ] +}); +``` + +#### Example 2: Guaranteed Allocation +Guarantee that funds can only be moved to a secondary channel. + +```solidity +Allocation({ + destination: 0x...ChannelID, + amount: 10 ether, + allocationType: AllocationType.Guarantee, + metadata: abi.encode(Guarantee({left: 0x...Alice, right: 0x...Bob})) +}); +``` + +## Rationale + +The Exit Format standardizes asset redistribution logic across state channel implementations, reducing ambiguity and improving interoperability. By supporting both simple and advanced allocations, it addresses a wide range of use cases, from basic payments to complex virtual channel setups. + +## Backwards Compatibility + +This ERC introduces new structs and enums for use in state channel contracts. It is designed to be forward-compatible with existing protocols like Nitro. Implementations not using this standard will need to adapt their on-chain logic to parse Exit Format structures. + +## Test Cases + +1. **Simple Allocation Test** + - Verify that simple allocations transfer the correct amounts to specified destinations. +2. **Guarantee Allocation Test** + - Test reclaiming funds from a guarantee allocation with valid and invalid metadata. +3. **Multi-Asset Exit Test** + - Validate proper handling of multiple asset types in a single `Outcome`. + +## Security Considerations + +- **Metadata Integrity:** Ensure that metadata for advanced allocations (e.g., guarantees) is properly validated. +- **Replay Protection:** Verify that channel IDs and participant signatures prevent unauthorized updates or disputes. +- **Overflow Handling:** Implement safeguards against overflow in allocation calculations. + +## Copyright + +Copyright and related rights waived via [CC0](../LICENSE). diff --git a/ERCS/erc-7825.md b/ERCS/erc-7825.md new file mode 100644 index 0000000000..478f67286e --- /dev/null +++ b/ERCS/erc-7825.md @@ -0,0 +1,160 @@ +--- +eip: 7825 +title: State Channel Standard data types and interfaces +description: A standard for implementing interoperable state channels on Ethereum using the State Channel Protocol, integrated with ERC-4337 for enhanced account abstraction. +author: State Channels (@statechannels), Layer-3 Foundation (@layer-3), Louis Bellet (@mod) +discussions-to: https://ethereum-magicians.org/c/ercs/57 (Coming soon) +status: Draft +type: Standards Track +category: ERC +created: 2024-11-22 +requires: 4337 7824 +--- + +## Abstract + +This ERC standardizes data types for state channels (Also known as Nitro Protocol), enabling efficient off-chain state execution and on-chain dispute resolution. Integrated with ERC-4337 account abstraction, it leverages the capabilities of programmable wallets and plugins to enhance functionality, including custom state channel validators using NitroApps. The proposal defines essential structs and interfaces for Nitro-based state channels, supporting interoperability across Ethereum-based systems. + +## Motivation + +State channels offer a mechanism for off-chain execution, improving scalability and reducing transaction costs. However, existing implementations are not standardized and lack native support for account abstraction. By integrating State Channel Protocol with ERC-4337, this ERC enables advanced wallet functionality, custom plugins for state validation, and seamless interoperability across Ethereum-compatible systems. + +## Specification + +### Structs + +The State Channel Protocol defines the following key structs: + +#### `FixedPart` +Defines immutable parameters of the state channel: + +```solidity +struct FixedPart { + address[] participants; // List of participant addresses + uint48 channelNonce; // Unique channel identifier + address appDefinition; // Address of the application-specific contract + uint48 challengeDuration; // Challenge duration in seconds +} +``` + +#### `VariablePart` +Defines the dynamic parameters of a channel's state: + +```solidity +struct VariablePart { + ExitFormat.SingleAssetExit[] outcome; // Asset distribution upon channel finalization + bytes appData; // Application-specific data + uint48 turnNum; // State version number + bool isFinal; // Flag for instant finalization +} +``` + +#### `SignedVariablePart` +Represents a signed state update: + +```solidity +struct SignedVariablePart { + VariablePart variablePart; + Signature[] sigs; // Participant signatures +} +``` + +#### `Outcome` +Describes asset distribution after channel finalization: + +```solidity +struct Outcome { + SingleAssetExit[] singleAssetExits; +} + +struct SingleAssetExit { + address asset; // Asset type (native or ERC20) + bytes assetMetadata; // Metadata for exotic assets + Allocation[] allocations; // Distribution of funds +} + +struct Allocation { + bytes32 destination; // Destination (channel ID or external address) + uint256 amount; // Allocation amount + uint8 allocationType; // Type (0 = simple, 1 = guarantee) + bytes metadata; // Additional data for guarantees +} +``` + +### Interfaces + +#### `IForceMoveApp` +Defines the application-specific execution rules: + +```solidity +interface IForceMoveApp { + function stateIsSupported( + FixedPart calldata fixedPart, + RecoveredVariablePart[] calldata proof, + RecoveredVariablePart calldata candidate + ) external view returns (bool, string memory); +} +``` + +#### `IAdjudicator` +Handles on-chain dispute resolution: + +```solidity +interface IAdjudicator { + function challenge( + bytes32 channelId, + FixedPart calldata fixedPart, + SignedVariablePart[] calldata proof, + SignedVariablePart calldata candidate + ) external; + + function finalize(bytes32 channelId) external; +} +``` + +### Integration with ERC-4337 + +#### Benefits +1. **Custom Validation Plugins:** State validation logic can be implemented as NitroApps and used as account abstraction plugins, enabling diverse use cases (e.g., payment channels, virtual channels). +2. **Programmable Wallets:** Wallets using ERC-4337 can interact directly with Nitro-based state channels. +3. **Interoperability:** Unified standard for account abstraction and state channels across Ethereum. + +#### Example +```solidity +contract NitroAccount is IAccount { + function validateUserOp( + UserOperation calldata userOp, + bytes32 userOpHash, + uint256 missingAccountFunds + ) external override returns (uint256) { + // Validate state updates using NitroApp logic + } +} +``` + +## Rationale + +This ERC builds on the modularity of Nitro Protocol and the flexibility of ERC-4337, creating a unified standard for state channel implementations. By decoupling execution rules from core protocol logic, it ensures adaptability for various applications while maintaining a secure and efficient dispute resolution process. + +## Backwards Compatibility + +This ERC depends on ERC-4337 and assumes its availability for account abstraction functionality. Legacy state channel implementations without Nitro compatibility will require adaptation. + +## Test Cases + +1. **Channel Initialization:** + - Deploy a channel with two participants and verify the `FixedPart` parameters. +2. **State Update:** + - Submit a valid `SignedVariablePart` and ensure it is accepted by the `IAdjudicator`. +3. **Dispute Resolution:** + - Simulate a challenge and verify proper execution of the `finalize` function. + +## Security Considerations + +- **Signature Validation:** Ensure that all state updates are cryptographically signed by the required participants. +- **Replay Protection:** Use unique `channelNonce` values to prevent replay attacks. +- **Application Logic Safety:** Carefully audit application-specific logic to avoid vulnerabilities. + +## Copyright + +Copyright and related rights waived via [CC0](../LICENSE).