Skip to content

Update SDK signer docs and node embed guidance #7

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
JimCollinson wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Update SDK signer docs and node embed guidance #7

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 4 additions & 2 deletions docs/how-to-guides/embed-a-node.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
-->

Expand All @@ -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"] }
```

Expand Down
64 changes: 53 additions & 11 deletions docs/how-to-guides/use-external-signers.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,8 @@
<!-- verification:
source_repo: ant-sdk
source_ref: main
source_commit: 6c4df9b745f3adcb022ac82b6bbc485727297e3e
verified_date: 2026-04-02
source_commit: 0ceb761cf0511f5c4fd2bd0367dc6e1a34a1a2e6
verified_date: 2026-04-07
verification_mode: current-merged-truth
-->
<!-- verification:
Expand All @@ -22,7 +22,7 @@
verification_mode: current-merged-truth
-->

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:

Expand Down Expand Up @@ -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": "<hex_id>",
"payment_type": "wave_batch",
"payments": [
{
"quote_hash": "0x...",
Expand All @@ -83,24 +86,63 @@ Expected response shape:
}
```

Merkle prepare response:

```json
{
"upload_id": "<hex_id>",
"payment_type": "merkle",
"depth": 6,
"pool_commitments": [
{
"pool_hash": "0x...",
"candidates": [
{
"rewards_address": "0x...",
"amount": "<atto_token_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 \
-H "Content-Type: application/json" \
-d '{"upload_id":"<hex_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":"<hex_id>","winner_pool_hash":"0x...","store_data_map":true}'
```

Expected response shape:

```json
Expand All @@ -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.

Expand Down
21 changes: 16 additions & 5 deletions docs/sdk-reference/mcp-server.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,8 @@
<!-- verification:
source_repo: ant-sdk
source_ref: main
source_commit: 6c4df9b745f3adcb022ac82b6bbc485727297e3e
verified_date: 2026-04-02
source_commit: 0ceb761cf0511f5c4fd2bd0367dc6e1a34a1a2e6
verified_date: 2026-04-07
verification_mode: current-merged-truth
-->

Expand Down Expand Up @@ -147,19 +147,30 @@ 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

**Tool:** `prepare_data_upload(data)`

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

Expand Down
50 changes: 44 additions & 6 deletions docs/sdk-reference/rest-api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,8 @@
<!-- verification:
source_repo: ant-sdk
source_ref: main
source_commit: 6c4df9b745f3adcb022ac82b6bbc485727297e3e
verified_date: 2026-04-02
source_commit: 0ceb761cf0511f5c4fd2bd0367dc6e1a34a1a2e6
verified_date: 2026-04-07
verification_mode: current-merged-truth
-->

Expand Down Expand Up @@ -486,9 +486,12 @@ Prepares an in-memory data upload for external signing.

**Response:**

The response varies by `payment_type`.

```json
{
"upload_id": "<hex_id>",
"payment_type": "wave_batch",
"payments": [
{
"quote_hash": "0x...",
Expand All @@ -503,6 +506,32 @@ Prepares an in-memory data upload for external signing.
}
```

Merkle variant:

```json
{
"upload_id": "<hex_id>",
"payment_type": "merkle",
"depth": 6,
"pool_commitments": [
{
"pool_hash": "0x...",
"candidates": [
{
"rewards_address": "0x...",
"amount": "<atto_token_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
Expand All @@ -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:**

Expand All @@ -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
Expand All @@ -561,14 +593,20 @@ 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 \
-H "Content-Type: application/json" \
-d '{"upload_id":"<hex_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":"<hex_id>","winner_pool_hash":"0x...","store_data_map":true}'
```

## Error codes

| Code | Meaning | Resolution |
Expand Down