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

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

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
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
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
12 changes: 5 additions & 7 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 @@ -209,9 +209,7 @@ Expected response shape:

### 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.

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.
The daemon SDKs 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. The gRPC `UploadService` and `ChunkService` expose the full prepare/finalize surface including `data_map`, `data_map_address`, and `store_data_map` — at parity with REST for the external-signer flow.

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.

Expand Down
170 changes: 168 additions & 2 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()` |
| `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 is the external-signer flow for files and in-memory data. 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 resulting transaction artefacts.

- Files with fewer than 64 chunks use `payment_type = "wave_batch"` and `payForQuotes()`.
- Files 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 daemon host |
| `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()` |
| `depth` | uint32 | Merkle: tree depth (1–8) |
| `pool_commitments` | repeated PoolCommitmentEntry | Merkle: pool commitments for `payForMerkleTree2()`; each entry has exactly 16 candidate nodes |
| `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 via the daemon's internal wallet and returns its address in `address` |

**Response fields:**

| Name | Type | Description |
|------|------|-------------|
| `data_map` | string | Hex-encoded serialized DataMap. Always returned |
| `address` | string | Network address of the stored DataMap; only set when `store_data_map` is `true` |
| `data_map_address` | string | 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 network |

## Wallet Service

The Wallet Service mirrors the REST `/v1/wallet/*` surface. All three RPCs require the daemon to have been started with `AUTONOMI_WALLET_KEY`. When the wallet is absent, the daemon 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
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