diff --git a/docs/how-to-guides/embed-a-node.md b/docs/how-to-guides/embed-a-node.md index 6ebe77c..7e7da57 100644 --- a/docs/how-to-guides/embed-a-node.md +++ b/docs/how-to-guides/embed-a-node.md @@ -4,7 +4,7 @@ source_repo: ant-node source_ref: main source_commit: 2a6e9f2a2066d80c072a7cc2cb644e35def9add3 - verified_date: 2026-04-03 + verified_date: 2026-04-07 verification_mode: current-merged-truth --> @@ -20,9 +20,11 @@ Use the `ant-node` API when your Rust application needs to own a node runtime di ### 1. Add ant-node +Use the published `ant-node` crate from crates.io: + ```toml [dependencies] -ant-node = "0.10.0-rc.1" +ant-node = "0.9.0" tokio = { version = "1", features = ["full"] } ``` diff --git a/docs/how-to-guides/use-external-signers.md b/docs/how-to-guides/use-external-signers.md index a0ed48c..33183a7 100644 --- a/docs/how-to-guides/use-external-signers.md +++ b/docs/how-to-guides/use-external-signers.md @@ -3,8 +3,8 @@ -Use the two-phase upload flow when your application needs a wallet outside `antd` to sign the payment transaction. +Use the two-phase upload flow when your application needs a wallet outside `antd` to sign and submit upload payments. This is the right approach when: @@ -64,11 +64,14 @@ curl -X POST http://localhost:8082/v1/data/prepare \ -d "{\"data\":\"$DATA_B64\"}" ``` -Expected response shape: +The prepare endpoints return a `payment_type` discriminator. Use that value to decide which on-chain call to make and which finalize payload to send back. + +Wave-batch prepare response: ```json { "upload_id": "", + "payment_type": "wave_batch", "payments": [ { "quote_hash": "0x...", @@ -83,17 +86,48 @@ Expected response shape: } ``` +Merkle prepare response: + +```json +{ + "upload_id": "", + "payment_type": "merkle", + "depth": 6, + "pool_commitments": [ + { + "pool_hash": "0x...", + "candidates": [ + { + "rewards_address": "0x...", + "amount": "" + } + ] + } + ], + "merkle_payment_timestamp": 1744041600, + "merkle_payments_address": "0x...", + "total_amount": "0", + "payment_token_address": "0x...", + "rpc_url": "https://your-rpc-endpoint" +} +``` + For file uploads, the equivalent is `POST /v1/upload/prepare` with a local `path` field instead of `data`. ### 3. Submit the payment externally -Use your signer stack to submit the EVM payment transactions described by the prepare response. +Use your signer stack to submit the EVM payment transaction described by the prepare response. -`antd` does not sign or broadcast those transactions in this flow. Your signer must return the resulting transaction hashes keyed by the quoted payment entries. +`antd` does not sign or broadcast those transactions in this flow. + +- For `wave_batch`, call `payForQuotes()` with the returned `payments` and keep the resulting transaction hashes keyed by `quote_hash`. +- For `merkle`, call `payForMerkleTree()` with `depth`, `pool_commitments`, and `merkle_payment_timestamp`, then keep the `winner_pool_hash` from the `MerklePaymentMade` event. ### 4. Finalize the upload -After your external signer has submitted the transactions, call `POST /v1/upload/finalize`: +After the external payment is on-chain, call `POST /v1/upload/finalize` with the matching fields for the prepared upload. + +Wave-batch finalize request: ```bash curl -X POST http://localhost:8082/v1/upload/finalize \ @@ -101,6 +135,14 @@ curl -X POST http://localhost:8082/v1/upload/finalize \ -d '{"upload_id":"","tx_hashes":{"0xquote":"0xtx"},"store_data_map":true}' ``` +Merkle finalize request: + +```bash +curl -X POST http://localhost:8082/v1/upload/finalize \ + -H "Content-Type: application/json" \ + -d '{"upload_id":"","winner_pool_hash":"0x...","store_data_map":true}' +``` + Expected response shape: ```json @@ -113,21 +155,21 @@ Expected response shape: The `address` field is only present when `store_data_map` is `true`. -### 5. Know the current SDK limitation +### 5. Use SDK helpers when available -The Python, Node.js / TypeScript, and Rust daemon SDKs include helper methods for prepare/finalize, but their finalize wrappers do not expose the full raw REST response shape. If you need `store_data_map` or the returned `data_map`, use the REST API directly. +The daemon SDKs follow the same prepare/finalize split. Merkle-capable bindings expose `payment_type` on prepare results and a `finalize_merkle_upload` helper for the Merkle path. If you are building in Rust with ant-core instead of the daemon, the library exposes native external-payment helpers such as `data_prepare_upload`, `file_prepare_upload`, `prepare_merkle_batch_external`, and `finalize_merkle_batch`. ## Verify it worked -Finalize succeeds when the daemon accepts the `upload_id` and the external transaction hashes, then returns upload metadata. If you requested `store_data_map: true`, you can retrieve the stored content again through the returned address. +Finalize succeeds when the daemon accepts the `upload_id` plus either the `tx_hashes` map or the `winner_pool_hash`, then returns upload metadata. If you requested `store_data_map: true`, you can retrieve the stored content again through the returned address. ## Common errors **404 Not Found**: The `upload_id` is missing, expired, or already finalized. -**400 Bad Request**: Check the `tx_hashes` map and the hex formatting of uploaded identifiers. +**400 Bad Request**: Check whether the prepared upload expects `tx_hashes` or `winner_pool_hash`, and validate the hex formatting of those values. **503 Service Unavailable**: You accidentally started the daemon in direct-wallet mode or without the required network configuration. diff --git a/docs/sdk-reference/mcp-server.md b/docs/sdk-reference/mcp-server.md index fb863f8..dc44cca 100644 --- a/docs/sdk-reference/mcp-server.md +++ b/docs/sdk-reference/mcp-server.md @@ -3,8 +3,8 @@ @@ -147,7 +147,7 @@ Fetches a raw chunk and returns base64-encoded data. **Tool:** `prepare_upload(path)` -Prepares a file upload for external signing and returns payment details. +Prepares a file upload for external signing and returns payment details plus a `payment_type` discriminator. ### Prepare a Data Upload @@ -155,11 +155,22 @@ Prepares a file upload for external signing and returns payment details. Prepares a data upload for external signing. The input is base64-encoded. -### Finalize an Upload +Both prepare tools return either: + +- `payment_type: "wave_batch"` with quote-level `payments` +- `payment_type: "merkle"` with `depth`, `pool_commitments`, `merkle_payment_timestamp`, and `merkle_payments_address` + +### Finalize a Wave-Batch Upload **Tool:** `finalize_upload(upload_id, tx_hashes)` -Finalizes an externally-signed upload. +Finalizes an externally-signed upload when the prepare step returned `payment_type: "wave_batch"`. + +### Finalize a Merkle Upload + +**Tool:** `finalize_merkle_upload(upload_id, winner_pool_hash)` + +Finalizes an externally-signed upload when the prepare step returned `payment_type: "merkle"`. ## Payment modes diff --git a/docs/sdk-reference/rest-api.md b/docs/sdk-reference/rest-api.md index 7e9e38f..da11442 100644 --- a/docs/sdk-reference/rest-api.md +++ b/docs/sdk-reference/rest-api.md @@ -3,8 +3,8 @@ @@ -486,9 +486,12 @@ Prepares an in-memory data upload for external signing. **Response:** +The response varies by `payment_type`. + ```json { "upload_id": "", + "payment_type": "wave_batch", "payments": [ { "quote_hash": "0x...", @@ -503,6 +506,32 @@ Prepares an in-memory data upload for external signing. } ``` +Merkle variant: + +```json +{ + "upload_id": "", + "payment_type": "merkle", + "depth": 6, + "pool_commitments": [ + { + "pool_hash": "0x...", + "candidates": [ + { + "rewards_address": "0x...", + "amount": "" + } + ] + } + ], + "merkle_payment_timestamp": 1744041600, + "merkle_payments_address": "0x...", + "total_amount": "0", + "payment_token_address": "0x...", + "rpc_url": "http://127.0.0.1:8545" +} +``` + **Example:** ```bash @@ -525,7 +554,7 @@ Prepares a file upload for external signing. |------|------|----------|-------------| | `path` | string | Yes | Local file path | -**Response:** Same shape as `POST /v1/data/prepare` +**Response:** Same `payment_type`-based shape as `POST /v1/data/prepare` **Example:** @@ -539,16 +568,19 @@ curl -X POST http://localhost:8082/v1/upload/prepare \ **Endpoint:** `POST /v1/upload/finalize` -Finalizes a prepared upload after the external signer has submitted payment transactions. +Finalizes a prepared upload after the external signer has submitted the matching payment transaction. **Parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `upload_id` | string | Yes | Value returned by a prepare endpoint | -| `tx_hashes` | object | Yes | Map of `quote_hash` to `tx_hash` | +| `tx_hashes` | object | No | Wave-batch only: map of `quote_hash` to `tx_hash` | +| `winner_pool_hash` | string | No | Merkle only: winner pool hash emitted by `MerklePaymentMade` | | `store_data_map` | boolean | No | If `true`, also stores the DataMap on-network | +Provide `tx_hashes` when the prepare response returned `payment_type: "wave_batch"`. Provide `winner_pool_hash` when it returned `payment_type: "merkle"`. + **Response:** ```json @@ -561,7 +593,7 @@ Finalizes a prepared upload after the external signer has submitted payment tran The `address` field is only present when `store_data_map` is `true`. -**Example:** +**Examples:** ```bash curl -X POST http://localhost:8082/v1/upload/finalize \ @@ -569,6 +601,12 @@ curl -X POST http://localhost:8082/v1/upload/finalize \ -d '{"upload_id":"","tx_hashes":{"0xquote":"0xtx"},"store_data_map":true}' ``` +```bash +curl -X POST http://localhost:8082/v1/upload/finalize \ + -H "Content-Type: application/json" \ + -d '{"upload_id":"","winner_pool_hash":"0x...","store_data_map":true}' +``` + ## Error codes | Code | Meaning | Resolution |