Skip to content

docs: gRPC new services, CLI diagnostic flags, external-signer transport parity #54

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

Merged
JimCollinson merged 3 commits into from
Jun 10, 2026
Merged

docs: gRPC new services, CLI diagnostic flags, external-signer transport parity #54

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
bc13a85
docs: document new gRPC services, CLI flags, and gRPC transport parity
claude May 29, 2026
e8e1781
Merge branch 'main' into claude/prose-2026-05-29-grpc-cli-external-si…
JimCollinson Jun 4, 2026
c0529f9
docs: fix gRPC external-signer wording
JimCollinson Jun 10, 2026
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
16 changes: 14 additions & 2 deletions docs/cli/command-reference.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-client
source_ref: main
source_commit: e67472424f94acd4b9188a342271210d4ab9f94d
verified_date: 2026-05-26
source_commit: eeba52b997415164421999287d54fce6beae3bd3
verified_date: 2026-05-29
verification_mode: current-merged-truth
-->

Expand Down Expand Up @@ -171,13 +171,21 @@ Retrieves a single chunk by address.
|------|------|----------|-------------|
| `ADDRESS` | string | Yes | Hex-encoded chunk address (64 hex characters) |
| `-o, --output <PATH>` | path | No | Write the chunk to a file instead of stdout |
| `--all-peers` | boolean | No | Diagnostic mode: try every selected closest peer and print ranked per-peer results. Chunk bytes are only written when `-o`/`--output` is also supplied. |
| `--peer-count <N>` | integer | No | Diagnostic mode only. Number of closest peers to try with `--all-peers`. Requires `--all-peers`. |

**Example:**

```bash
ant chunk get <chunk_address> -o chunk.bin
```

Diagnostic example (try all closest peers and rank results):

```bash
ant chunk get <chunk_address> --all-peers --peer-count 5
```

## Wallet commands

### `ant wallet address`
Expand Down Expand Up @@ -291,12 +299,16 @@ Adds one or more nodes to the registry.
| `--version <X.Y.Z>` | string | No | Download a specific node version |
| `--url <URL>` | string | No | Download a node archive from a URL |
| `--bootstrap <ADDRS>` | string list | No | Bootstrap peers for the node binary itself |
| `--upgrade-channel <CHANNEL>` | string | No | Release channel the node tracks for automatic upgrades: `stable` or `beta` |
| `--env <K=V>` | string list | No | Node environment variables |

**Example:**

```bash
ant node add --rewards-address 0xYourWallet --count 1

# Pin the node to the stable upgrade channel:
ant node add --rewards-address 0xYourWallet --count 1 --upgrade-channel stable
```

