From b070708ec6694a5a9326bdd2598189781f62c45b Mon Sep 17 00:00:00 2001 From: Freddie Coleman Date: Tue, 17 Dec 2024 14:51:41 +0400 Subject: [PATCH 1/8] initial fee service spec --- CHIPs/chip-0039.md | 188 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 188 insertions(+) create mode 100644 CHIPs/chip-0039.md diff --git a/CHIPs/chip-0039.md b/CHIPs/chip-0039.md new file mode 100644 index 00000000..ecf3b74e --- /dev/null +++ b/CHIPs/chip-0039.md @@ -0,0 +1,188 @@ +| 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 | Draft | +| 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 + +### 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 + +### Example Spend Bundle Modification + +``` +# Original spend bundle: +{ + "coin_spends": [ + { + "coin": { + "parent_coin_info": "0x...", + "puzzle_hash": "0x...", + "amount": 1000 + }, + "puzzle_reveal": "0x...", + "solution": "0x..." + } + ], + "aggregated_signature": "0x..." +} + +# After fee service: +{ + "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": 100 + }, + "puzzle_reveal": "0x...", + "solution": "0x..." + } + ], + "aggregated_signature": "0x..." # Updated to include fee spend +} +``` + +## 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/). From 49a702e7dc3b5392ab89d9760cbdbcc48c09115a Mon Sep 17 00:00:00 2001 From: Freddie Coleman Date: Tue, 17 Dec 2024 14:58:21 +0400 Subject: [PATCH 2/8] document entire HTTP request/response --- CHIPs/chip-0039.md | 94 +++++++++++++++++++++++++++------------------- 1 file changed, 56 insertions(+), 38 deletions(-) diff --git a/CHIPs/chip-0039.md b/CHIPs/chip-0039.md index ecf3b74e..51cecc37 100644 --- a/CHIPs/chip-0039.md +++ b/CHIPs/chip-0039.md @@ -115,50 +115,68 @@ Fee services should: 6. Service returns complete spend bundle to client 7. Client can verify and submit the transaction -### Example Spend Bundle Modification +### HTTP Request/Response Examples + +#### Request + +```http +POST /api/fees HTTP/1.1 +Content-Type: application/json -``` -# Original spend bundle: { - "coin_spends": [ - { - "coin": { - "parent_coin_info": "0x...", - "puzzle_hash": "0x...", - "amount": 1000 - }, - "puzzle_reveal": "0x...", - "solution": "0x..." - } - ], - "aggregated_signature": "0x..." + "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 -# After fee service: { - "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": 100 + "spendBundle": { + "aggregated_signature": "0x...", + "coin_spends": [ + # Original spend + { + "coin": { + "parent_coin_info": "0x...", + "puzzle_hash": "0x...", + "amount": 1000 + }, + "puzzle_reveal": "0x...", + "solution": "0x..." }, - "puzzle_reveal": "0x...", - "solution": "0x..." - } - ], - "aggregated_signature": "0x..." # Updated to include fee spend + # Added fee spend + { + "coin": { + "parent_coin_info": "0x...", + "puzzle_hash": "0x...", + "amount": 100 + }, + "puzzle_reveal": "0x...", + "solution": "0x..." + } + ], + }, + "fees": 100000, + "submitted": false } ``` From 0c88c9fddbb011826166e9f6be87b3ebfd8122f1 Mon Sep 17 00:00:00 2001 From: danieljperry Date: Thu, 19 Dec 2024 11:30:31 -0600 Subject: [PATCH 3/8] Update example coin amount --- CHIPs/chip-0039.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHIPs/chip-0039.md b/CHIPs/chip-0039.md index 51cecc37..060cd27e 100644 --- a/CHIPs/chip-0039.md +++ b/CHIPs/chip-0039.md @@ -168,7 +168,7 @@ Content-Type: application/json "coin": { "parent_coin_info": "0x...", "puzzle_hash": "0x...", - "amount": 100 + "amount": 100000 }, "puzzle_reveal": "0x...", "solution": "0x..." From bc34cc68b99958d1c41d6c252dea01956f1fe019 Mon Sep 17 00:00:00 2001 From: Freddie Coleman Date: Wed, 15 Jan 2025 13:07:52 +0400 Subject: [PATCH 4/8] CLVM conditions --- CHIPs/chip-0039.md | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/CHIPs/chip-0039.md b/CHIPs/chip-0039.md index 51cecc37..0dc25c8d 100644 --- a/CHIPs/chip-0039.md +++ b/CHIPs/chip-0039.md @@ -64,7 +64,7 @@ The fee attachment protocol consists of two main operations: A request to attach fees must include: -- Spend Bundle: +- Spend Bundle - Network identifier (e.g. mainnet, testnet11) - Submit flag - whether to let the service submit the spend bundle or just return it @@ -76,6 +76,16 @@ The response must include: - Amount of fees added - Error information if the request failed +##### 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: From f6a5c8ef591cd2b747154107829cbabc6d2f71c8 Mon Sep 17 00:00:00 2001 From: Freddie Coleman Date: Thu, 23 Jan 2025 10:30:33 +0400 Subject: [PATCH 5/8] Replace By Fee support --- CHIPs/chip-0039.md | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/CHIPs/chip-0039.md b/CHIPs/chip-0039.md index 32578b13..4b2b5dcb 100644 --- a/CHIPs/chip-0039.md +++ b/CHIPs/chip-0039.md @@ -76,6 +76,28 @@ The response must include: - 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. From 53b1ac8ff09c85bcfab2cc63361a3bdaceaa41a1 Mon Sep 17 00:00:00 2001 From: danieljperry Date: Sat, 13 Sep 2025 07:34:44 +0800 Subject: [PATCH 6/8] Move CHIP-39 to Review --- CHIPs/chip-0039.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHIPs/chip-0039.md b/CHIPs/chip-0039.md index 4b2b5dcb..3324f4c5 100644 --- a/CHIPs/chip-0039.md +++ b/CHIPs/chip-0039.md @@ -5,7 +5,7 @@ | 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 | Draft | +| Status | Review | | Category | Standards Track | | Sub-Category | Standard | | Created | 2024-12-17 | From 983af4a3bc9be131a1b8e06e9781fd376d0954cb Mon Sep 17 00:00:00 2001 From: danieljperry Date: Fri, 7 Nov 2025 13:27:20 +0800 Subject: [PATCH 7/8] Move CHIP-39 to Last Call --- CHIPs/chip-0039.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHIPs/chip-0039.md b/CHIPs/chip-0039.md index 3324f4c5..5caa32f8 100644 --- a/CHIPs/chip-0039.md +++ b/CHIPs/chip-0039.md @@ -5,7 +5,7 @@ | 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 | Review | +| Status | Last Call | | Category | Standards Track | | Sub-Category | Standard | | Created | 2024-12-17 | From 8f8295dfe778fd53b0c0d852a9c6a347e066e807 Mon Sep 17 00:00:00 2001 From: danieljperry Date: Fri, 21 Nov 2025 09:09:26 +0800 Subject: [PATCH 8/8] Move CHIP-39 to Final status --- CHIPs/chip-0039.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHIPs/chip-0039.md b/CHIPs/chip-0039.md index 5caa32f8..09291069 100644 --- a/CHIPs/chip-0039.md +++ b/CHIPs/chip-0039.md @@ -5,7 +5,7 @@ | 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 | Last Call | +| Status | Final | | Category | Standards Track | | Sub-Category | Standard | | Created | 2024-12-17 |