diff --git a/CHIPs/chip-0039.md b/CHIPs/chip-0039.md new file mode 100644 index 00000000..09291069 --- /dev/null +++ b/CHIPs/chip-0039.md @@ -0,0 +1,238 @@ +| CHIP Number | 0039 | +| :----------- | :-------------------------------------------------------------------- | +| Title | Fee Service Standard | +| Description | A standard for fee services that attach fees when XCH isn't available | +| Author | [Freddie Coleman](https://github.com/freddiecoleman) | +| Editor | [Dan Perry](https://github.com/danieljperry) | +| Comments-URI | [CHIPs repo, PR #138](https://github.com/Chia-Network/chips/pull/138) | +| Status | Final | +| Category | Standards Track | +| Sub-Category | Standard | +| Created | 2024-12-17 | + +## Abstract + +This proposal describes a standard for fee services that attach fees when the spender doesn't have access to XCH. This service allows any spend bundle to have fees attached through a standardized protocol. + +## Motivation + +There are scenarios where a valid transaction cannot be submitted or will take a long time to be included in a block because there is no XCH available to pay for fees. Common scenarios include: + +- Coins controlled by wallets that don't have access to XCH +- Multi-signature wallets that want to separate fee management from asset management +- Wallets that hold CATs and NFTs but no XCH +- Vaults that want to perform recovery or rekey operations without holding XCH + +Currently, these systems either need to: + +1. Hold XCH specifically for fees +2. Rely on manual fee attachment +3. Use custom, non-standardized fee services + +A standardized fee service interface would allow any application to request fee attachment from any compatible service, improving interoperability and reducing complexity. + +## Backwards Compatibility + +This standard introduces new service definitions but does not modify existing blockchain behavior. It is fully backwards compatible with existing spend bundles and transaction mechanisms. + +## Rationale + +The design focuses on the core functionality needed to attach fees to transactions: + +- Simple request/response protocol +- Minimal required fields +- Clear separation between fee attachment and transaction submission + +## Specification + +### Core Concepts + +A fee service must provide the capability to attach fees to a spend bundle. This involves: + +1. Receiving a spend bundle that requires fees +2. Creating additional coin spends to provide the necessary fees +3. Returning a new spend bundle that includes both the original spends and the fee spends + +### Protocol + +The fee attachment protocol consists of two main operations: + +1. Fee Attachment Request +2. Fee Attachment Response + +#### Fee Attachment Request + +A request to attach fees must include: + +- Spend Bundle +- Network identifier (e.g. mainnet, testnet11) +- Submit flag - whether to let the service submit the spend bundle or just return it + +#### Fee Attachment Response + +The response must include: + +- Modified spend bundle with fees attached +- Amount of fees added +- Error information if the request failed + +### Replace By Fee + +The fee attachment request accepts an `rbf` flag which supports adding higher fees to an existing transaction: + +```http +POST /api/fees HTTP/1.1 +Content-Type: application/json + +{ + "network": "mainnet", + "rbf": true, + "spendBundle": {...} +} +``` + +When `rbf: true`, the service will: + +- Add fees to enable replacement of the spend bundle in the mempool +- Ensure fee-per-cost exceeds the original transaction +- Add minimum 10000000 mojos more than original fees +- Preserve any existing time-locks + +##### CLVM Conditions + +Fee coin spends provided by the service may include conditions to ensure the fees cannot be separated from the spend or to assist with the running of the fees service. + +Examples: + +- `ASSERT_CONCURRENT_SPEND` to attach fee coins to coin spends in the original spend bundle +- `ASSERT_BEFORE_SECONDS_ABSOLUTE` to expire coin spends after an amount of time. This enables the fee service to reserve coins for a user for a limited amount of time. +- `RECEIVE_MESSAGE` to make fee spends depend on a message in the original spend bundle. + +### Error Conditions + +Services must handle and clearly indicate the following error conditions: + +1. Invalid spend bundle format +2. Unsupported network +3. Fee calculation failures + +### Implementation Requirements + +Fee services should: + +1. Never modify the intention or effect of the original spend bundle +2. Only add coin spends necessary for fee payment +3. Provide clear documentation of: + - Supported networks + - Any rate limits or restrictions + - Error conditions and responses + +### Security Requirements + +Fee services should: + +1. Validate all input spend bundles +2. Use secure transport (e.g. TLS) +3. Implement appropriate rate limiting + +## Examples + +### Basic Fee Attachment Flow + +1. Client has a valid spend bundle without fees +2. Client sends spend bundle to fee service +3. Service calculates required fees +4. Service creates new coin spends for fees +5. Service combines original spend bundle with fee spends +6. Service returns complete spend bundle to client +7. Client can verify and submit the transaction + +### HTTP Request/Response Examples + +#### Request + +```http +POST /api/fees HTTP/1.1 +Content-Type: application/json + +{ + "network": "mainnet", + "spendBundle": { + "aggregated_signature": "0x..." + "coin_spends": [ + { + "coin": { + "parent_coin_info": "0x...", + "puzzle_hash": "0x...", + "amount": 1000 + }, + "puzzle_reveal": "0x...", + "solution": "0x..." + } + ], + }, + "submit": false +} +``` + +#### Success Response + +```http +HTTP/1.1 201 OK +Content-Type: application/json + +{ + "spendBundle": { + "aggregated_signature": "0x...", + "coin_spends": [ + # Original spend + { + "coin": { + "parent_coin_info": "0x...", + "puzzle_hash": "0x...", + "amount": 1000 + }, + "puzzle_reveal": "0x...", + "solution": "0x..." + }, + # Added fee spend + { + "coin": { + "parent_coin_info": "0x...", + "puzzle_hash": "0x...", + "amount": 100000 + }, + "puzzle_reveal": "0x...", + "solution": "0x..." + } + ], + }, + "fees": 100000, + "submitted": false +} +``` + +## Test Cases + +1. Basic fee attachment to a simple spend bundle +2. Fee attachment to a multiple-coin-spend transaction +3. Handling of invalid spend bundles +4. Verification that original transaction intent is preserved +5. Rate limit handling +6. Network selection validation + +## Security Considerations + +Fee services introduce a trust relationship - the service must be trusted to: + +1. Not front-run transactions +2. Not leak transaction details +3. Provide reliable fee attachment +4. Maintain availability +5. Not modify transaction intent + +Implementations should clearly document their trust model and security properties. + +## Copyright + +Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).