### `ant node start`
Expand Down
34 changes: 16 additions & 18 deletions docs/sdk/how-to-guides/use-external-signers-for-upload-payments.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,15 +3,15 @@
<!-- verification:
source_repo: ant-sdk
source_ref: main
source_commit: 7853b76d99ef9e308140b763f23d043559b204c4
verified_date: 2026-05-28
source_commit: cac111f35bdc30cf05a82468d5fa84d594626d87
verified_date: 2026-05-29
verification_mode: current-merged-truth
-->
<!-- verification:
source_repo: ant-client
source_ref: main
source_commit: e67472424f94acd4b9188a342271210d4ab9f94d
verified_date: 2026-05-26
source_commit: eeba52b997415164421999287d54fce6beae3bd3
verified_date: 2026-05-29
verification_mode: current-merged-truth
-->
<!-- verification:
Expand Down Expand Up @@ -67,7 +67,7 @@ curl -X POST http://localhost:8082/v1/chunks/prepare \
-d "{\"data\":\"$CHUNK_B64\"}"
```

When the chunk is already stored on the network, the response returns `already_stored: true` with the existing address and no `upload_id`. There is nothing more to do: no payment to make and no finalize call to issue. Otherwise the response returns the wave-batch payment shape:
When the chunk is already stored on the Autonomi Network, the response returns `already_stored: true` with the existing address and no `upload_id`. There is nothing more to do: no payment to make and no finalize call to issue. Otherwise the response returns the wave-batch payment shape:

```json
{
Expand Down Expand Up @@ -161,7 +161,7 @@ Merkle prepare response:

Each `pool_commitments` entry contains exactly 16 candidate payments. The sample above shows one candidate for brevity.

For file uploads, the equivalent is `POST /v1/upload/prepare` with a local `path` field instead of `data`. To make the upload publicly retrievable by address, add `"visibility":"public"` to the prepare request — the daemon bundles the serialized DataMap chunk into the same payment batch, and the finalize response includes a `data_map_address` field with its network address.
For file uploads, the equivalent is `POST /v1/upload/prepare` with a local `path` field instead of `data`. To make the upload publicly retrievable by address, add `"visibility":"public"` to the prepare request. `antd` bundles the serialized DataMap chunk into the same payment batch, and the finalize response includes a `data_map_address` field with its Autonomi Network address.

### 3. Submit the payment externally

Expand All @@ -170,7 +170,7 @@ Use your signer stack to submit the EVM payment transaction described by the pre
`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.
- For `merkle`, call `payForMerkleTree2()` with `depth`, `pool_commitments`, and `merkle_payment_timestamp`, then keep the `winner_pool_hash` from the `MerklePaymentMade` event.

Both calls use the `payment_vault_address` returned by the prepare step.

Expand All @@ -183,49 +183,47 @@ 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}'
-d '{"upload_id":"<hex_id>","tx_hashes":{"0xquote":"0xtx"}}'
```

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}'
-d '{"upload_id":"<hex_id>","winner_pool_hash":"0x..."}'
```

Expected response shape:

```json
{
"data_map": "<hex_encoded_datamap>",
"address": "<64_hex_address>",
"data_map_address": "<64_hex_address>",
"address": "<64_hex_address_if_store_data_map_true>",
"data_map_address": "<64_hex_address_if_visibility_public>",
"chunks_stored": <chunk_count>
}
```

`address` is only present when `store_data_map` is `true`; that path uses the daemon's own wallet to store the DataMap. `data_map_address` is only present when the upload was prepared with `visibility:"public"` — it is the network address of the DataMap chunk whose payment was included in the same external-signer batch.
`address` is only present when `store_data_map` is `true`; that path stores the DataMap through `antd`'s configured wallet. Use it only when `antd` has a wallet key. `data_map_address` is only present when the upload was prepared with `visibility:"public"`; it is the Autonomi Network address of the DataMap chunk whose payment was included in the same external-signer batch.

### 5. Use SDK helpers when available

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.
The language bindings for `antd` follow the same prepare/finalize split across both REST and gRPC transports. Merkle-capable bindings expose `payment_type` on prepare results and a `finalize_merkle_upload` helper for the Merkle path. For file and in-memory data uploads, gRPC `UploadService` exposes the full finalize surface, including `data_map`, `data_map_address`, and `store_data_map`. For single-chunk uploads, gRPC `ChunkService` exposes `PrepareChunk` and `FinalizeChunk`; `FinalizeChunk` returns the stored chunk address.

Use the REST API when you need the full finalize response surface, such as the raw `data_map` value or explicit `store_data_map` control on wave-batch finalize requests.

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`, `data_prepare_upload_with_visibility`, `file_prepare_upload`, `prepare_merkle_batch_external`, and `finalize_merkle_batch`. Use `data_prepare_upload_with_visibility(content, Visibility::Public)` to bundle the DataMap chunk into the payment batch for a public in-memory upload. Progress-aware variants such as `file_prepare_upload_with_progress`, `finalize_upload_with_progress`, and `finalize_upload_merkle_with_progress` are also available when you need UI feedback during long-running uploads.
If you are building in Rust with ant-core instead of `antd`, the library exposes native external-payment helpers such as `data_prepare_upload`, `data_prepare_upload_with_visibility`, `file_prepare_upload`, `prepare_merkle_batch_external`, and `finalize_merkle_batch`. Use `data_prepare_upload_with_visibility(content, Visibility::Public)` to bundle the DataMap chunk into the payment batch for a public in-memory upload. Progress-aware variants such as `file_prepare_upload_with_progress`, `finalize_upload_with_progress`, and `finalize_upload_merkle_with_progress` are also available when you need UI feedback during long-running uploads.

## Verify it worked

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.
Finalize succeeds when `antd` accepts the `upload_id` plus either the `tx_hashes` map or the `winner_pool_hash`, then returns upload metadata. Use the returned `data_map` for private retrieval. If you prepared with `visibility:"public"`, use the returned `data_map_address` for public retrieval.

## Common errors

**404 Not Found**: The `upload_id` is missing, expired, or already finalized.

**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.
**503 Service Unavailable**: You started `antd` in direct-wallet mode or without the required network configuration.

## Next steps

Expand Down
175 changes: 172 additions & 3 deletions docs/sdk/reference/grpc-services.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: 7853b76d99ef9e308140b763f23d043559b204c4
verified_date: 2026-05-28
source_commit: cac111f35bdc30cf05a82468d5fa84d594626d87
verified_date: 2026-05-29
verification_mode: current-merged-truth
-->

