diff --git a/ERCS/erc-7824.md b/ERCS/erc-7824.md new file mode 100644 index 0000000000..d62c90b7e3 --- /dev/null +++ b/ERCS/erc-7824.md @@ -0,0 +1,146 @@ +--- +eip: 7824 +title: ERC for Exit Format in State Channels +description: Outcomes and asset allocations definition 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 +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, ERC-20, 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..0dbce7417b --- /dev/null +++ b/ERCS/erc-7825.md @@ -0,0 +1,160 @@ +--- +eip: 7825 +title: State Channel Standard data types and interfaces +description: Interoperable state channels on Ethereum using 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 +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](./eip-4337.md) 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).