From fe6ea55a374051ad6fa22f26786d4dd26eb5599c Mon Sep 17 00:00:00 2001 From: Jim Collinson Date: Thu, 30 Apr 2026 16:53:51 +0100 Subject: [PATCH 1/4] Reverify docs and skill against current merged truth --- docs/architecture/system-overview.md | 24 +++++----- docs/cli/command-reference.md | 48 ++++++++++++++----- docs/cli/use-the-cli.md | 7 ++- docs/core-concepts/data-types.md | 10 ++-- .../keys-addresses-and-datamaps.md | 10 ++-- docs/core-concepts/overview.md | 14 +++--- docs/core-concepts/payment-model.md | 20 ++++---- .../post-quantum-cryptography.md | 10 ++-- docs/core-concepts/self-encryption.md | 2 +- docs/guides/build-read-only-features.md | 12 ++--- docs/guides/deploy-to-mainnet.md | 8 ++-- ...timate-costs-and-handle-upload-payments.md | 10 ++-- docs/guides/overview.md | 10 ++-- docs/guides/prepare-a-wallet-for-uploads.md | 21 ++++++-- docs/guides/set-up-a-local-network.md | 10 ++-- docs/guides/test-your-application.md | 14 +++--- docs/index.md | 12 ++--- docs/mcp/mcp-server-reference.md | 31 +++++++++--- docs/mcp/use-mcp-with-ai-tools.md | 13 +++-- docs/mcp/use-the-autonomi-mcp-server.md | 25 ++++++---- docs/reference/glossary.md | 26 +++++----- docs/reference/source-repositories.md | 30 ++++++------ docs/rust/README.md | 8 ++-- docs/rust/build-directly-in-rust.md | 6 +-- docs/rust/embed-a-node-in-your-application.md | 6 +-- docs/rust/library-reference.md | 45 +++++++++++++---- docs/sdk/how-to-guides/README.md | 4 +- .../how-to-guides/store-and-retrieve-data.md | 4 +- ...se-external-signers-for-upload-payments.md | 18 ++++--- .../use-the-daemon-as-a-local-service.md | 6 +-- docs/sdk/install.md | 4 +- docs/sdk/reference/README.md | 4 +- .../sdk/reference/daemon-command-reference.md | 6 +-- docs/sdk/reference/grpc-services.md | 8 ++-- docs/sdk/reference/language-bindings/cpp.md | 4 +- .../sdk/reference/language-bindings/csharp.md | 4 +- docs/sdk/reference/language-bindings/dart.md | 4 +- docs/sdk/reference/language-bindings/go.md | 6 ++- docs/sdk/reference/language-bindings/java.md | 4 +- .../reference/language-bindings/javascript.md | 6 ++- .../sdk/reference/language-bindings/kotlin.md | 4 +- .../reference/language-bindings/overview.md | 11 ++--- docs/sdk/reference/language-bindings/php.md | 4 +- .../sdk/reference/language-bindings/python.md | 6 ++- docs/sdk/reference/language-bindings/ruby.md | 4 +- docs/sdk/reference/language-bindings/rust.md | 6 ++- docs/sdk/reference/language-bindings/swift.md | 4 +- .../reference/language-bindings/typescript.md | 4 +- docs/sdk/reference/language-bindings/zig.md | 4 +- docs/sdk/reference/overview.md | 12 ++--- docs/sdk/reference/rest-api.md | 4 +- docs/sdk/retrieve-data-from-the-network.md | 4 +- docs/sdk/start-the-local-daemon.md | 20 ++++---- docs/sdk/store-data-on-the-network.md | 4 +- skills/start/CHANGELOG.md | 12 +++-- skills/start/SKILL.md | 12 +++-- skills/start/version.json | 4 +- 57 files changed, 379 insertions(+), 254 deletions(-) diff --git a/docs/architecture/system-overview.md b/docs/architecture/system-overview.md index dbd6693..5a5dbf3 100644 --- a/docs/architecture/system-overview.md +++ b/docs/architecture/system-overview.md @@ -3,57 +3,57 @@ diff --git a/docs/cli/command-reference.md b/docs/cli/command-reference.md index 7b4c20b..0a814f0 100644 --- a/docs/cli/command-reference.md +++ b/docs/cli/command-reference.md @@ -3,12 +3,12 @@ -Reference for the `ant` CLI command tree and its current flags. The command tree below mirrors the current `ant --help` output, and the option tables are verified against the current command help while the sections stay grouped by command family for easier scanning. +Reference for the `ant` CLI command tree and its current flags. The command tree below follows the current direct-network CLI surface, and the option tables stay grouped by command family for easier scanning. A few hidden or advanced flags are included where they matter for troubleshooting. ## Command tree @@ -30,7 +30,8 @@ ant │ └── balance ├── file │ ├── upload -│ └── download +│ ├── download +│ └── cost ├── chunk │ ├── put │ └── get @@ -52,10 +53,10 @@ The root command accepts the global flags used across data and node operations. | `--devnet-manifest ` | path | No | Path to a local devnet manifest JSON file | | `--allow-loopback` | boolean | No | Allow loopback connections for local devnet or local testing | | `--ipv4-only` | boolean | No | Disable dual-stack and force IPv4-only mode | -| `--quote-timeout-secs ` | integer | No | Timeout for lightweight network operations such as DHT lookups | -| `--store-timeout-secs ` | integer | No | Timeout for chunk store and retrieve operations | -| `--quote-concurrency ` | integer | No | Maximum number of chunks quoted or downloaded concurrently | -| `--store-concurrency ` | integer | No | Maximum number of chunks stored concurrently during uploads. `--chunk-concurrency` is accepted as an alias. | +| `--quote-timeout-secs ` | integer | No | Hidden advanced flag for lightweight network-operation timeouts such as DHT lookups | +| `--store-timeout-secs ` | integer | No | Hidden advanced flag for chunk store and retrieve timeouts | +| `--quote-concurrency ` | integer | No | Hidden advanced flag that caps the quote channel only. It does not affect store or download concurrency. | +| `--store-concurrency ` | integer | No | Hidden advanced flag for upload chunk concurrency. `--chunk-concurrency` is accepted as an alias. | | `-v, --verbose...` | count | No | Increase log verbosity: `-v`, `-vv`, or `-vvv` | | `--evm-network ` | string | No | EVM network for payments: `arbitrum-one`, `arbitrum-sepolia`, or `local` | | `-h, --help` | boolean | No | Print help | @@ -87,8 +88,9 @@ Uploads a file with self-encryption and EVM payment. | `--public` | boolean | No | Store the DataMap on-network so anyone with the address can download the file | | `--merkle` | boolean | No | Force Merkle batch payment | | `--no-merkle` | boolean | No | Force single per-chunk payments | -| `--store-timeout ` | integer | No | Override the chunk store timeout for this upload | -| `--store-concurrency ` | integer | No | Override upload chunk concurrency for this upload | +| `--store-timeout ` | integer | No | Hidden advanced flag that overrides the chunk store timeout for this upload | +| `--store-concurrency ` | integer | No | Hidden advanced flag that overrides upload chunk concurrency for this upload | +| `--overwrite` | boolean | No | Replace an existing `.datamap` instead of writing a suffixed datamap filename | **Example:** @@ -106,7 +108,7 @@ Downloads a public file by address or a private file using a local DataMap file. |------|------|----------|-------------| | `ADDRESS` | string | Conditionally | Public DataMap address. Required unless `--datamap` is provided. | | `--datamap ` | path | No | Local `.datamap` file for private download | -| `-o, --output ` | path | Yes | Output file path | +| `-o, --output ` | path | Conditionally | Required for address-based downloads. Optional for `--datamap` downloads that can infer the original filename. | **Example:** @@ -116,6 +118,30 @@ ant file download 711c7e20006ff3e0ac6c1f3063286a0c1a3e4c409642e8c526173fa60bb707 The output path is your local filename. In this example, the command downloads a public JPEG of Lucky the dog and saves it as `lucky.jpg`. +Private datamap example: + +```bash +ant file download --datamap photo.jpg.datamap +``` + +### `ant file cost ` + +Estimates the upload cost for a file without uploading it. + +**Parameters:** + +| Name | Type | Required | Description | +|------|------|----------|-------------| +| `PATH` | path | Yes | File to estimate | +| `--merkle` | boolean | No | Force Merkle batch payment mode for the estimate | +| `--no-merkle` | boolean | No | Force single payment mode for the estimate | + +**Example:** + +```bash +ant file cost photo.jpg --merkle +``` + ## Chunk commands ### `ant chunk put [FILE]` diff --git a/docs/cli/use-the-cli.md b/docs/cli/use-the-cli.md index d367529..a1fa6b8 100644 --- a/docs/cli/use-the-cli.md +++ b/docs/cli/use-the-cli.md @@ -3,8 +3,8 @@ @@ -59,6 +59,9 @@ If you build `ant` from source instead, provide your own bootstrap config or pas ```bash ant --help + +# or, if you built from source and have not installed it on PATH: +./target/release/ant --help ``` For the `ant` CLI, root flags such as `--bootstrap`, `--devnet-manifest`, `--allow-loopback`, and `--evm-network` come before the subcommand. diff --git a/docs/core-concepts/data-types.md b/docs/core-concepts/data-types.md index 650432f..5fc51cd 100644 --- a/docs/core-concepts/data-types.md +++ b/docs/core-concepts/data-types.md @@ -3,22 +3,22 @@ diff --git a/docs/core-concepts/keys-addresses-and-datamaps.md b/docs/core-concepts/keys-addresses-and-datamaps.md index bf47c3d..0f8a44c 100644 --- a/docs/core-concepts/keys-addresses-and-datamaps.md +++ b/docs/core-concepts/keys-addresses-and-datamaps.md @@ -3,22 +3,22 @@ diff --git a/docs/core-concepts/overview.md b/docs/core-concepts/overview.md index cbf96d8..8891db1 100644 --- a/docs/core-concepts/overview.md +++ b/docs/core-concepts/overview.md @@ -3,29 +3,29 @@ diff --git a/docs/core-concepts/payment-model.md b/docs/core-concepts/payment-model.md index 626061f..868f1d9 100644 --- a/docs/core-concepts/payment-model.md +++ b/docs/core-concepts/payment-model.md @@ -3,36 +3,36 @@ @@ -76,7 +76,7 @@ The `antd` surface exposes cost estimation explicitly: - `POST /v1/data/cost` - `POST /v1/files/cost` -Those endpoints return the estimated upload cost as a string amount in atto tokens. +Those endpoints return a structured estimate with cost, file size, chunk count, estimated gas, and the payment mode that would be used. ### Payment modes @@ -96,7 +96,7 @@ Node-side storage pricing currently follows `BASELINE + K × (n / D)^2`, where ` ### What happens on retrieval -Downloads do not require a separate payment step. Payments are tied to storing data, chunks, files, directories, or node-management operations that require wallet context. +Downloads do not require a separate payment step. Payments are tied to storage writes such as storing data, chunks, files, or directories. ## Practical example diff --git a/docs/core-concepts/post-quantum-cryptography.md b/docs/core-concepts/post-quantum-cryptography.md index dc96cc9..37f222c 100644 --- a/docs/core-concepts/post-quantum-cryptography.md +++ b/docs/core-concepts/post-quantum-cryptography.md @@ -3,22 +3,22 @@ diff --git a/docs/core-concepts/self-encryption.md b/docs/core-concepts/self-encryption.md index bb09982..4c80d75 100644 --- a/docs/core-concepts/self-encryption.md +++ b/docs/core-concepts/self-encryption.md @@ -4,7 +4,7 @@ source_repo: self_encryption source_ref: master source_commit: 5f9d1646231da7ca2ce60e84d010acfb6d9c29d0 - verified_date: 2026-04-02 + verified_date: 2026-04-30 verification_mode: current-merged-truth --> diff --git a/docs/guides/build-read-only-features.md b/docs/guides/build-read-only-features.md index 8556074..88e1d3f 100644 --- a/docs/guides/build-read-only-features.md +++ b/docs/guides/build-read-only-features.md @@ -3,15 +3,15 @@ @@ -85,8 +85,8 @@ The private retrieval response is JSON with the content returned as base64 in th With the CLI, public and private file retrieval use `ant file download` with either a public address or a local `.datamap` file: ```bash -ant file download -o downloaded.bin --bootstrap 1.2.3.4:12000 -ant file download --datamap my_data.bin.datamap -o downloaded.bin --bootstrap 1.2.3.4:12000 +ant --bootstrap 1.2.3.4:12000 file download -o downloaded.bin +ant --bootstrap 1.2.3.4:12000 file download --datamap my_data.bin.datamap -o downloaded.bin ``` For native Rust, use the retrieval APIs in `ant-core` after connecting to the network client. diff --git a/docs/guides/deploy-to-mainnet.md b/docs/guides/deploy-to-mainnet.md index 1e095dc..5917af7 100644 --- a/docs/guides/deploy-to-mainnet.md +++ b/docs/guides/deploy-to-mainnet.md @@ -3,15 +3,15 @@ diff --git a/docs/guides/estimate-costs-and-handle-upload-payments.md b/docs/guides/estimate-costs-and-handle-upload-payments.md index dea0670..8913ff6 100644 --- a/docs/guides/estimate-costs-and-handle-upload-payments.md +++ b/docs/guides/estimate-costs-and-handle-upload-payments.md @@ -3,15 +3,15 @@ @@ -154,7 +154,7 @@ async fn main() -> Result<(), Box> { ### 3. Estimate storage cost -The daemon exposes cost-estimation endpoints and returns the estimated upload cost as a string amount in atto tokens. +The daemon exposes cost-estimation endpoints and returns a structured estimate that includes cost, file size, chunk count, estimated gas, and the payment mode that would be used. Use this step before uploads when you want to show a user the likely storage cost or validate that the wallet has enough balance. diff --git a/docs/guides/overview.md b/docs/guides/overview.md index 4978d3f..4d1b534 100644 --- a/docs/guides/overview.md +++ b/docs/guides/overview.md @@ -3,22 +3,22 @@ diff --git a/docs/guides/prepare-a-wallet-for-uploads.md b/docs/guides/prepare-a-wallet-for-uploads.md index de8f708..9cbe8e6 100644 --- a/docs/guides/prepare-a-wallet-for-uploads.md +++ b/docs/guides/prepare-a-wallet-for-uploads.md @@ -3,15 +3,15 @@ @@ -59,13 +59,20 @@ If you do not want the daemon to hold the wallet key, use the external-signer fl ### 2. Configure a wallet for antd -The daemon consumes a hex private key through `AUTONOMI_WALLET_KEY`. +For direct-wallet uploads on Arbitrum Sepolia or Arbitrum One, start `antd` with both the wallet key and the EVM payment settings. + +From the `ant-sdk/antd` build directory, run: ```bash export AUTONOMI_WALLET_KEY="" +export EVM_RPC_URL="https://your-rpc-endpoint" +export EVM_PAYMENT_TOKEN_ADDRESS="0x..." +export EVM_PAYMENT_VAULT_ADDRESS="0x..." ./target/release/antd ``` +If `antd` is already on your `PATH`, use `antd` instead. + ### 3. Configure a wallet for ant The direct-network CLI uses `SECRET_KEY`. @@ -96,6 +103,8 @@ SECRET_KEY=0x... ant --evm-network arbitrum-one wallet balance If you do not want `antd` to hold a wallet key, run it without `AUTONOMI_WALLET_KEY` and use the external-signer flow instead. +From the `ant-sdk/antd` build directory, run: + ```bash EVM_RPC_URL=https://your-rpc-endpoint \ EVM_PAYMENT_TOKEN_ADDRESS=0x... \ @@ -103,6 +112,8 @@ EVM_PAYMENT_VAULT_ADDRESS=0x... \ ./target/release/antd ``` +If `antd` is already on your `PATH`, use `antd` instead. + Use `EVM_PAYMENT_VAULT_ADDRESS` for both wave-batch and Merkle external-signer uploads in this configuration. That keeps signing outside the daemon and pushes transaction submission into your wallet or signer integration. diff --git a/docs/guides/set-up-a-local-network.md b/docs/guides/set-up-a-local-network.md index af27aa9..9e73152 100644 --- a/docs/guides/set-up-a-local-network.md +++ b/docs/guides/set-up-a-local-network.md @@ -3,15 +3,15 @@ @@ -47,6 +47,8 @@ cd ant-sdk pip install -e ant-dev/ ``` +The `ant` command installed by `ant-dev` is separate from the direct-network `ant` CLI in `ant-client`. Use a virtualenv, `pipx`, or a separate `PATH` setup if you need both workflows on the same machine. + This installs the `ant` command provided by the current `ant-dev` package. If `antd` has not been built on this machine before, make sure `protoc` is installed first. On macOS, one working setup is `brew install protobuf`. diff --git a/docs/guides/test-your-application.md b/docs/guides/test-your-application.md index 478eece..668accd 100644 --- a/docs/guides/test-your-application.md +++ b/docs/guides/test-your-application.md @@ -3,22 +3,22 @@ @@ -31,6 +31,8 @@ This guide focuses on the shared testing progression that applies across SDK, CL - A test framework for your language - `ant-dev` installed from an `ant-sdk` checkout, or a direct-network local devnet if you are testing `ant-core` +If you also use the direct-network `ant` CLI from `ant-client`, isolate `ant-dev` in a virtualenv, `pipx`, or a separate `PATH` so the two `ant` commands do not shadow each other. + ## Steps ### 1. Keep unit tests local to your own code diff --git a/docs/index.md b/docs/index.md index c1b924a..b689db9 100644 --- a/docs/index.md +++ b/docs/index.md @@ -3,29 +3,29 @@ diff --git a/docs/mcp/mcp-server-reference.md b/docs/mcp/mcp-server-reference.md index d7bbcfd..8825359 100644 --- a/docs/mcp/mcp-server-reference.md +++ b/docs/mcp/mcp-server-reference.md @@ -3,8 +3,8 @@ @@ -33,6 +33,8 @@ pip install "antd[rest]" pip install -e antd-mcp/ ``` +Run the editable install from an `ant-sdk` checkout root. + The package metadata currently declares: - Python `>=3.10` @@ -55,7 +57,9 @@ At startup, the server resolves the daemon base URL in this order: 2. `daemon.port` discovery 3. `http://127.0.0.1:8082` -The discovery helper reads the same platform-specific `daemon.port` file written by `antd` and uses the REST port found there. +The discovery helper still checks a `daemon.port` file before falling back to the default URL. + +`antd` writes `ant/sdk/daemon.port`, while `antd-mcp` still reads `ant/daemon.port`. Treat `ANTD_BASE_URL` as the reliable configuration path unless you have already confirmed port-file discovery works in your environment. ## Claude Desktop configuration @@ -63,12 +67,17 @@ The discovery helper reads the same platform-specific `daemon.port` file written { "mcpServers": { "antd-autonomi": { - "command": "antd-mcp" + "command": "antd-mcp", + "env": { + "ANTD_BASE_URL": "http://127.0.0.1:8082" + } } } } ``` +Adjust `ANTD_BASE_URL` if your daemon runs on a different host or port. + ## Data tools ### Store Data @@ -101,6 +110,8 @@ Downloads a public file or directory to a local path. Estimates storage cost for text or a local file path. +Provide exactly one of `text` or `file_path`. + ### Check Health **Tool:** `check_health()` @@ -195,7 +206,7 @@ Examples: } ``` -Example `upload_file` or `upload_dir` response: +Example `upload_file(..., is_directory=true)` response: ```json { @@ -208,7 +219,15 @@ Example `upload_file` or `upload_dir` response: } ``` -`put_data` responses omit `storage_cost_atto` and `gas_cost_wei`. +Example `store_data` response: + +```json +{ + "address": "abc123...", + "cost": "1000000", + "network": "local" +} +``` Structured `AntdError` responses include: diff --git a/docs/mcp/use-mcp-with-ai-tools.md b/docs/mcp/use-mcp-with-ai-tools.md index fc30ba9..f9a6a9b 100644 --- a/docs/mcp/use-mcp-with-ai-tools.md +++ b/docs/mcp/use-mcp-with-ai-tools.md @@ -3,8 +3,8 @@ @@ -26,6 +26,8 @@ The MCP server talks to `antd`, so start there first: ./target/release/antd ``` +Run that command from the `ant-sdk/antd` build directory. If `antd` is already on your `PATH`, use `antd` instead. + If you have not built `antd` yet, follow [Build with the SDKs](../sdk/install.md) and [Start the Local Daemon](../sdk/start-the-local-daemon.md) first. ### 2. Install the MCP server @@ -45,12 +47,17 @@ For Claude Desktop, add `antd-mcp` to `claude_desktop_config.json`: { "mcpServers": { "antd-autonomi": { - "command": "antd-mcp" + "command": "antd-mcp", + "env": { + "ANTD_BASE_URL": "http://127.0.0.1:8082" + } } } } ``` +Adjust `ANTD_BASE_URL` if your daemon runs on a different host or port. + ### 4. Continue with the full MCP setup Use the full setup guide next. It covers daemon discovery, SSE mode, and overrides such as `ANTD_BASE_URL`. diff --git a/docs/mcp/use-the-autonomi-mcp-server.md b/docs/mcp/use-the-autonomi-mcp-server.md index 166f26b..3a6e428 100644 --- a/docs/mcp/use-the-autonomi-mcp-server.md +++ b/docs/mcp/use-the-autonomi-mcp-server.md @@ -3,8 +3,8 @@ @@ -30,11 +30,13 @@ pip install -e antd-mcp/ The `antd-mcp` package installs a command named `antd-mcp`. -### 2. Let it discover the daemon automatically +### 2. Prefer an explicit daemon URL -By default, the server looks for the `daemon.port` file written by `antd` on startup. If discovery succeeds, it connects to the REST endpoint listed there. +The server still attempts `daemon.port` discovery before falling back to the default REST URL. -If no environment variable or port file is available, it falls back to: +`antd` writes `ant/sdk/daemon.port`, while `antd-mcp` still reads `ant/daemon.port`. Treat `ANTD_BASE_URL` as the reliable setup path unless you have already confirmed port-file discovery works in your environment. + +If no environment variable or readable port file is available, it falls back to: ```text http://127.0.0.1:8082 @@ -54,9 +56,9 @@ For web-based clients that want SSE transport: antd-mcp --sse ``` -### 4. Override the daemon URL when needed +### 4. Set the daemon URL explicitly -If the daemon is not discoverable through `daemon.port`, set `ANTD_BASE_URL` explicitly: +Set `ANTD_BASE_URL` explicitly for a reliable connection: ```bash ANTD_BASE_URL="http://your-host:8082" antd-mcp @@ -70,13 +72,16 @@ Add this to `claude_desktop_config.json`: { "mcpServers": { "antd-autonomi": { - "command": "antd-mcp" + "command": "antd-mcp", + "env": { + "ANTD_BASE_URL": "http://127.0.0.1:8082" + } } } } ``` -If you need to override discovery, add an `env` block with `ANTD_BASE_URL`. +Adjust `ANTD_BASE_URL` if your daemon runs on a different host or port. ## Verify it worked @@ -84,7 +89,7 @@ Your MCP client is configured correctly when it can see the `antd-autonomi` serv ## Common errors -**The server cannot find the daemon**: Confirm that `antd` is running and that `daemon.port` exists, or set `ANTD_BASE_URL` explicitly. +**The server cannot find the daemon**: Confirm that `antd` is running, then set `ANTD_BASE_URL` explicitly. **Import or package errors**: Make sure both `antd[rest]` and `antd-mcp` were installed into the same Python environment. diff --git a/docs/reference/glossary.md b/docs/reference/glossary.md index 4795d23..1c885ad 100644 --- a/docs/reference/glossary.md +++ b/docs/reference/glossary.md @@ -3,64 +3,64 @@ diff --git a/docs/reference/source-repositories.md b/docs/reference/source-repositories.md index 6b9726a..8ec4456 100644 --- a/docs/reference/source-repositories.md +++ b/docs/reference/source-repositories.md @@ -3,78 +3,78 @@ diff --git a/docs/rust/README.md b/docs/rust/README.md index 1a1f200..9adff2c 100644 --- a/docs/rust/README.md +++ b/docs/rust/README.md @@ -3,15 +3,15 @@ diff --git a/docs/rust/build-directly-in-rust.md b/docs/rust/build-directly-in-rust.md index 75c1443..71b7478 100644 --- a/docs/rust/build-directly-in-rust.md +++ b/docs/rust/build-directly-in-rust.md @@ -3,8 +3,8 @@ @@ -32,7 +32,7 @@ Update `Cargo.toml`: ```toml [dependencies] -ant-core = { path = "../ant-client/ant-core" } +ant-core = { path = "../ant-client/ant-core", features = ["devnet"] } bytes = "1" tokio = { version = "1", features = ["full"] } ``` diff --git a/docs/rust/embed-a-node-in-your-application.md b/docs/rust/embed-a-node-in-your-application.md index f0cad34..abb0f28 100644 --- a/docs/rust/embed-a-node-in-your-application.md +++ b/docs/rust/embed-a-node-in-your-application.md @@ -3,8 +3,8 @@ @@ -24,7 +24,7 @@ Use the published `ant-node` crate from crates.io: ```toml [dependencies] -ant-node = "0.10.1" +ant-node = "0.11.0" tokio = { version = "1", features = ["full"] } ``` diff --git a/docs/rust/library-reference.md b/docs/rust/library-reference.md index fbcaeb2..4d4a958 100644 --- a/docs/rust/library-reference.md +++ b/docs/rust/library-reference.md @@ -3,8 +3,8 @@ @@ -54,12 +54,15 @@ async fn main() -> Result<(), Box> { ## Store and retrieve data ```rust -use ant_core::data::{Client, ClientConfig}; +use ant_core::data::{Client, ClientConfig, EvmNetwork, Wallet}; use bytes::Bytes; #[tokio::main] async fn main() -> Result<(), Box> { let client = Client::connect(&["1.2.3.4:12000".parse()?], ClientConfig::default()).await?; + let wallet = Wallet::new_from_private_key(EvmNetwork::ArbitrumOne, "0xprivate_key...")?; + let client = client.with_wallet(wallet); + client.approve_token_spend().await?; let result = client.data_upload(Bytes::from("hello autonomi")).await?; let content = client.data_download(&result.data_map).await?; @@ -72,20 +75,39 @@ async fn main() -> Result<(), Box> { To make uploaded data publicly retrievable by address, store and later fetch the DataMap: ```rust -let public_address = client.data_map_store(&result.data_map).await?; -let public_data_map = client.data_map_fetch(&public_address).await?; -let downloaded = client.data_download(&public_data_map).await?; +use ant_core::data::{Client, ClientConfig, EvmNetwork, Wallet}; +use bytes::Bytes; + +#[tokio::main] +async fn main() -> Result<(), Box> { + let client = Client::connect(&["1.2.3.4:12000".parse()?], ClientConfig::default()).await?; + let wallet = Wallet::new_from_private_key(EvmNetwork::ArbitrumOne, "0xprivate_key...")?; + let client = client.with_wallet(wallet); + client.approve_token_spend().await?; + + let result = client.data_upload(Bytes::from("hello autonomi")).await?; + + let public_address = client.data_map_store(&result.data_map).await?; + let public_data_map = client.data_map_fetch(&public_address).await?; + let downloaded = client.data_download(&public_data_map).await?; + + assert_eq!(downloaded, Bytes::from("hello autonomi")); + Ok(()) +} ``` ## File operations ```rust -use ant_core::data::{Client, ClientConfig, PaymentMode}; +use ant_core::data::{Client, ClientConfig, EvmNetwork, PaymentMode, Wallet}; use std::path::Path; #[tokio::main] async fn main() -> Result<(), Box> { let client = Client::connect(&["1.2.3.4:12000".parse()?], ClientConfig::default()).await?; + let wallet = Wallet::new_from_private_key(EvmNetwork::ArbitrumOne, "0xprivate_key...")?; + let client = client.with_wallet(wallet); + client.approve_token_spend().await?; let result = client.file_upload_with_mode(Path::new("photo.jpg"), PaymentMode::Merkle).await?; let address = client.data_map_store(&result.data_map).await?; @@ -101,7 +123,7 @@ The native Rust library exposes both wave-batch and Merkle-batch external paymen For wave-batch uploads, `data_prepare_upload`, `file_prepare_upload`, and `finalize_upload` prepare the upload, collect quotes, and later store the chunks after an external signer returns transaction hashes. -For Merkle batches, `prepare_merkle_batch_external` and `finalize_merkle_batch` expose the low-level batch helpers, while `finalize_upload_merkle` completes a prepared upload from the winning pool hash. +For Merkle batches, `prepare_merkle_batch_external` and `finalize_merkle_batch` expose the low-level batch helpers, while `finalize_upload_merkle` completes a prepared upload from the winning pool hash. 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. ## Key types @@ -169,6 +191,13 @@ async fn main() { The library also exports `LocalDevnet` for local development flows: +Enable the `ant-core` `devnet` feature before you use this section: + +```toml +[dependencies] +ant-core = { path = "../ant-client/ant-core", features = ["devnet"] } +``` + ```rust use ant_core::data::LocalDevnet; diff --git a/docs/sdk/how-to-guides/README.md b/docs/sdk/how-to-guides/README.md index 7333815..a86bc13 100644 --- a/docs/sdk/how-to-guides/README.md +++ b/docs/sdk/how-to-guides/README.md @@ -3,8 +3,8 @@ diff --git a/docs/sdk/how-to-guides/store-and-retrieve-data.md b/docs/sdk/how-to-guides/store-and-retrieve-data.md index 870fe13..b02259f 100644 --- a/docs/sdk/how-to-guides/store-and-retrieve-data.md +++ b/docs/sdk/how-to-guides/store-and-retrieve-data.md @@ -3,8 +3,8 @@ diff --git a/docs/sdk/how-to-guides/use-external-signers-for-upload-payments.md b/docs/sdk/how-to-guides/use-external-signers-for-upload-payments.md index ffb4ae0..ab41749 100644 --- a/docs/sdk/how-to-guides/use-external-signers-for-upload-payments.md +++ b/docs/sdk/how-to-guides/use-external-signers-for-upload-payments.md @@ -3,22 +3,22 @@ @@ -42,6 +42,8 @@ This is the right approach when: The daemon does not have an `--external-signer` flag. External-signer mode is the absence of `AUTONOMI_WALLET_KEY` plus the use of the prepare/finalize endpoints. +From the `ant-sdk/antd` build directory, run: + ```bash EVM_RPC_URL=https://your-rpc-endpoint \ EVM_PAYMENT_TOKEN_ADDRESS=0x... \ @@ -49,6 +51,8 @@ EVM_PAYMENT_VAULT_ADDRESS=0x... \ ./target/release/antd ``` +If `antd` is already on your `PATH`, use `antd` instead. + Use `EVM_PAYMENT_VAULT_ADDRESS` for both wave-batch and Merkle uploads in the external-signer flow. ### 2. Prepare the upload @@ -166,7 +170,7 @@ The daemon SDKs follow the same prepare/finalize split. Merkle-capable bindings 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`, `file_prepare_upload`, `prepare_merkle_batch_external`, and `finalize_merkle_batch`. +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`. 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 diff --git a/docs/sdk/how-to-guides/use-the-daemon-as-a-local-service.md b/docs/sdk/how-to-guides/use-the-daemon-as-a-local-service.md index 309bdb9..8be0520 100644 --- a/docs/sdk/how-to-guides/use-the-daemon-as-a-local-service.md +++ b/docs/sdk/how-to-guides/use-the-daemon-as-a-local-service.md @@ -3,8 +3,8 @@ @@ -88,7 +88,7 @@ For a stable local service, keep explicit addresses as shown above. If another s antd --rest-port 0 --grpc-port 0 ``` -In that mode, SDKs can discover the chosen ports from the `daemon.port` file written on startup. +In that mode, SDKs can discover the chosen ports from the `daemon.port` file written under the SDK data directory on startup. ## Verify it worked diff --git a/docs/sdk/install.md b/docs/sdk/install.md index 1a44f90..662e8f7 100644 --- a/docs/sdk/install.md +++ b/docs/sdk/install.md @@ -3,8 +3,8 @@ diff --git a/docs/sdk/reference/README.md b/docs/sdk/reference/README.md index 5111054..2ed41d2 100644 --- a/docs/sdk/reference/README.md +++ b/docs/sdk/reference/README.md @@ -3,8 +3,8 @@ diff --git a/docs/sdk/reference/daemon-command-reference.md b/docs/sdk/reference/daemon-command-reference.md index 095df8f..b6d2c0f 100644 --- a/docs/sdk/reference/daemon-command-reference.md +++ b/docs/sdk/reference/daemon-command-reference.md @@ -3,8 +3,8 @@ @@ -85,7 +85,7 @@ antd --quote-timeout-secs 15 --store-timeout-secs 90 --quote-concurrency 32 --st - The CLI does not include an `--external-signer` flag. - External-signer mode is handled through environment configuration and the prepare/finalize upload endpoints. - Use `EVM_PAYMENT_VAULT_ADDRESS` for current paid-write and external-signer setups. -- On startup, `antd` writes a `daemon.port` file so SDKs can discover the active ports. +- On startup, `antd` writes a `daemon.port` file under the SDK data directory so SDKs can discover the active ports. ## Error codes diff --git a/docs/sdk/reference/grpc-services.md b/docs/sdk/reference/grpc-services.md index d773795..bb0b66e 100644 --- a/docs/sdk/reference/grpc-services.md +++ b/docs/sdk/reference/grpc-services.md @@ -3,8 +3,8 @@ @@ -45,7 +45,7 @@ Stores public data. **Signature:** `StreamPublic(StreamPublicDataRequest) -> stream DataChunk` -Streams public data chunks. +Current merged code exposes this RPC, but the handler is still stubbed and currently returns `UNIMPLEMENTED`. ### Get Private @@ -121,7 +121,7 @@ Estimates file upload cost. **Signature:** `Subscribe(SubscribeRequest) -> stream ClientEventProto` -Streams client events from the daemon. +Current merged code exposes this RPC, but the stream is still stubbed and currently stays open without emitting events. `ClientEventProto` currently includes: diff --git a/docs/sdk/reference/language-bindings/cpp.md b/docs/sdk/reference/language-bindings/cpp.md index 57cef84..1f67ff7 100644 --- a/docs/sdk/reference/language-bindings/cpp.md +++ b/docs/sdk/reference/language-bindings/cpp.md @@ -3,8 +3,8 @@ diff --git a/docs/sdk/reference/language-bindings/csharp.md b/docs/sdk/reference/language-bindings/csharp.md index 2941bcb..834aaf1 100644 --- a/docs/sdk/reference/language-bindings/csharp.md +++ b/docs/sdk/reference/language-bindings/csharp.md @@ -3,8 +3,8 @@ diff --git a/docs/sdk/reference/language-bindings/dart.md b/docs/sdk/reference/language-bindings/dart.md index 6e9c6d2..8d2ae26 100644 --- a/docs/sdk/reference/language-bindings/dart.md +++ b/docs/sdk/reference/language-bindings/dart.md @@ -3,8 +3,8 @@ diff --git a/docs/sdk/reference/language-bindings/go.md b/docs/sdk/reference/language-bindings/go.md index f9f4de6..1d5503e 100644 --- a/docs/sdk/reference/language-bindings/go.md +++ b/docs/sdk/reference/language-bindings/go.md @@ -3,8 +3,8 @@ @@ -48,6 +48,8 @@ The SDK also includes a `GrpcClient` for the daemon's gRPC endpoint. ## Store and retrieve data +For upload examples in this section, start `antd` in a write-enabled mode first. On the default network, that means wallet plus EVM payment configuration. On a local devnet, `ant dev start` provisions that for you. + ```go package main diff --git a/docs/sdk/reference/language-bindings/java.md b/docs/sdk/reference/language-bindings/java.md index 4190019..1df1715 100644 --- a/docs/sdk/reference/language-bindings/java.md +++ b/docs/sdk/reference/language-bindings/java.md @@ -3,8 +3,8 @@ diff --git a/docs/sdk/reference/language-bindings/javascript.md b/docs/sdk/reference/language-bindings/javascript.md index bc2bd30..6c4cc8e 100644 --- a/docs/sdk/reference/language-bindings/javascript.md +++ b/docs/sdk/reference/language-bindings/javascript.md @@ -3,8 +3,8 @@ @@ -37,6 +37,8 @@ console.log(url); ## Store and retrieve data +For upload examples in this section, start `antd` in a write-enabled mode first. On the default network, that means wallet plus EVM payment configuration. On a local devnet, `ant dev start` provisions that for you. + ```javascript import { createClient } from "antd"; diff --git a/docs/sdk/reference/language-bindings/kotlin.md b/docs/sdk/reference/language-bindings/kotlin.md index 338a1c3..118efbf 100644 --- a/docs/sdk/reference/language-bindings/kotlin.md +++ b/docs/sdk/reference/language-bindings/kotlin.md @@ -3,8 +3,8 @@ diff --git a/docs/sdk/reference/language-bindings/overview.md b/docs/sdk/reference/language-bindings/overview.md index 698ea76..aba0133 100644 --- a/docs/sdk/reference/language-bindings/overview.md +++ b/docs/sdk/reference/language-bindings/overview.md @@ -3,8 +3,8 @@ @@ -33,10 +33,9 @@ Bindings usually default to those same endpoints when you do not supply an overr At this commit: -- JavaScript and TypeScript use REST -- Python supports REST and gRPC -- Go supports REST and gRPC -- Rust supports REST and gRPC +- JavaScript and TypeScript are documented as REST-based +- Python, Go, and Rust document both REST and gRPC support +- other bindings vary by package and current docs coverage Check the individual page before assuming a transport is available in your language. diff --git a/docs/sdk/reference/language-bindings/php.md b/docs/sdk/reference/language-bindings/php.md index 2ec576c..bd5e819 100644 --- a/docs/sdk/reference/language-bindings/php.md +++ b/docs/sdk/reference/language-bindings/php.md @@ -3,8 +3,8 @@ diff --git a/docs/sdk/reference/language-bindings/python.md b/docs/sdk/reference/language-bindings/python.md index 9faa1ab..8caa57a 100644 --- a/docs/sdk/reference/language-bindings/python.md +++ b/docs/sdk/reference/language-bindings/python.md @@ -3,8 +3,8 @@ @@ -39,6 +39,8 @@ discovered_client = AntdClient(base_url=base_url) ## Store and retrieve data +For upload examples in this section, start `antd` in a write-enabled mode first. On the default network, that means wallet plus EVM payment configuration. On a local devnet, `ant dev start` provisions that for you. + ```python from antd import AntdClient diff --git a/docs/sdk/reference/language-bindings/ruby.md b/docs/sdk/reference/language-bindings/ruby.md index d3213c6..7fc0571 100644 --- a/docs/sdk/reference/language-bindings/ruby.md +++ b/docs/sdk/reference/language-bindings/ruby.md @@ -3,8 +3,8 @@ diff --git a/docs/sdk/reference/language-bindings/rust.md b/docs/sdk/reference/language-bindings/rust.md index 4d14c57..8ab4c5a 100644 --- a/docs/sdk/reference/language-bindings/rust.md +++ b/docs/sdk/reference/language-bindings/rust.md @@ -3,8 +3,8 @@ @@ -37,6 +37,8 @@ For gRPC, the current crate also exports `GrpcClient` and `DEFAULT_GRPC_ENDPOINT ## Store and retrieve data +For upload examples in this section, start `antd` in a write-enabled mode first. On the default network, that means wallet plus EVM payment configuration. On a local devnet, `ant dev start` provisions that for you. + ```rust use antd_client::{Client, DEFAULT_BASE_URL}; diff --git a/docs/sdk/reference/language-bindings/swift.md b/docs/sdk/reference/language-bindings/swift.md index 7f92093..9cdd459 100644 --- a/docs/sdk/reference/language-bindings/swift.md +++ b/docs/sdk/reference/language-bindings/swift.md @@ -3,8 +3,8 @@ diff --git a/docs/sdk/reference/language-bindings/typescript.md b/docs/sdk/reference/language-bindings/typescript.md index dacc080..fe3bb9a 100644 --- a/docs/sdk/reference/language-bindings/typescript.md +++ b/docs/sdk/reference/language-bindings/typescript.md @@ -3,8 +3,8 @@ diff --git a/docs/sdk/reference/language-bindings/zig.md b/docs/sdk/reference/language-bindings/zig.md index fdab821..47a2a65 100644 --- a/docs/sdk/reference/language-bindings/zig.md +++ b/docs/sdk/reference/language-bindings/zig.md @@ -3,8 +3,8 @@ diff --git a/docs/sdk/reference/overview.md b/docs/sdk/reference/overview.md index 839e879..4eca007 100644 --- a/docs/sdk/reference/overview.md +++ b/docs/sdk/reference/overview.md @@ -3,8 +3,8 @@ @@ -49,11 +49,11 @@ On startup, `antd` writes a `daemon.port` file with the resolved REST and gRPC p | Platform | `daemon.port` location | |------|------| -| Windows | `%APPDATA%\ant\daemon.port` | -| Linux | `~/.local/share/ant/daemon.port` or `$XDG_DATA_HOME/ant/daemon.port` | -| macOS | `~/Library/Application Support/ant/daemon.port` | +| Windows | `%APPDATA%\ant\sdk\daemon.port` | +| Linux | `~/.local/share/ant/sdk/daemon.port` or `$XDG_DATA_HOME/ant/sdk/daemon.port` | +| macOS | `~/Library/Application Support/ant/sdk/daemon.port` | -Current SDKs can use that file to discover non-default ports instead of hardcoding `8082`. +Several current SDKs can use that file to discover non-default ports instead of hardcoding `8082`. Check the language-specific page when you need to know whether discovery is automatic or exposed through an explicit helper. ## Current shared surfaces diff --git a/docs/sdk/reference/rest-api.md b/docs/sdk/reference/rest-api.md index 9c0b50b..38999f0 100644 --- a/docs/sdk/reference/rest-api.md +++ b/docs/sdk/reference/rest-api.md @@ -3,8 +3,8 @@ diff --git a/docs/sdk/retrieve-data-from-the-network.md b/docs/sdk/retrieve-data-from-the-network.md index 64f55c0..7724924 100644 --- a/docs/sdk/retrieve-data-from-the-network.md +++ b/docs/sdk/retrieve-data-from-the-network.md @@ -3,8 +3,8 @@ diff --git a/docs/sdk/start-the-local-daemon.md b/docs/sdk/start-the-local-daemon.md index 783bc2c..b688cb6 100644 --- a/docs/sdk/start-the-local-daemon.md +++ b/docs/sdk/start-the-local-daemon.md @@ -3,15 +3,15 @@ @@ -113,15 +113,19 @@ This mode is for the two-phase prepare and finalize upload flow described in [Us ### 5. Start a local devnet when you need a full local stack -If you want local services and test funds provisioned for you, use the helper from the repo root: +If you want local services and test funds provisioned for you, run the helper from the `ant-sdk` repo root: ```bash -cd .. +cd /path/to/ant-sdk pip install -e ant-dev/ -ant dev start +ant dev start --ant-node-dir ../ant-node ``` -`ant dev start` expects the `ant-node` repo to be cloned as a sibling of `ant-sdk`. +The `ant` command installed by `ant-dev` is separate from the direct-network `ant` CLI in `ant-client`. Use a virtualenv, `pipx`, or a separate `PATH` setup if you need both workflows on the same machine. + +If you just built `antd` in `ant-sdk/antd`, `cd ..` first to get back to the repo root. + +If the two repos are already laid out as siblings and discovery works in your environment, you can omit `--ant-node-dir`. It starts `ant-devnet`, waits for the generated devnet manifest, and then launches `antd` with the bootstrap peers, wallet key, and local EVM payment settings from that manifest. diff --git a/docs/sdk/store-data-on-the-network.md b/docs/sdk/store-data-on-the-network.md index 224d248..d05cdd4 100644 --- a/docs/sdk/store-data-on-the-network.md +++ b/docs/sdk/store-data-on-the-network.md @@ -3,8 +3,8 @@ diff --git a/skills/start/CHANGELOG.md b/skills/start/CHANGELOG.md index edaaaa6..a7bcb6a 100644 --- a/skills/start/CHANGELOG.md +++ b/skills/start/CHANGELOG.md @@ -4,10 +4,7 @@ All notable changes to this skill are recorded here. ## [Unreleased] -### Changed -- Moved the skill from `skills/autonomi-developer/` to `skills/start/` so the namespaced slash form is `/developer:start` instead of `/autonomi-developer:autonomi-developer`. Plugin identifier is now `developer` and the marketplace identifier is `withautonomi`. Internal `name:` and `skill:` fields and canonical URLs updated to match. - -## [0.1.1-draft] - 2026-04-30 +## [0.1.2-draft] - 2026-04-30 ### Changed - Reverified the skill against the current docs layout and current upstream source heads. @@ -17,13 +14,18 @@ All notable changes to this skill are recorded here. - Refreshed the pinned `ant-client` and `ant-protocol` verification commits and clarified `LocalDevnet::create_funded_client(...)` in the Direct Rust playbook. ### Verified Against -- ant-sdk: 1cbfb3e92cb4309f29e92b5609837812027f0a67 +- ant-sdk: d7652ec3da82dfbe2107778e5223dc413d95815b - ant-client: 8b2c9c606a1223f105fed9aa2b56310b6a6763da - ant-node: 23aee15cae33a17257ba833b2b98ed8a7a12e684 - ant-protocol: 65651f3a3243af8299a3e8d63385cba846ef88a4 - self_encryption: 5f9d1646231da7ca2ce60e84d010acfb6d9c29d0 - evmlib: 225acbb1af613193bcc8264b6ede4d7e4a7ac607 +## [0.1.1-draft] - 2026-04-30 + +### Changed +- Moved the skill from `skills/autonomi-developer/` to `skills/start/` so the namespaced slash form is `/developer:start` instead of `/autonomi-developer:autonomi-developer`. Plugin identifier is now `developer` and the marketplace identifier is `withautonomi`. Internal `name:` and `skill:` fields and canonical URLs updated to match. + ## [0.1.0-draft] - 2026-04-22 ### Added diff --git a/skills/start/SKILL.md b/skills/start/SKILL.md index 644a126..ecb86d9 100644 --- a/skills/start/SKILL.md +++ b/skills/start/SKILL.md @@ -8,7 +8,7 @@ description: | in Rust with `ant-core`, or expose Autonomi through an MCP-compatible client. Do not use for Autonomi 1.0, the MaidSafe-era network, `ant-quic`, or general EVM work that is not part of building on Autonomi. -version: 0.1.1-draft +version: 0.1.2-draft license: MIT repository: https://github.com/WithAutonomi/autonomi-developer-docs homepage: https://docs.autonomi.com/developers @@ -32,7 +32,7 @@ keywords: verified_date: 2026-04-30 verification_mode: current-merged-truth verified_commits: - ant-sdk: 1cbfb3e92cb4309f29e92b5609837812027f0a67 + ant-sdk: d7652ec3da82dfbe2107778e5223dc413d95815b ant-client: 8b2c9c606a1223f105fed9aa2b56310b6a6763da ant-node: 23aee15cae33a17257ba833b2b98ed8a7a12e684 ant-protocol: 65651f3a3243af8299a3e8d63385cba846ef88a4 @@ -136,7 +136,7 @@ Current daemon defaults: - REST: `http://localhost:8082` - gRPC: `localhost:50051` -- non-default ports can be discovered through the `daemon.port` file written by `antd` +- several SDKs expose helpers that read the `daemon.port` file written by `antd` Current shared daemon surfaces you can rely on at this commit: @@ -255,13 +255,17 @@ pip install "antd[rest]" pip install -e antd-mcp/ ``` +Run the editable install from an `ant-sdk` checkout root. + - stdio mode: `antd-mcp` - SSE mode: `antd-mcp --sse` -- daemon discovery order: +- daemon discovery still attempts this order: - `ANTD_BASE_URL` - `daemon.port` - `http://127.0.0.1:8082` +`ANTD_BASE_URL` is the reliable MCP setup path because `antd` writes `ant/sdk/daemon.port` while `antd-mcp` still reads `ant/daemon.port`. + Do not memorize MCP tool names or schemas in this skill. Fetch the MCP server reference when the task is MCP-specific. ## Concepts That Affect Implementation diff --git a/skills/start/version.json b/skills/start/version.json index 19b4b0f..754fa37 100644 --- a/skills/start/version.json +++ b/skills/start/version.json @@ -1,6 +1,6 @@ { "skill": "start", - "version": "0.1.1-draft", + "version": "0.1.2-draft", "published_date": "2026-04-30", "status": "draft", "canonical_skill_url": "https://raw.githubusercontent.com/WithAutonomi/autonomi-developer-docs/main/skills/start/SKILL.md", @@ -8,7 +8,7 @@ "repository": "https://github.com/WithAutonomi/autonomi-developer-docs", "verification_mode": "current-merged-truth", "verified_commits": { - "ant-sdk": "1cbfb3e92cb4309f29e92b5609837812027f0a67", + "ant-sdk": "d7652ec3da82dfbe2107778e5223dc413d95815b", "ant-client": "8b2c9c606a1223f105fed9aa2b56310b6a6763da", "ant-node": "23aee15cae33a17257ba833b2b98ed8a7a12e684", "ant-protocol": "65651f3a3243af8299a3e8d63385cba846ef88a4", From 066cdc05a4f1d1253d603884ae64483bff91937e Mon Sep 17 00:00:00 2001 From: Jim Collinson Date: Fri, 1 May 2026 10:06:39 +0100 Subject: [PATCH 2/4] Polish wording and troubleshooting guidance --- docs/cli/command-reference.md | 16 ++++++++-------- docs/core-concepts/payment-model.md | 4 ++-- .../estimate-costs-and-handle-upload-payments.md | 2 +- docs/guides/prepare-a-wallet-for-uploads.md | 4 ++-- docs/guides/set-up-a-local-network.md | 2 +- docs/guides/test-your-application.md | 2 +- docs/mcp/mcp-server-reference.md | 4 ++-- docs/mcp/use-mcp-with-ai-tools.md | 2 +- docs/mcp/use-the-autonomi-mcp-server.md | 2 +- .../use-external-signers-for-upload-payments.md | 2 +- docs/sdk/reference/grpc-services.md | 6 +++--- docs/sdk/reference/language-bindings/overview.md | 4 +--- docs/sdk/reference/overview.md | 2 +- docs/sdk/reference/rest-api.md | 2 +- docs/sdk/start-the-local-daemon.md | 4 ++-- skills/start/SKILL.md | 4 ++-- 16 files changed, 30 insertions(+), 32 deletions(-) diff --git a/docs/cli/command-reference.md b/docs/cli/command-reference.md index 0a814f0..5b82bfb 100644 --- a/docs/cli/command-reference.md +++ b/docs/cli/command-reference.md @@ -8,7 +8,7 @@ verification_mode: current-merged-truth --> -Reference for the `ant` CLI command tree and its current flags. The command tree below follows the current direct-network CLI surface, and the option tables stay grouped by command family for easier scanning. A few hidden or advanced flags are included where they matter for troubleshooting. +Reference for the `ant` CLI command tree and its flags. The command tree below follows the direct-network CLI surface, and the option tables stay grouped by command family for easier scanning. Hidden or advanced flags are called out where they matter for troubleshooting. ## Command tree @@ -53,10 +53,10 @@ The root command accepts the global flags used across data and node operations. | `--devnet-manifest ` | path | No | Path to a local devnet manifest JSON file | | `--allow-loopback` | boolean | No | Allow loopback connections for local devnet or local testing | | `--ipv4-only` | boolean | No | Disable dual-stack and force IPv4-only mode | -| `--quote-timeout-secs ` | integer | No | Hidden advanced flag for lightweight network-operation timeouts such as DHT lookups | -| `--store-timeout-secs ` | integer | No | Hidden advanced flag for chunk store and retrieve timeouts | -| `--quote-concurrency ` | integer | No | Hidden advanced flag that caps the quote channel only. It does not affect store or download concurrency. | -| `--store-concurrency ` | integer | No | Hidden advanced flag for upload chunk concurrency. `--chunk-concurrency` is accepted as an alias. | +| `--quote-timeout-secs ` | integer | No | Hidden. Controls lightweight network-operation timeouts such as DHT lookups. | +| `--store-timeout-secs ` | integer | No | Hidden. Controls chunk store and retrieve timeouts. | +| `--quote-concurrency ` | integer | No | Hidden. Caps the quote channel only. It does not affect store or download concurrency. | +| `--store-concurrency ` | integer | No | Hidden. Controls upload chunk concurrency. `--chunk-concurrency` is accepted as an alias. | | `-v, --verbose...` | count | No | Increase log verbosity: `-v`, `-vv`, or `-vvv` | | `--evm-network ` | string | No | EVM network for payments: `arbitrum-one`, `arbitrum-sepolia`, or `local` | | `-h, --help` | boolean | No | Print help | @@ -88,9 +88,9 @@ Uploads a file with self-encryption and EVM payment. | `--public` | boolean | No | Store the DataMap on-network so anyone with the address can download the file | | `--merkle` | boolean | No | Force Merkle batch payment | | `--no-merkle` | boolean | No | Force single per-chunk payments | -| `--store-timeout ` | integer | No | Hidden advanced flag that overrides the chunk store timeout for this upload | -| `--store-concurrency ` | integer | No | Hidden advanced flag that overrides upload chunk concurrency for this upload | -| `--overwrite` | boolean | No | Replace an existing `.datamap` instead of writing a suffixed datamap filename | +| `--store-timeout ` | integer | No | Hidden. Overrides the chunk store timeout for this upload. | +| `--store-concurrency ` | integer | No | Hidden. Overrides upload chunk concurrency for this upload. | +| `--overwrite` | boolean | No | Replace any existing `.datamap` instead of writing a suffixed `-2.datamap`. | **Example:** diff --git a/docs/core-concepts/payment-model.md b/docs/core-concepts/payment-model.md index 868f1d9..3e721ed 100644 --- a/docs/core-concepts/payment-model.md +++ b/docs/core-concepts/payment-model.md @@ -88,11 +88,11 @@ The supported payment modes are: | `merkle` | Force Merkle batch payment | | `single` | Force per-chunk payment | -In `ant-core`, the current Merkle threshold is `64` chunks. +In `ant-core`, the Merkle threshold is `64` chunks. Nodes verify the payment proof that arrives with each write. That includes signature checks, on-chain payment verification, and record-level validation before content is accepted into the chunk store. -Node-side storage pricing currently follows `BASELINE + K × (n / D)^2`, where `n` is the number of close records the node is already storing and `D` is a fixed divisor. That gives lightly loaded nodes a non-zero spam-barrier price and pushes larger uploads toward less-loaded close groups as the network fills. +Node-side storage pricing follows `BASELINE + K × (n / D)^2`, where `n` is the number of close records the node is already storing and `D` is a fixed divisor. That gives lightly loaded nodes a non-zero spam-barrier price and pushes larger uploads toward less-loaded close groups as the network fills. ### What happens on retrieval diff --git a/docs/guides/estimate-costs-and-handle-upload-payments.md b/docs/guides/estimate-costs-and-handle-upload-payments.md index 8913ff6..5d1ea39 100644 --- a/docs/guides/estimate-costs-and-handle-upload-payments.md +++ b/docs/guides/estimate-costs-and-handle-upload-payments.md @@ -100,7 +100,7 @@ On public EVM networks, both values matter: Fresh wallets may need an approval transaction before uploads can spend tokens through the payment contracts. -This approval currently grants the payment contracts an unlimited token allowance. +This approval grants the payment contracts an unlimited token allowance. {% tabs %} {% tab title="cURL" %} diff --git a/docs/guides/prepare-a-wallet-for-uploads.md b/docs/guides/prepare-a-wallet-for-uploads.md index 9cbe8e6..7aeddab 100644 --- a/docs/guides/prepare-a-wallet-for-uploads.md +++ b/docs/guides/prepare-a-wallet-for-uploads.md @@ -71,7 +71,7 @@ export EVM_PAYMENT_VAULT_ADDRESS="0x..." ./target/release/antd ``` -If `antd` is already on your `PATH`, use `antd` instead. +If `antd` is already on your `PATH`, replace `./target/release/antd` with `antd`. ### 3. Configure a wallet for ant @@ -112,7 +112,7 @@ EVM_PAYMENT_VAULT_ADDRESS=0x... \ ./target/release/antd ``` -If `antd` is already on your `PATH`, use `antd` instead. +If `antd` is already on your `PATH`, replace `./target/release/antd` with `antd`. Use `EVM_PAYMENT_VAULT_ADDRESS` for both wave-batch and Merkle external-signer uploads in this configuration. diff --git a/docs/guides/set-up-a-local-network.md b/docs/guides/set-up-a-local-network.md index 9e73152..b47ef01 100644 --- a/docs/guides/set-up-a-local-network.md +++ b/docs/guides/set-up-a-local-network.md @@ -47,7 +47,7 @@ cd ant-sdk pip install -e ant-dev/ ``` -The `ant` command installed by `ant-dev` is separate from the direct-network `ant` CLI in `ant-client`. Use a virtualenv, `pipx`, or a separate `PATH` setup if you need both workflows on the same machine. +The `ant` command installed by `ant-dev` is separate from [the direct-network CLI](../cli/use-the-cli.md). Use a virtualenv, `pipx`, or a separate `PATH` setup if you need both workflows on the same machine. This installs the `ant` command provided by the current `ant-dev` package. diff --git a/docs/guides/test-your-application.md b/docs/guides/test-your-application.md index 668accd..c9974d9 100644 --- a/docs/guides/test-your-application.md +++ b/docs/guides/test-your-application.md @@ -31,7 +31,7 @@ This guide focuses on the shared testing progression that applies across SDK, CL - A test framework for your language - `ant-dev` installed from an `ant-sdk` checkout, or a direct-network local devnet if you are testing `ant-core` -If you also use the direct-network `ant` CLI from `ant-client`, isolate `ant-dev` in a virtualenv, `pipx`, or a separate `PATH` so the two `ant` commands do not shadow each other. +If you also use [the direct-network CLI](../cli/use-the-cli.md), isolate `ant-dev` in a virtualenv, `pipx`, or a separate `PATH` so the two `ant` commands do not shadow each other. ## Steps diff --git a/docs/mcp/mcp-server-reference.md b/docs/mcp/mcp-server-reference.md index 8825359..484778d 100644 --- a/docs/mcp/mcp-server-reference.md +++ b/docs/mcp/mcp-server-reference.md @@ -35,7 +35,7 @@ pip install -e antd-mcp/ Run the editable install from an `ant-sdk` checkout root. -The package metadata currently declares: +The package metadata declares: - Python `>=3.10` - dependency on `mcp>=1.2.0` @@ -59,7 +59,7 @@ At startup, the server resolves the daemon base URL in this order: The discovery helper still checks a `daemon.port` file before falling back to the default URL. -`antd` writes `ant/sdk/daemon.port`, while `antd-mcp` still reads `ant/daemon.port`. Treat `ANTD_BASE_URL` as the reliable configuration path unless you have already confirmed port-file discovery works in your environment. +`antd` writes `ant/sdk/daemon.port`, while `antd-mcp` reads `ant/daemon.port`. Treat `ANTD_BASE_URL` as the reliable configuration path unless you have already confirmed port-file discovery works in your environment. ## Claude Desktop configuration diff --git a/docs/mcp/use-mcp-with-ai-tools.md b/docs/mcp/use-mcp-with-ai-tools.md index f9a6a9b..7a665aa 100644 --- a/docs/mcp/use-mcp-with-ai-tools.md +++ b/docs/mcp/use-mcp-with-ai-tools.md @@ -26,7 +26,7 @@ The MCP server talks to `antd`, so start there first: ./target/release/antd ``` -Run that command from the `ant-sdk/antd` build directory. If `antd` is already on your `PATH`, use `antd` instead. +Run that command from the `ant-sdk/antd` build directory, or use `antd` if the binary is already on your `PATH`. If you have not built `antd` yet, follow [Build with the SDKs](../sdk/install.md) and [Start the Local Daemon](../sdk/start-the-local-daemon.md) first. diff --git a/docs/mcp/use-the-autonomi-mcp-server.md b/docs/mcp/use-the-autonomi-mcp-server.md index 3a6e428..85af4d6 100644 --- a/docs/mcp/use-the-autonomi-mcp-server.md +++ b/docs/mcp/use-the-autonomi-mcp-server.md @@ -34,7 +34,7 @@ The `antd-mcp` package installs a command named `antd-mcp`. The server still attempts `daemon.port` discovery before falling back to the default REST URL. -`antd` writes `ant/sdk/daemon.port`, while `antd-mcp` still reads `ant/daemon.port`. Treat `ANTD_BASE_URL` as the reliable setup path unless you have already confirmed port-file discovery works in your environment. +`antd` writes `ant/sdk/daemon.port`, while `antd-mcp` reads `ant/daemon.port`. Treat `ANTD_BASE_URL` as the reliable setup path unless you have already confirmed port-file discovery works in your environment. If no environment variable or readable port file is available, it falls back to: diff --git a/docs/sdk/how-to-guides/use-external-signers-for-upload-payments.md b/docs/sdk/how-to-guides/use-external-signers-for-upload-payments.md index ab41749..25ef6ae 100644 --- a/docs/sdk/how-to-guides/use-external-signers-for-upload-payments.md +++ b/docs/sdk/how-to-guides/use-external-signers-for-upload-payments.md @@ -51,7 +51,7 @@ EVM_PAYMENT_VAULT_ADDRESS=0x... \ ./target/release/antd ``` -If `antd` is already on your `PATH`, use `antd` instead. +If `antd` is already on your `PATH`, replace `./target/release/antd` with `antd`. Use `EVM_PAYMENT_VAULT_ADDRESS` for both wave-batch and Merkle uploads in the external-signer flow. diff --git a/docs/sdk/reference/grpc-services.md b/docs/sdk/reference/grpc-services.md index bb0b66e..8499806 100644 --- a/docs/sdk/reference/grpc-services.md +++ b/docs/sdk/reference/grpc-services.md @@ -45,7 +45,7 @@ Stores public data. **Signature:** `StreamPublic(StreamPublicDataRequest) -> stream DataChunk` -Current merged code exposes this RPC, but the handler is still stubbed and currently returns `UNIMPLEMENTED`. +This RPC is exposed, but the handler returns `UNIMPLEMENTED`. ### Get Private @@ -121,9 +121,9 @@ Estimates file upload cost. **Signature:** `Subscribe(SubscribeRequest) -> stream ClientEventProto` -Current merged code exposes this RPC, but the stream is still stubbed and currently stays open without emitting events. +This RPC is exposed, but the stream stays open without emitting events. -`ClientEventProto` currently includes: +`ClientEventProto` includes: | Name | Type | Description | |------|------|-------------| diff --git a/docs/sdk/reference/language-bindings/overview.md b/docs/sdk/reference/language-bindings/overview.md index aba0133..0259866 100644 --- a/docs/sdk/reference/language-bindings/overview.md +++ b/docs/sdk/reference/language-bindings/overview.md @@ -8,7 +8,7 @@ verification_mode: current-merged-truth --> -The language bindings in `ant-sdk` are clients for the `antd` daemon. They share the same daemon surface, but they do not currently expose identical constructors, transports, or helper APIs. +The language bindings in `ant-sdk` are clients for the `antd` daemon. They share the same daemon surface, but they do not expose identical constructors, transports, or helper APIs. ## Architecture @@ -31,8 +31,6 @@ Bindings usually default to those same endpoints when you do not supply an overr ## Current transport split -At this commit: - - JavaScript and TypeScript are documented as REST-based - Python, Go, and Rust document both REST and gRPC support - other bindings vary by package and current docs coverage diff --git a/docs/sdk/reference/overview.md b/docs/sdk/reference/overview.md index 4eca007..e737ddf 100644 --- a/docs/sdk/reference/overview.md +++ b/docs/sdk/reference/overview.md @@ -53,7 +53,7 @@ On startup, `antd` writes a `daemon.port` file with the resolved REST and gRPC p | Linux | `~/.local/share/ant/sdk/daemon.port` or `$XDG_DATA_HOME/ant/sdk/daemon.port` | | macOS | `~/Library/Application Support/ant/sdk/daemon.port` | -Several current SDKs can use that file to discover non-default ports instead of hardcoding `8082`. Check the language-specific page when you need to know whether discovery is automatic or exposed through an explicit helper. +Some SDKs expose a helper that reads this file instead of hardcoding `8082`. Check the language-specific page when you need to know whether discovery is automatic or exposed through an explicit helper. ## Current shared surfaces diff --git a/docs/sdk/reference/rest-api.md b/docs/sdk/reference/rest-api.md index 38999f0..ab08b2d 100644 --- a/docs/sdk/reference/rest-api.md +++ b/docs/sdk/reference/rest-api.md @@ -100,7 +100,7 @@ curl http://localhost:8082/v1/data/public/ **Endpoint:** `GET /v1/data/public/{addr}/stream` -Current merged code exposes this streaming endpoint, but the handler is still a stub at this commit and currently returns an empty SSE stream. +This endpoint is exposed, but the handler is still a stub and returns an empty SSE stream. **Parameters:** diff --git a/docs/sdk/start-the-local-daemon.md b/docs/sdk/start-the-local-daemon.md index b688cb6..d1887bc 100644 --- a/docs/sdk/start-the-local-daemon.md +++ b/docs/sdk/start-the-local-daemon.md @@ -41,7 +41,7 @@ cd ant-sdk/antd cargo build --release ``` -`antd` currently needs `protoc` during the build. On macOS, one working setup is: +`antd` needs `protoc` during the build. On macOS, one working setup is: ```bash brew install protobuf @@ -121,7 +121,7 @@ pip install -e ant-dev/ ant dev start --ant-node-dir ../ant-node ``` -The `ant` command installed by `ant-dev` is separate from the direct-network `ant` CLI in `ant-client`. Use a virtualenv, `pipx`, or a separate `PATH` setup if you need both workflows on the same machine. +The `ant` command installed by `ant-dev` is separate from [the direct-network CLI](../cli/use-the-cli.md). Use a virtualenv, `pipx`, or a separate `PATH` setup if you need both workflows on the same machine. If you just built `antd` in `ant-sdk/antd`, `cd ..` first to get back to the repo root. diff --git a/skills/start/SKILL.md b/skills/start/SKILL.md index ecb86d9..12bda1d 100644 --- a/skills/start/SKILL.md +++ b/skills/start/SKILL.md @@ -264,7 +264,7 @@ Run the editable install from an `ant-sdk` checkout root. - `daemon.port` - `http://127.0.0.1:8082` -`ANTD_BASE_URL` is the reliable MCP setup path because `antd` writes `ant/sdk/daemon.port` while `antd-mcp` still reads `ant/daemon.port`. +`ANTD_BASE_URL` is the reliable MCP setup path because `antd` writes `ant/sdk/daemon.port` while `antd-mcp` reads `ant/daemon.port`. Do not memorize MCP tool names or schemas in this skill. Fetch the MCP server reference when the task is MCP-specific. @@ -369,7 +369,7 @@ Check whether the test expects raw bytes over REST. Current REST binary payloads ## Hard Constraints - Do not reference Autonomi 1.0 as if it were current. -- Do not reference `ant-quic` in current Autonomi work. +- Do not reference `ant-quic` in Autonomi 2.0 work. - Do not guess endpoints, flags, method names, or contract details. - Do not put real wallet keys into committed code. - Do not walk a user into public-network uploads without checking that they understand the money and irreversibility involved. From c55c2e6b6496a5920cc2c04ee09a52733342490a Mon Sep 17 00:00:00 2001 From: Jim Collinson Date: Fri, 1 May 2026 10:17:50 +0100 Subject: [PATCH 3/4] Tighten local dev CLI warning copy --- docs/guides/set-up-a-local-network.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/guides/set-up-a-local-network.md b/docs/guides/set-up-a-local-network.md index b47ef01..6404945 100644 --- a/docs/guides/set-up-a-local-network.md +++ b/docs/guides/set-up-a-local-network.md @@ -47,10 +47,10 @@ cd ant-sdk pip install -e ant-dev/ ``` -The `ant` command installed by `ant-dev` is separate from [the direct-network CLI](../cli/use-the-cli.md). Use a virtualenv, `pipx`, or a separate `PATH` setup if you need both workflows on the same machine. - This installs the `ant` command provided by the current `ant-dev` package. +That `ant` command is separate from [the direct-network CLI](../cli/use-the-cli.md). Use a virtualenv, `pipx`, or a separate `PATH` setup if you need both workflows on the same machine. + If `antd` has not been built on this machine before, make sure `protoc` is installed first. On macOS, one working setup is `brew install protobuf`. ### 3. Start the local environment From 853139fa9cec92bb7a4dd0ff6d594de2db5d2eee Mon Sep 17 00:00:00 2001 From: Jim Collinson Date: Fri, 1 May 2026 10:30:51 +0100 Subject: [PATCH 4/4] Clean up remaining wording nits --- docs/guides/set-up-a-local-network.md | 2 +- docs/sdk/reference/language-bindings/overview.md | 8 ++++---- docs/sdk/reference/overview.md | 4 ++-- docs/sdk/reference/rest-api.md | 2 +- 4 files changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/guides/set-up-a-local-network.md b/docs/guides/set-up-a-local-network.md index 6404945..288251d 100644 --- a/docs/guides/set-up-a-local-network.md +++ b/docs/guides/set-up-a-local-network.md @@ -47,7 +47,7 @@ cd ant-sdk pip install -e ant-dev/ ``` -This installs the `ant` command provided by the current `ant-dev` package. +This installs the `ant` command provided by the `ant-dev` package. That `ant` command is separate from [the direct-network CLI](../cli/use-the-cli.md). Use a virtualenv, `pipx`, or a separate `PATH` setup if you need both workflows on the same machine. diff --git a/docs/sdk/reference/language-bindings/overview.md b/docs/sdk/reference/language-bindings/overview.md index 0259866..522533e 100644 --- a/docs/sdk/reference/language-bindings/overview.md +++ b/docs/sdk/reference/language-bindings/overview.md @@ -20,7 +20,7 @@ The pattern is: 2. the language client talks to `antd` 3. `antd` talks to the Autonomi network through `ant-core` -## Current defaults +## Defaults The daemon defaults are: @@ -29,11 +29,11 @@ The daemon defaults are: Bindings usually default to those same endpoints when you do not supply an override. -## Current transport split +## Transport Split - JavaScript and TypeScript are documented as REST-based - Python, Go, and Rust document both REST and gRPC support -- other bindings vary by package and current docs coverage +- other bindings vary by package and docs coverage Check the individual page before assuming a transport is available in your language. @@ -50,7 +50,7 @@ Examples from the current packages: Some bindings use discovery only through explicit helper APIs rather than by default constructors. -## Current naming differences +## Naming Differences The bindings use different entry points: diff --git a/docs/sdk/reference/overview.md b/docs/sdk/reference/overview.md index e737ddf..75ec4d9 100644 --- a/docs/sdk/reference/overview.md +++ b/docs/sdk/reference/overview.md @@ -55,11 +55,11 @@ On startup, `antd` writes a `daemon.port` file with the resolved REST and gRPC p Some SDKs expose a helper that reads this file instead of hardcoding `8082`. Check the language-specific page when you need to know whether discovery is automatic or exposed through an explicit helper. -## Current shared surfaces +## Shared Surfaces The `antd` REST surface groups into these areas: -| Group | Current routes | +| Group | Routes | |------|------| | Health | `/health` | | Data | `/v1/data/public`, `/v1/data/private`, `/v1/data/cost` | diff --git a/docs/sdk/reference/rest-api.md b/docs/sdk/reference/rest-api.md index ab08b2d..b0a74cf 100644 --- a/docs/sdk/reference/rest-api.md +++ b/docs/sdk/reference/rest-api.md @@ -100,7 +100,7 @@ curl http://localhost:8082/v1/data/public/ **Endpoint:** `GET /v1/data/public/{addr}/stream` -This endpoint is exposed, but the handler is still a stub and returns an empty SSE stream. +This endpoint is exposed, but the handler is a stub and returns an empty SSE stream. **Parameters:**