Expand Down Expand Up @@ -85,6 +85,172 @@ Fetches a chunk by address.

Stores a raw chunk.

### PrepareChunk

**Signature:** `PrepareChunk(PrepareChunkRequest) -> PrepareChunkResponse`

Phase 1 of the external-signer single-chunk upload flow. Mirrors `POST /v1/chunks/prepare`. Single-chunk publishes always use the wave-batch payment shape.

When the chunk is already on-network, `already_stored` is `true`, the payment fields are empty, and no finalize call is needed.

**Request fields:**

| Name | Type | Description |
|------|------|-------------|
| `data` | bytes | Raw chunk bytes (at most one ant-protocol chunk) |

**Response fields:**

| Name | Type | Description |
|------|------|-------------|
| `address` | string | Content-addressed BLAKE3 hash of the chunk bytes (hex with `0x` prefix) |
| `already_stored` | bool | `true` if the chunk was already on-network; all payment fields are empty when `true` |
| `upload_id` | string | Opaque token to pass to `FinalizeChunk`; empty when `already_stored` is `true` |
| `payment_type` | string | Always `"wave_batch"` for single-chunk publishes; empty when `already_stored` is `true` |
| `payments` | repeated PaymentEntry | Per-quote payment entries for `payForQuotes()`; see [Common messages](#common-messages) |
| `total_amount` | string | Total amount to pay in atto tokens |
| `payment_vault_address` | string | Payment vault contract address (hex with `0x` prefix) |
| `payment_token_address` | string | Payment token contract address (hex with `0x` prefix) |
| `rpc_url` | string | EVM RPC URL for submitting transactions |

### FinalizeChunk

**Signature:** `FinalizeChunk(FinalizeChunkRequest) -> FinalizeChunkResponse`

Phase 2 of the external-signer single-chunk upload flow. Mirrors `POST /v1/chunks/finalize`. Call this after the external EVM payment has landed on-chain.

**Request fields:**

| Name | Type | Description |
|------|------|-------------|
| `upload_id` | string | The `upload_id` returned from `PrepareChunk` |
| `tx_hashes` | map\<string, string\> | Map of `quote_hash` (hex) to `tx_hash` (hex) from the on-chain payment |

**Response fields:**

| Name | Type | Description |
|------|------|-------------|
| `address` | string | Network address of the stored chunk (hex with `0x` prefix) |

## Upload Service

The Upload Service handles external-signer file and in-memory data uploads. It mirrors the REST `/v1/upload/prepare`, `/v1/data/prepare`, and `/v1/upload/finalize` surface.

The flow is two-phase: submit a prepare request, receive payment details and an `upload_id`, submit the EVM payment externally, then call `FinalizeUpload` with the transaction hashes or winner pool hash.

- Uploads with fewer than 64 chunks use `payment_type = "wave_batch"` and `payForQuotes()`.
- Uploads with 64 or more chunks use `payment_type = "merkle"` and `payForMerkleTree2()`.

### PrepareFileUpload

**Signature:** `PrepareFileUpload(PrepareFileUploadRequest) -> PrepareUploadResponse`

Phase 1 for a local file. Returns payment details and an `upload_id`.

**Request fields:**

| Name | Type | Description |
|------|------|-------------|
| `path` | string | Local filesystem path on the host running `antd` |
| `visibility` | string | `"private"` (default) or `"public"`. `"public"` bundles the DataMap chunk into the payment batch; `data_map_address` is populated in the finalize response |

### PrepareDataUpload

**Signature:** `PrepareDataUpload(PrepareDataUploadRequest) -> PrepareUploadResponse`

Phase 1 for in-memory bytes. Same two-phase flow as `PrepareFileUpload` but accepts raw bytes rather than a filesystem path.

**Request fields:**

| Name | Type | Description |
|------|------|-------------|
| `data` | bytes | Raw bytes to upload |
| `visibility` | string | `"private"` (default) or `"public"` |

### PrepareUploadResponse (shared)

Both prepare RPCs return `PrepareUploadResponse`:

| Name | Type | Description |
|------|------|-------------|
| `upload_id` | string | Opaque token to pass to `FinalizeUpload` |
| `payment_type` | string | `"wave_batch"` or `"merkle"` |
| `payments` | repeated PaymentEntry | Wave-batch: per-quote entries for `payForQuotes()`; see [Common messages](#common-messages) |
| `depth` | uint32 | Merkle: tree depth (1–8) |
| `pool_commitments` | repeated PoolCommitmentEntry | Merkle: pool commitments for `payForMerkleTree2()`; each entry has exactly 16 candidate nodes; see [Common messages](#common-messages) |
| `merkle_payment_timestamp` | uint64 | Merkle: unix timestamp for the payment |
| `total_amount` | string | Total amount in atto tokens (`"0"` for Merkle) |
| `payment_vault_address` | string | Payment vault contract address (hex with `0x` prefix) |
| `payment_token_address` | string | Payment token contract address (hex with `0x` prefix) |
| `rpc_url` | string | EVM RPC URL for submitting transactions |

### FinalizeUpload

**Signature:** `FinalizeUpload(FinalizeUploadRequest) -> FinalizeUploadResponse`

Phase 2 for both file and data uploads. Call after the external EVM payment lands.

**Request fields:**

| Name | Type | Description |
|------|------|-------------|
| `upload_id` | string | The `upload_id` returned from a prepare RPC |
| `tx_hashes` | map\<string, string\> | Wave-batch: map of `quote_hash` (hex) to `tx_hash` (hex). Must be empty for Merkle |
| `winner_pool_hash` | string | Merkle: winner pool hash (hex with `0x` prefix) from the `MerklePaymentMade` event. Must be empty for wave-batch |
| `store_data_map` | bool | If `true`, stores the DataMap through `antd`'s configured wallet and returns its address in `address` |

**Response fields:**

| Name | Type | Description |
|------|------|-------------|
| `data_map` | string | Hex-encoded serialized DataMap. Always returned |
| `address` | string | Autonomi Network address of the stored DataMap; only set when `store_data_map` is `true` |
| `data_map_address` | string | Autonomi Network address of the bundled DataMap chunk; only set when the upload was prepared with `visibility = "public"` |
| `chunks_stored` | uint64 | Number of chunks stored on the Autonomi Network |

## Wallet Service

The Wallet Service mirrors the REST `/v1/wallet/*` surface. All three RPCs require `antd` to have been started with `AUTONOMI_WALLET_KEY`. When the wallet is absent, `antd` returns `failed_precondition`.

External-signer flows do not use this service — they use `UploadService` and `ChunkService.PrepareChunk`/`FinalizeChunk` instead.

### GetAddress

**Signature:** `GetAddress(GetWalletAddressRequest) -> GetWalletAddressResponse`

Returns the wallet's on-chain address.

**Response fields:**

| Name | Type | Description |
|------|------|-------------|
| `address` | string | Wallet address (hex with `0x` prefix) |

### GetBalance

**Signature:** `GetBalance(GetWalletBalanceRequest) -> GetWalletBalanceResponse`

Returns the wallet's token and gas balances.

**Response fields:**

| Name | Type | Description |
|------|------|-------------|
| `balance` | string | Token balance in atto tokens as a decimal string |
| `gas_balance` | string | Gas (native EVM token) balance in atto tokens as a decimal string |

### Approve

**Signature:** `Approve(WalletApproveRequest) -> WalletApproveResponse`

Approves the wallet to spend tokens on the payment vault contract. Safe to call repeatedly; idempotent once approval is in place.

**Response fields:**

| Name | Type | Description |
|------|------|-------------|
| `approved` | bool | `true` if the approve transaction succeeded |

## File Service

### Put
Expand Down Expand Up @@ -138,7 +304,7 @@ This RPC is exposed, but the stream stays open without emitting events.

## Common messages

The proto files define these shared shapes:
The proto files define these reusable shapes:

| Message | Fields |
|------|--------|
Expand All @@ -153,6 +319,9 @@ The proto files define these shared shapes:
| `GetFileRequest` | `data_map`, `dest_path` |
| `GetDataRequest` | `data_map` |
| `FileCostRequest` | `path`, `is_public`, `payment_mode` |
| `PaymentEntry` | `quote_hash`, `rewards_address`, `amount` |
| `PoolCommitmentEntry` | `pool_hash`, `candidates` |
| `CandidateNodeEntry` | `rewards_address`, `amount` |

## Related pages

Expand Down
6 changes: 3 additions & 3 deletions docs/sdk/reference/language-bindings/python.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: 7853b76d99ef9e308140b763f23d043559b204c4
verified_date: 2026-05-28
source_commit: cac111f35bdc30cf05a82468d5fa84d594626d87
verified_date: 2026-05-29
verification_mode: current-merged-truth
-->

Expand Down Expand Up @@ -91,7 +91,7 @@ except AntdError as error:
print(error)
```

REST and gRPC share the same high-level API. Wallet operations and external-signer tools are REST-only; `payment_mode` is available on both transports.
REST and gRPC share the same high-level API, including wallet operations and external-signer prepare/finalize methods. `payment_mode` is available on both transports.

## Full API reference

Expand Down
Loading