From a3e95dc4df2a10a74aa2c4ac3b0eb3391045493d Mon Sep 17 00:00:00 2001 From: Jim Collinson Date: Thu, 23 Apr 2026 15:11:09 +0100 Subject: [PATCH 1/2] Add initial Autonomi developer skill --- component-registry.yml | 46 ++- skills/autonomi-developer/CHANGELOG.md | 25 ++ skills/autonomi-developer/MAINTAINING.md | 136 ++++++++ skills/autonomi-developer/SKILL.md | 403 +++++++++++++++++++++++ skills/autonomi-developer/version.json | 24 ++ 5 files changed, 633 insertions(+), 1 deletion(-) create mode 100644 skills/autonomi-developer/CHANGELOG.md create mode 100644 skills/autonomi-developer/MAINTAINING.md create mode 100644 skills/autonomi-developer/SKILL.md create mode 100644 skills/autonomi-developer/version.json diff --git a/component-registry.yml b/component-registry.yml index 433bf32..0a086a9 100644 --- a/component-registry.yml +++ b/component-registry.yml @@ -1,5 +1,5 @@ # Component Registry — Autonomi Developer Documentation -# Maps components within each repo to the documentation pages they feed. +# Maps components within each repo to the documentation pages and skills they feed. # See CLAUDE.md for how agents use this during writing and auditing. # See repo-registry.yml for repo-level scope and behaviour. @@ -21,6 +21,8 @@ components: - sdk-reference/overview.md - sdk-reference/rest-api.md - sdk-reference/daemon-cli.md + feeds_skills: + - skills/autonomi-developer/SKILL.md openapi: repo: ant-sdk @@ -30,6 +32,8 @@ components: - rest-api feeds_pages: - sdk-reference/rest-api.md + feeds_skills: + - skills/autonomi-developer/SKILL.md proto: repo: ant-sdk @@ -39,6 +43,8 @@ components: - grpc feeds_pages: - sdk-reference/grpc-services.md + feeds_skills: + - skills/autonomi-developer/SKILL.md antd-rust: repo: ant-sdk @@ -48,6 +54,8 @@ components: - rust-binding feeds_pages: - sdk-reference/language-bindings/rust.md + feeds_skills: + - skills/autonomi-developer/SKILL.md antd-py: repo: ant-sdk @@ -57,6 +65,8 @@ components: - python-binding feeds_pages: - sdk-reference/language-bindings/python.md + feeds_skills: + - skills/autonomi-developer/SKILL.md antd-js: repo: ant-sdk @@ -66,6 +76,8 @@ components: - javascript-binding feeds_pages: - sdk-reference/language-bindings/javascript.md + feeds_skills: + - skills/autonomi-developer/SKILL.md antd-go: repo: ant-sdk @@ -75,6 +87,8 @@ components: - go-binding feeds_pages: - sdk-reference/language-bindings/go.md + feeds_skills: + - skills/autonomi-developer/SKILL.md antd-java: repo: ant-sdk @@ -84,6 +98,8 @@ components: - java-binding feeds_pages: - sdk-reference/language-bindings/java.md + feeds_skills: + - skills/autonomi-developer/SKILL.md antd-csharp: repo: ant-sdk @@ -93,6 +109,8 @@ components: - csharp-binding feeds_pages: - sdk-reference/language-bindings/csharp.md + feeds_skills: + - skills/autonomi-developer/SKILL.md antd-kotlin: repo: ant-sdk @@ -102,6 +120,8 @@ components: - kotlin-binding feeds_pages: - sdk-reference/language-bindings/kotlin.md + feeds_skills: + - skills/autonomi-developer/SKILL.md antd-swift: repo: ant-sdk @@ -111,6 +131,8 @@ components: - swift-binding feeds_pages: - sdk-reference/language-bindings/swift.md + feeds_skills: + - skills/autonomi-developer/SKILL.md antd-ruby: repo: ant-sdk @@ -120,6 +142,8 @@ components: - ruby-binding feeds_pages: - sdk-reference/language-bindings/ruby.md + feeds_skills: + - skills/autonomi-developer/SKILL.md antd-php: repo: ant-sdk @@ -129,6 +153,8 @@ components: - php-binding feeds_pages: - sdk-reference/language-bindings/php.md + feeds_skills: + - skills/autonomi-developer/SKILL.md antd-cpp: repo: ant-sdk @@ -138,6 +164,8 @@ components: - cpp-binding feeds_pages: - sdk-reference/language-bindings/cpp.md + feeds_skills: + - skills/autonomi-developer/SKILL.md antd-dart: repo: ant-sdk @@ -147,6 +175,8 @@ components: - dart-binding feeds_pages: - sdk-reference/language-bindings/dart.md + feeds_skills: + - skills/autonomi-developer/SKILL.md antd-zig: repo: ant-sdk @@ -156,6 +186,8 @@ components: - zig-binding feeds_pages: - sdk-reference/language-bindings/zig.md + feeds_skills: + - skills/autonomi-developer/SKILL.md # === ant-client === @@ -173,6 +205,8 @@ components: - how-to-guides/store-and-retrieve-data.md - how-to-guides/handle-payments.md - cli-reference/ant-core-library.md + feeds_skills: + - skills/autonomi-developer/SKILL.md ant-cli: repo: ant-client @@ -185,6 +219,8 @@ components: - cli-reference/overview.md - cli-reference/command-reference.md - getting-started/using-ant-client.md + feeds_skills: + - skills/autonomi-developer/SKILL.md # === ant-node === @@ -200,6 +236,8 @@ components: - core-concepts/payment-model.md - how-to-guides/setup-local-network.md - how-to-guides/embed-a-node.md + feeds_skills: + - skills/autonomi-developer/SKILL.md ant-devnet: repo: ant-node @@ -209,6 +247,8 @@ components: - devnet-launcher feeds_pages: - how-to-guides/setup-local-network.md + feeds_skills: + - skills/autonomi-developer/SKILL.md # === Foundational single-crate repos === @@ -256,6 +296,8 @@ components: feeds_pages: - core-concepts/self-encryption.md - core-concepts/data-types.md + feeds_skills: + - skills/autonomi-developer/SKILL.md evmlib: repo: evmlib @@ -268,6 +310,8 @@ components: - core-concepts/payment-model.md - how-to-guides/handle-payments.md - how-to-guides/manage-keys.md + feeds_skills: + - skills/autonomi-developer/SKILL.md ant-merkle: repo: ant-merkle diff --git a/skills/autonomi-developer/CHANGELOG.md b/skills/autonomi-developer/CHANGELOG.md new file mode 100644 index 0000000..81e30ed --- /dev/null +++ b/skills/autonomi-developer/CHANGELOG.md @@ -0,0 +1,25 @@ +# Changelog - autonomi-developer skill + +All notable changes to this skill are recorded here. + +## [Unreleased] + +## [0.1.0-draft] - 2026-04-22 + +### Added +- Initial in-repo `autonomi-developer` skill package. +- Operational path selector for SDK, CLI, Direct Rust, and MCP work. +- Exact golden flows for daemon health, SDK public data round-trip, CLI public file round-trip, and local devnet startup checks. +- Live reference table for the current docs site. +- Skill version manifest and maintenance guide. + +### Changed +- Rebuilt the skill around the current docs and current upstream source artifacts instead of the earlier standalone draft. +- Reduced deep network internals so the skill stays focused on building and shipping applications. + +### Verified Against +- ant-sdk: 2ed9b14bda42fbdc604a173cc1af27be0964908f +- ant-client: b0c501a163c1a95bdbfc703892b88a8a91f7e482 +- ant-node: 5a5d7d4fed766cd56d0f97f337fcd5ff049bea6a +- self_encryption: 5f9d1646231da7ca2ce60e84d010acfb6d9c29d0 +- evmlib: 82f2fccff243b48de0e04ceb71ccb2aa17d810af diff --git a/skills/autonomi-developer/MAINTAINING.md b/skills/autonomi-developer/MAINTAINING.md new file mode 100644 index 0000000..c73c248 --- /dev/null +++ b/skills/autonomi-developer/MAINTAINING.md @@ -0,0 +1,136 @@ +# Maintaining the `autonomi-developer` skill + +This skill lives in `skills/autonomi-developer/` and follows the same source-of-truth model as the rest of the docs repo. + +## Files that move together + +Every release or re-verification pass updates these files together: + +- `SKILL.md` +- `version.json` +- `CHANGELOG.md` + +## Current scope + +This skill is intentionally practical. It covers: + +- SDK and daemon workflows +- CLI workflows +- Direct Rust with `ant-core` +- MCP setup rules +- read-only versus upload-enabled architecture +- local devnet testing +- wallet and payment basics needed to build safely + +It does not try to teach the deeper routing, transport, or cryptography internals in detail. If the skill grows into those areas later, update the component mapping first. + +## Verification inputs + +Use the same workflow the docs use: + +1. Source audit +2. Draft +3. Verify + +Read these repo files before changing the skill: + +- `CLAUDE.md` +- `planning/verification-workflow.md` +- `repo-registry.yml` +- `component-registry.yml` + +## Components that currently feed this skill + +The skill is mapped through `feeds_skills:` in `component-registry.yml`. + +Current component coverage: + +- `antd`, `openapi`, `proto`, and the documented `antd-*` language bindings +- `ant-core` +- `ant-cli` +- `ant-node` +- `ant-devnet` +- `self_encryption` +- `evmlib` + +That means these repos trigger re-verification today: + +- `ant-sdk` +- `ant-client` +- `ant-node` +- `self_encryption` +- `evmlib` + +## When to re-verify + +Run a skill verification pass when: + +- one of the mapped repos changes in a way that can affect the skill +- a docs page URL baked into `SKILL.md` changes +- a golden flow in the skill stops matching the current docs or source artifacts +- the skill adds or removes path coverage + +## What to verify + +### SDK path + +Check current daemon defaults and exact route names against the active `ant-sdk` source artifacts. + +Use these artifacts first: + +- `antd/openapi.yaml` +- `antd/proto/` +- `antd-mcp/README.md` when MCP setup rules are in scope + +### CLI path + +Check command names, global-flag placement, and quickstart flows against the active `ant-client` sources. + +Use these artifacts first: + +- `README.md` +- current help output if you have the repo checked out locally + +### Direct Rust path + +Check named `ant-core` surfaces against the active `ant-client` sources. + +Use these artifacts first: + +- `README.md` +- public Rust API docs or examples in `ant-core` + +### Concepts and safety rules + +Check these against the relevant docs pages and source repos: + +- public versus private data +- wallet key versus public address versus `DataMap` +- self-encryption behavior +- payment and wallet handling +- local devnet workflow + +## Update order + +1. Update `SKILL.md`. +2. Update `version.json` with the same version, date, and verified commits. +3. Add a matching entry to `CHANGELOG.md`. + +## Versioning + +Use Semantic Versioning with these rules: + +- major: breaking changes to skill loading or manifest shape +- minor: new paths, new verified examples, or new operational capabilities +- patch: wording fixes, pointer fixes, or re-verification-only updates + +Keep the `-draft` suffix until the skill has gone through at least one deliberate re-verification pass after landing in the repo. + +## Pre-merge checklist + +- [ ] `SKILL.md`, `version.json`, and `CHANGELOG.md` agree on the version. +- [ ] `verified_date` and `published_date` match. +- [ ] every `verified_commits` entry is a real SHA +- [ ] every live-docs URL in `SKILL.md` resolves +- [ ] no hard-coded detail was added without a matching verification source +- [ ] the skill still avoids guessed SDK methods, CLI flags, and MCP tool names diff --git a/skills/autonomi-developer/SKILL.md b/skills/autonomi-developer/SKILL.md new file mode 100644 index 0000000..2f55ccf --- /dev/null +++ b/skills/autonomi-developer/SKILL.md @@ -0,0 +1,403 @@ +--- +name: autonomi-developer +description: | + Build applications, automations, and AI workflows on the Autonomi Network. + Use this skill when the user wants to store or retrieve data, add Autonomi + storage to an application, build read-only or upload-enabled features, use + the `antd` daemon and SDK bindings, work from the `ant` CLI, build directly + 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.0-draft +license: MIT +repository: https://github.com/WithAutonomi/autonomi-developer-docs +homepage: https://docs.autonomi.com/developers +author: Autonomi Developer Documentation +keywords: + - autonomi + - ant-sdk + - antd + - ant-client + - ant-core + - ant + - mcp + - devnet + - datamap + - self-encryption + - uploads + - read-only + +# Verification block. Re-verify before changing stable claims or examples. +verified_date: 2026-04-22 +verification_mode: current-merged-truth +verified_commits: + ant-sdk: 2ed9b14bda42fbdc604a173cc1af27be0964908f + ant-client: b0c501a163c1a95bdbfc703892b88a8a91f7e482 + ant-node: 5a5d7d4fed766cd56d0f97f337fcd5ff049bea6a + self_encryption: 5f9d1646231da7ca2ce60e84d010acfb6d9c29d0 + evmlib: 82f2fccff243b48de0e04ceb71ccb2aa17d810af + +version_manifest_url: https://raw.githubusercontent.com/WithAutonomi/autonomi-developer-docs/main/skills/autonomi-developer/version.json +canonical_docs_url: https://docs.autonomi.com/developers +--- + +# Autonomi Developer + +This skill makes you effective at building on the Autonomi Network without making the user read the full docs set first. Treat it as an operational guide: pick the correct Autonomi path, fetch one live reference when exact interface details matter, and do not invent Autonomi-specific APIs. + +## Scope + +Use this skill when the task is about: + +- storing or retrieving data on Autonomi +- adding Autonomi storage to an application +- building read-only or upload-enabled features +- using `antd` and the SDK bindings +- using the `ant` CLI +- building directly in Rust with `ant-core` +- exposing Autonomi through an MCP-compatible client +- testing with a local devnet before public-network deployment + +Do not use this skill for: + +- Autonomi 1.0 or anything under the MaidSafe org unless the user explicitly wants historical context +- `ant-quic` or older transport docs +- general EVM, Arbitrum, IPFS, or Filecoin work unrelated to building on Autonomi + +## Operating Rules + +1. Check whether a newer verified version of this skill exists: + +```bash +curl -fsSL https://raw.githubusercontent.com/WithAutonomi/autonomi-developer-docs/main/skills/autonomi-developer/version.json +``` + +If the published `version` is newer, tell the user this copy may be stale and offer to reload it. If the fetch fails, continue silently. + +2. Pick one path before you start coding: SDK, CLI, Direct Rust, or MCP. + +3. Fetch one live reference page once per task when you need volatile details such as install steps, exact REST or gRPC schemas, binding-specific helpers, CLI flags, or MCP tool names. + +4. Do not invent Autonomi-specific details. If this skill does not name a route, flag, method, env var, or tool and you have not fetched the live reference, do not guess it. + +5. For anything that uploads data, start on a local devnet first unless the user explicitly wants public-network work. + +6. Ask before installing software, configuring wallets, or touching real ANT on a public network. + +## Path Selector + +| Path | Choose it when the user wants to... | Fetch first when details matter | +|------|-------------------------------------|---------------------------------| +| SDK | Build an application in Python, JavaScript, TypeScript, Rust, Go, Java, C#, Kotlin, Swift, Ruby, PHP, C++, Dart, or Zig through a local daemon | language page plus REST or gRPC reference | +| CLI | Work from the shell, script uploads or downloads, inspect wallets, or do operational workflows | CLI command reference | +| Direct Rust | Build daemon-free Rust with direct network control or local devnet helpers | Rust getting-started page plus library reference | +| MCP | Let an MCP-compatible client talk to Autonomi through `antd` | MCP setup page plus MCP server reference | + +If the user has not chosen a path, recommend SDK first. It is the best fit for most application work. + +## Fast Lookup Discipline + +Use this workflow to stay fast without guessing: + +1. Decide whether the feature is read-only or upload-enabled. +2. Pick a path. +3. Check the local prerequisite for that path. +4. Fetch one live page for the path-specific details. +5. Reuse that page for the rest of the task instead of re-fetching several pages. + +For SDK and MCP work, the fastest first check is usually: + +```bash +curl http://localhost:8082/health +``` + +Expected shape: + +```json +{ + "status": "ok", + "network": "default" +} +``` + +If the user is on a non-default host or port, ask for the base URL instead of assuming `localhost:8082`. + +## Path Playbooks + +### SDK + +Choose SDK when the user wants normal application development in a supported language. This path goes through `antd`. + +Current daemon defaults: + +- REST: `http://localhost:8082` +- gRPC: `localhost:50051` +- non-default ports can be discovered through the `daemon.port` file written by `antd` + +Current shared daemon surfaces you can rely on at this commit: + +- `GET /health` +- `POST /v1/data/public` +- `GET /v1/data/public/{addr}` +- `POST /v1/data/private` +- `GET /v1/data/private` +- `POST /v1/data/cost` +- `GET /v1/wallet/address` +- `GET /v1/wallet/balance` +- `POST /v1/wallet/approve` +- `POST /v1/data/prepare` +- `POST /v1/upload/prepare` +- `POST /v1/upload/finalize` + +Golden public-data round trip: + +```bash +DATA_B64=$(printf 'Hello, Autonomi!' | base64) + +curl -X POST http://localhost:8082/v1/data/public \ + -H "Content-Type: application/json" \ + -d "{\"data\":\"$DATA_B64\"}" + +curl http://localhost:8082/v1/data/public/
+``` + +Keep these rules straight: + +- REST binary payloads are base64 inside JSON. +- `POST /v1/data/public` returns a public address. +- `POST /v1/data/private` returns a serialized `DataMap`. +- `GET /v1/data/private` needs the `data_map` query parameter. +- read-only daemon work does not require `AUTONOMI_WALLET_KEY` + +Current documented binding entry points: + +- Python: `AntdClient()` or `AsyncAntdClient()` +- JavaScript and TypeScript: `createClient()` +- Go: `NewClient(...)` +- Rust SDK: `Client::new(...)` + +Before writing SDK code beyond health checks and the public-data round trip, fetch the binding page for the user's language. + +### CLI + +Choose CLI when the user wants direct shell workflows, scripts, CI automation, wallet inspection, or quick operational tasks without `antd` in the data path. + +Current CLI rules that matter in practice: + +- data commands do not require the daemon +- root flags such as `--bootstrap`, `--devnet-manifest`, `--allow-loopback`, and `--evm-network` come before the subcommand +- the main top-level groups are `file`, `chunk`, `wallet`, `node`, and `update` +- uploads and wallet commands require `SECRET_KEY` + +Golden public-file flow on a local devnet: + +```bash +SECRET_KEY=0x... ant \ + --devnet-manifest /tmp/devnet.json \ + --allow-loopback \ + --evm-network local \ + file upload photo.jpg --public + +ant \ + --devnet-manifest /tmp/devnet.json \ + --allow-loopback \ + --evm-network local \ + file download
-o photo_copy.jpg +``` + +Keep these rules straight: + +- private file uploads save a local `.datamap` file instead of returning a public address +- private file downloads use `--datamap ` +- public downloads do not need a wallet + +For anything beyond these patterns, fetch the CLI command reference first. + +### Direct Rust + +Choose Direct Rust when the user wants daemon-free Rust, native Rust types, direct client control, or built-in local devnet helpers. + +Current `ant-core` surfaces you can name safely: + +- `Client::connect(...)` +- `with_wallet(...)` +- `data_upload(...)` +- `data_download(...)` +- `file_upload(...)` +- `file_download(...)` +- `data_map_store(...)` +- `data_map_fetch(...)` +- `LocalDevnet::start_minimal()` +- `create_funded_client()` +- `write_manifest(...)` + +Use Direct Rust when the user needs those native surfaces. Do not infer full method signatures or argument shapes from memory; fetch the Rust getting-started page and the library reference before writing the code. + +### MCP + +Choose MCP when an MCP-compatible client should use Autonomi through structured tools instead of raw HTTP. + +Current MCP setup facts: + +- server command: `antd-mcp` +- install pattern: + +```bash +pip install "antd[rest]" +pip install -e antd-mcp/ +``` + +- stdio mode: `antd-mcp` +- SSE mode: `antd-mcp --sse` +- daemon discovery order: + - `ANTD_BASE_URL` + - `daemon.port` + - `http://127.0.0.1:8082` + +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 + +### Public vs private data + +Autonomi has one underlying storage primitive: encrypted chunks. Public and private data differ mainly in where the `DataMap` lives. + +- public data returns an address that can be shared and fetched later +- private data returns a `DataMap` that the caller must keep +- if private retrieval is failing, check for a missing or wrong `DataMap` before anything else + +### Wallet keys vs retrieval material + +These are different things: + +- `AUTONOMI_WALLET_KEY` pays for uploads through `antd` +- `SECRET_KEY` pays for uploads and wallet commands through `ant` +- an attached `Wallet` pays for uploads through `ant-core` +- a public address retrieves public data +- a `DataMap` retrieves private data + +Do not collapse those concepts into one key-handling model. + +### Read-only vs upload-enabled features + +This is the first architectural split to make. + +If the feature is read-only: + +- no ANT is required +- no gas is required +- no wallet is required +- the daemon can run without `AUTONOMI_WALLET_KEY` + +If the feature uploads data: + +- local devnet gives you funded local test wallets +- public networks need ANT plus gas on the selected EVM network +- wallet setup becomes part of the feature, not an afterthought + +### Local devnet first + +For upload-enabled work, the shortest safe loop is: + +```bash +ant dev start --ant-node-dir ../ant-node +ant dev status +ant dev wallet show +curl http://localhost:8082/health +``` + +The local environment gives you a running devnet, `antd --network local`, and a funded local wallet. Stop it with: + +```bash +ant dev stop +``` + +### Payment modes + +Current upload payment modes are: + +- `auto` +- `merkle` +- `single` + +Use `auto` unless the user has a reason to force the behavior. If the user wants explicit cost estimation before an upload, use the current cost endpoints or the path-specific reference page. + +## Common Failures + +### Daemon health check fails + +The daemon is not running, it is on a different port, or the task should be using CLI or Direct Rust instead of SDK or MCP. + +### `503` on daemon write routes + +`antd` is reachable but wallet configuration is missing. Check `AUTONOMI_WALLET_KEY` or switch to an external-signer flow. + +### `insufficient funds` + +Distinguish between missing ANT and missing gas. Do not tell the user to fund the wallet without identifying which balance is missing. + +### Private retrieval fails + +Check the `DataMap` first. Private content still needs the retrieval metadata even after the content has already been paid for. + +### CLI command shape looks wrong + +Check whether the root flags were placed after the subcommand. In `ant`, global flags belong before `file`, `chunk`, `wallet`, `node`, or `update`. + +### Tests fail against the daemon surface + +Check whether the test expects raw bytes over REST. Current REST binary payloads are JSON with base64 in the `data` field. + +## Hard Constraints + +- Do not reference Autonomi 1.0 as if it were current. +- Do not reference `ant-quic`; Autonomi 2.0 transport docs use `saorsa-transport`. +- 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. +- Stay on one Autonomi path unless the user explicitly asks for a comparison. + +## Live References + +Use these pages as the first lookup for current details: + +| Need | Live page | +|------|-----------| +| Overview | `https://docs.autonomi.com/developers` | +| SDK entry point | `https://docs.autonomi.com/developers/sdk/install` | +| SDK first upload | `https://docs.autonomi.com/developers/sdk/store-data-on-the-network` | +| SDK first retrieval | `https://docs.autonomi.com/developers/sdk/retrieve-data-from-the-network` | +| SDK store and retrieve guide | `https://docs.autonomi.com/developers/sdk/how-to-guides/store-and-retrieve-data` | +| SDK daemon as service | `https://docs.autonomi.com/developers/sdk/how-to-guides/use-the-daemon-as-a-local-service` | +| REST API | `https://docs.autonomi.com/developers/sdk/reference/rest-api` | +| gRPC services | `https://docs.autonomi.com/developers/sdk/reference/grpc-services` | +| Daemon command reference | `https://docs.autonomi.com/developers/sdk/reference/daemon-command-reference` | +| Language bindings overview | `https://docs.autonomi.com/developers/sdk/reference/language-bindings/overview` | +| Python SDK | `https://docs.autonomi.com/developers/sdk/reference/language-bindings/python` | +| JavaScript SDK | `https://docs.autonomi.com/developers/sdk/reference/language-bindings/javascript` | +| TypeScript SDK | `https://docs.autonomi.com/developers/sdk/reference/language-bindings/typescript` | +| Rust SDK | `https://docs.autonomi.com/developers/sdk/reference/language-bindings/rust` | +| Go SDK | `https://docs.autonomi.com/developers/sdk/reference/language-bindings/go` | +| CLI quickstart | `https://docs.autonomi.com/developers/cli/use-the-cli` | +| CLI command reference | `https://docs.autonomi.com/developers/cli/command-reference` | +| Direct Rust quickstart | `https://docs.autonomi.com/developers/rust/build-directly-in-rust` | +| Rust library reference | `https://docs.autonomi.com/developers/rust/library-reference` | +| MCP setup | `https://docs.autonomi.com/developers/mcp/use-the-autonomi-mcp-server` | +| MCP reference | `https://docs.autonomi.com/developers/mcp/mcp-server-reference` | +| Local devnet | `https://docs.autonomi.com/developers/guides/set-up-a-local-network` | +| Prepare a wallet | `https://docs.autonomi.com/developers/guides/prepare-a-wallet-for-uploads` | +| Payments and cost estimation | `https://docs.autonomi.com/developers/guides/estimate-costs-and-handle-upload-payments` | +| Read-only features | `https://docs.autonomi.com/developers/guides/build-read-only-features` | +| Testing | `https://docs.autonomi.com/developers/guides/test-your-application` | +| Deploy to mainnet | `https://docs.autonomi.com/developers/guides/deploy-to-mainnet` | +| Data types | `https://docs.autonomi.com/developers/core-concepts/data-types` | +| Keys, addresses, and DataMaps | `https://docs.autonomi.com/developers/core-concepts/keys-addresses-and-datamaps` | +| Self-encryption | `https://docs.autonomi.com/developers/core-concepts/self-encryption` | +| Payment model | `https://docs.autonomi.com/developers/core-concepts/payment-model` | +| System overview | `https://docs.autonomi.com/developers/architecture/system-overview` | +| Glossary | `https://docs.autonomi.com/developers/reference/glossary` | +| Source repositories | `https://docs.autonomi.com/developers/reference/source-repositories` | + +## If Something Conflicts + +Trust the live docs over stale memory. If the live docs and this skill disagree, tell the user the skill may be stale, use the live docs for the task in front of you, and update the skill package in this repo afterward. diff --git a/skills/autonomi-developer/version.json b/skills/autonomi-developer/version.json new file mode 100644 index 0000000..748b55a --- /dev/null +++ b/skills/autonomi-developer/version.json @@ -0,0 +1,24 @@ +{ + "skill": "autonomi-developer", + "version": "0.1.0-draft", + "published_date": "2026-04-22", + "status": "draft", + "canonical_skill_url": "https://raw.githubusercontent.com/WithAutonomi/autonomi-developer-docs/main/skills/autonomi-developer/SKILL.md", + "canonical_docs_url": "https://docs.autonomi.com/developers", + "repository": "https://github.com/WithAutonomi/autonomi-developer-docs", + "verification_mode": "current-merged-truth", + "verified_commits": { + "ant-sdk": "2ed9b14bda42fbdc604a173cc1af27be0964908f", + "ant-client": "b0c501a163c1a95bdbfc703892b88a8a91f7e482", + "ant-node": "5a5d7d4fed766cd56d0f97f337fcd5ff049bea6a", + "self_encryption": "5f9d1646231da7ca2ce60e84d010acfb6d9c29d0", + "evmlib": "82f2fccff243b48de0e04ceb71ccb2aa17d810af" + }, + "covers_paths": [ + "sdk", + "cli", + "direct-rust", + "mcp" + ], + "notes": "Initial in-repo operational draft. Re-verify before promoting to a non-draft version." +} From b3d8abc2c0f0a92da29695c40ba4039b7c4ba9a5 Mon Sep 17 00:00:00 2001 From: Jim Collinson Date: Wed, 29 Apr 2026 15:32:39 +0100 Subject: [PATCH 2/2] Refresh upstream repo coverage and reverify docs --- component-registry.yml | 114 +++++++++++++++++- docs/architecture/system-overview.md | 36 ++++-- docs/cli-reference/command-reference.md | 9 +- docs/cli-reference/overview.md | 15 ++- docs/core-concepts/data-types.md | 15 ++- docs/core-concepts/payment-model.md | 25 ++-- docs/core-concepts/self-encryption.md | 14 ++- .../getting-started/build-directly-in-rust.md | 4 +- docs/getting-started/hello-world.md | 4 +- docs/getting-started/install.md | 4 +- docs/getting-started/introduction.md | 29 +++++ docs/getting-started/using-ant-client.md | 4 +- .../using-the-autonomi-daemon.md | 8 +- docs/github.md | 36 +++--- docs/glossary.md | 42 +++++-- .../build-a-read-only-application.md | 12 +- docs/how-to-guides/deploy-to-mainnet.md | 15 ++- docs/how-to-guides/manage-keys.md | 20 +-- docs/how-to-guides/run-as-daemon.md | 10 +- docs/how-to-guides/setup-local-network.md | 8 +- docs/how-to-guides/test-your-application.md | 12 +- docs/how-to-guides/use-external-signers.md | 43 +++++-- docs/how-to-guides/use-the-mcp-server.md | 4 +- docs/index.md | 39 +++++- docs/rust-reference/overview.md | 8 +- docs/sdk-reference/daemon-cli.md | 7 +- docs/sdk-reference/mcp-server.md | 18 ++- docs/sdk-reference/overview.md | 6 +- docs/sdk-reference/rest-api.md | 18 ++- repo-registry.yml | 30 +++-- 30 files changed, 438 insertions(+), 171 deletions(-) diff --git a/component-registry.yml b/component-registry.yml index 0a086a9..7d7f370 100644 --- a/component-registry.yml +++ b/component-registry.yml @@ -17,10 +17,37 @@ components: - grpc - install feeds_pages: + - index.md + - getting-started/introduction.md - getting-started/install.md + - getting-started/using-the-autonomi-daemon.md + - getting-started/hello-world.md - sdk-reference/overview.md - sdk-reference/rest-api.md - sdk-reference/daemon-cli.md + - how-to-guides/run-as-daemon.md + - how-to-guides/store-and-retrieve-data.md + - how-to-guides/handle-payments.md + - how-to-guides/manage-keys.md + - how-to-guides/build-a-read-only-application.md + - how-to-guides/use-external-signers.md + - how-to-guides/deploy-to-mainnet.md + feeds_skills: + - skills/autonomi-developer/SKILL.md + + ant-dev: + repo: ant-sdk + kind: python-package + path: ant-dev/ + topics: + - devnet + - local-network + - testing + feeds_pages: + - getting-started/using-the-autonomi-daemon.md + - sdk-reference/overview.md + - how-to-guides/setup-local-network.md + - how-to-guides/test-your-application.md feeds_skills: - skills/autonomi-developer/SKILL.md @@ -35,6 +62,20 @@ components: feeds_skills: - skills/autonomi-developer/SKILL.md + antd-mcp: + repo: ant-sdk + kind: python-package + path: antd-mcp/ + topics: + - mcp + - agent-tools + feeds_pages: + - sdk-reference/overview.md + - sdk-reference/mcp-server.md + - how-to-guides/use-the-mcp-server.md + feeds_skills: + - skills/autonomi-developer/SKILL.md + proto: repo: ant-sdk kind: grpc-spec @@ -53,6 +94,8 @@ components: topics: - rust-binding feeds_pages: + - rust-reference/overview.md + - sdk-reference/language-bindings/overview.md - sdk-reference/language-bindings/rust.md feeds_skills: - skills/autonomi-developer/SKILL.md @@ -64,6 +107,7 @@ components: topics: - python-binding feeds_pages: + - sdk-reference/language-bindings/overview.md - sdk-reference/language-bindings/python.md feeds_skills: - skills/autonomi-developer/SKILL.md @@ -75,7 +119,9 @@ components: topics: - javascript-binding feeds_pages: + - sdk-reference/language-bindings/overview.md - sdk-reference/language-bindings/javascript.md + - sdk-reference/language-bindings/typescript.md feeds_skills: - skills/autonomi-developer/SKILL.md @@ -86,6 +132,7 @@ components: topics: - go-binding feeds_pages: + - sdk-reference/language-bindings/overview.md - sdk-reference/language-bindings/go.md feeds_skills: - skills/autonomi-developer/SKILL.md @@ -201,10 +248,19 @@ components: - payments - devnet feeds_pages: + - index.md + - getting-started/introduction.md + - getting-started/build-directly-in-rust.md - core-concepts/data-types.md - - how-to-guides/store-and-retrieve-data.md - - how-to-guides/handle-payments.md + - core-concepts/overview.md + - core-concepts/keys-addresses-and-datamaps.md + - how-to-guides/build-a-read-only-application.md + - how-to-guides/use-external-signers.md + - how-to-guides/test-your-application.md - cli-reference/ant-core-library.md + - rust-reference/overview.md + - github.md + - glossary.md feeds_skills: - skills/autonomi-developer/SKILL.md @@ -216,9 +272,16 @@ components: - cli - node-management feeds_pages: + - index.md + - getting-started/introduction.md - cli-reference/overview.md - cli-reference/command-reference.md - getting-started/using-ant-client.md + - how-to-guides/manage-keys.md + - how-to-guides/build-a-read-only-application.md + - how-to-guides/deploy-to-mainnet.md + - github.md + - glossary.md feeds_skills: - skills/autonomi-developer/SKILL.md @@ -233,9 +296,14 @@ components: - local-network - payment-model feeds_pages: + - architecture/system-overview.md - core-concepts/payment-model.md + - getting-started/using-the-autonomi-daemon.md - how-to-guides/setup-local-network.md - how-to-guides/embed-a-node.md + - how-to-guides/test-your-application.md + - github.md + - glossary.md feeds_skills: - skills/autonomi-developer/SKILL.md @@ -247,6 +315,7 @@ components: - devnet-launcher feeds_pages: - how-to-guides/setup-local-network.md + - how-to-guides/test-your-application.md feeds_skills: - skills/autonomi-developer/SKILL.md @@ -262,8 +331,9 @@ components: - trust - architecture feeds_pages: - - core-concepts/overview.md - architecture/system-overview.md + - github.md + - glossary.md saorsa-transport: repo: saorsa-transport @@ -273,7 +343,10 @@ components: - transport - nat-traversal feeds_pages: + - core-concepts/post-quantum-cryptography.md - architecture/system-overview.md + - github.md + - glossary.md saorsa-pqc: repo: saorsa-pqc @@ -284,7 +357,25 @@ components: - key-derivation feeds_pages: - core-concepts/post-quantum-cryptography.md - - core-concepts/key-derivation.md + - core-concepts/overview.md + - architecture/system-overview.md + - github.md + - glossary.md + + ant-protocol: + repo: ant-protocol + kind: rust-crate + path: src/ + topics: + - protocol + - content-addressing + - payment-proof + - devnet-manifest + feeds_pages: + - architecture/system-overview.md + - core-concepts/self-encryption.md + - core-concepts/payment-model.md + - github.md self_encryption: repo: self_encryption @@ -296,6 +387,11 @@ components: feeds_pages: - core-concepts/self-encryption.md - core-concepts/data-types.md + - core-concepts/overview.md + - core-concepts/keys-addresses-and-datamaps.md + - architecture/system-overview.md + - github.md + - glossary.md feeds_skills: - skills/autonomi-developer/SKILL.md @@ -310,6 +406,8 @@ components: - core-concepts/payment-model.md - how-to-guides/handle-payments.md - how-to-guides/manage-keys.md + - how-to-guides/use-external-signers.md + - how-to-guides/deploy-to-mainnet.md feeds_skills: - skills/autonomi-developer/SKILL.md @@ -323,6 +421,7 @@ components: - merkle-payment-flows feeds_pages: - how-to-guides/handle-payments.md + - how-to-guides/use-external-signers.md # === Specialist === @@ -333,5 +432,8 @@ components: topics: - release-signing - key-management - feeds_pages: [] - notes: "Only feeds pages if key management docs are created." + feeds_pages: + - core-concepts/post-quantum-cryptography.md + - github.md + - glossary.md + notes: "Feeds release-signing and key-management pages, plus repo overview pages that reference the tool." diff --git a/docs/architecture/system-overview.md b/docs/architecture/system-overview.md index fa3f95a..3f02d3d 100644 --- a/docs/architecture/system-overview.md +++ b/docs/architecture/system-overview.md @@ -3,50 +3,57 @@ + @@ -89,6 +96,8 @@ These interfaces target the same network, but one uses a local daemon and the ot The `ant-node` crate is a thin wrapper around `saorsa-core::P2PNode`. It adds configuration, chunk storage, payment verification, replication, upgrade handling, and node runtime management on top of the core P2P layer. +`ant-core` and `ant-node` also share wire-message types, payment-proof types, and devnet manifest types through `ant-protocol`. + In the repos used for this page, `ant-node` documents chunk storage as its active network data type. ## Routing and transport @@ -111,6 +120,7 @@ On the client side, `self_encryption` turns uploaded content into a `DataMap` pl - [ant-sdk](https://github.com/WithAutonomi/ant-sdk) - [ant-client](https://github.com/WithAutonomi/ant-client) - [ant-node](https://github.com/WithAutonomi/ant-node) +- [ant-protocol](https://github.com/WithAutonomi/ant-protocol) - [self_encryption](https://github.com/WithAutonomi/self_encryption) - [saorsa-core](https://github.com/saorsa-labs/saorsa-core) - [saorsa-transport](https://github.com/saorsa-labs/saorsa-transport) diff --git a/docs/cli-reference/command-reference.md b/docs/cli-reference/command-reference.md index 529406f..2d3c61b 100644 --- a/docs/cli-reference/command-reference.md +++ b/docs/cli-reference/command-reference.md @@ -3,8 +3,8 @@ @@ -28,9 +28,8 @@ Root flags must appear before the subcommand. | `-b, --bootstrap ` | socket list | No | Bootstrap peers for data operations | | `--devnet-manifest ` | path | No | Local devnet manifest JSON | | `--allow-loopback` | boolean | No | Allow loopback connections for local testing | -| `--timeout-secs ` | integer | No | Network timeout in seconds, default `60` | -| `--chunk-concurrency ` | integer | No | Upload chunk concurrency override | -| `--log-level ` | string | No | `trace`, `debug`, `info`, `warn`, `error` | +| `--ipv4-only` | boolean | No | Disable dual-stack and force IPv4-only mode | +| `-v, --verbose` | count | No | Increase verbosity: `-v` info, `-vv` debug, `-vvv` trace | | `--evm-network ` | string | No | `arbitrum-one`, `arbitrum-sepolia`, or `local` | **Environment:** diff --git a/docs/cli-reference/overview.md b/docs/cli-reference/overview.md index c09f2d8..1574740 100644 --- a/docs/cli-reference/overview.md +++ b/docs/cli-reference/overview.md @@ -1,5 +1,13 @@ # CLI Overview + + `ant` is the command-line interface for Autonomi. It gives you direct shell access to uploads, downloads, wallet inspection, self-update, chunk operations, and node-management workflows without running the SDK daemon. ## When to use the CLI @@ -7,7 +15,7 @@ Use the CLI when you want: * Direct CLI access for file, chunk, wallet, or node-management workflows -* Direct control over bootstrap peers, devnet manifests, and EVM network selection +* Direct control over bootstrap peers, devnet manifests, IPv4-only mode, and EVM network selection * Shell-first automation or operational workflows If you want SDK ergonomics in other languages, use the SDKs instead. If you want daemon-free programmatic Rust access, see [Developing in Rust](../rust-reference/overview.md). @@ -29,9 +37,8 @@ It also accepts global flags such as: * `--bootstrap` * `--devnet-manifest` * `--allow-loopback` -* `--timeout-secs` -* `--chunk-concurrency` -* `--log-level` +* `--ipv4-only` +* `-v`, `--verbose` * `--evm-network` ## Installation diff --git a/docs/core-concepts/data-types.md b/docs/core-concepts/data-types.md index 1bf9cc5..bea4206 100644 --- a/docs/core-concepts/data-types.md +++ b/docs/core-concepts/data-types.md @@ -3,15 +3,22 @@ + diff --git a/docs/core-concepts/payment-model.md b/docs/core-concepts/payment-model.md index 63f4424..feac01e 100644 --- a/docs/core-concepts/payment-model.md +++ b/docs/core-concepts/payment-model.md @@ -3,29 +3,36 @@ + @@ -67,7 +74,7 @@ The daemon-side external-signer flow also exposes the RPC URL and payment contra The `antd` surface exposes cost estimation explicitly: - `POST /v1/data/cost` -- `POST /v1/cost/file` +- `POST /v1/files/cost` Those endpoints return the estimated upload cost as a string amount in atto tokens. diff --git a/docs/core-concepts/self-encryption.md b/docs/core-concepts/self-encryption.md index 0d3f3c4..94a9e69 100644 --- a/docs/core-concepts/self-encryption.md +++ b/docs/core-concepts/self-encryption.md @@ -4,7 +4,14 @@ source_repo: self_encryption source_ref: master source_commit: 5f9d1646231da7ca2ce60e84d010acfb6d9c29d0 - verified_date: 2026-04-02 + verified_date: 2026-04-29 + verification_mode: current-merged-truth +--> + @@ -30,10 +37,10 @@ The implementation uses: Chunk addresses are derived from the encrypted content. That is why the higher-level storage model is content-addressed: if the content changes, the resulting encrypted chunks and their addresses change too. -Important limits from the crate itself: +Important current limits from the active sources: - `MIN_ENCRYPTABLE_BYTES` is `3` -- `MAX_CHUNK_SIZE` is `4_190_208` bytes +- `MAX_CHUNK_SIZE` is `4_190_208` bytes for network chunk payloads The crate stores chunk metadata in a `DataMap`, and the `DataMap` can be shrunk recursively when it grows beyond the immediate chunk set. In the higher-level SDK and CLI workflows, that `DataMap` is what turns a set of encrypted chunks back into retrievable content. @@ -59,6 +66,7 @@ The crate does not store anything on the network for you. Persisting the encrypt ## Upstream sources - [self_encryption](https://github.com/WithAutonomi/self_encryption) +- [ant-protocol](https://github.com/WithAutonomi/ant-protocol) ## Related pages diff --git a/docs/getting-started/build-directly-in-rust.md b/docs/getting-started/build-directly-in-rust.md index 99aa5cb..e138978 100644 --- a/docs/getting-started/build-directly-in-rust.md +++ b/docs/getting-started/build-directly-in-rust.md @@ -3,8 +3,8 @@ diff --git a/docs/getting-started/hello-world.md b/docs/getting-started/hello-world.md index 39880ca..f026b4c 100644 --- a/docs/getting-started/hello-world.md +++ b/docs/getting-started/hello-world.md @@ -3,8 +3,8 @@ diff --git a/docs/getting-started/install.md b/docs/getting-started/install.md index 186552d..6348902 100644 --- a/docs/getting-started/install.md +++ b/docs/getting-started/install.md @@ -3,8 +3,8 @@ diff --git a/docs/getting-started/introduction.md b/docs/getting-started/introduction.md index abb880d..7836bdc 100644 --- a/docs/getting-started/introduction.md +++ b/docs/getting-started/introduction.md @@ -1,5 +1,34 @@ # What is Autonomi? + + + + + Autonomi is a decentralized peer-to-peer network for permanent, immutable data storage. Data is encrypted before upload, stored using content-addressing, and paid for once when you write it to the network. ## What makes Autonomi different diff --git a/docs/getting-started/using-ant-client.md b/docs/getting-started/using-ant-client.md index 88f2ba8..80bd1a8 100644 --- a/docs/getting-started/using-ant-client.md +++ b/docs/getting-started/using-ant-client.md @@ -3,8 +3,8 @@ diff --git a/docs/getting-started/using-the-autonomi-daemon.md b/docs/getting-started/using-the-autonomi-daemon.md index e42f86f..caf36bb 100644 --- a/docs/getting-started/using-the-autonomi-daemon.md +++ b/docs/getting-started/using-the-autonomi-daemon.md @@ -3,15 +3,15 @@ diff --git a/docs/github.md b/docs/github.md index 9891262..07505f9 100644 --- a/docs/github.md +++ b/docs/github.md @@ -3,57 +3,64 @@ + @@ -65,6 +72,7 @@ This documentation is assembled from several upstream GitHub repositories. If yo - [`ant-sdk`](https://github.com/WithAutonomi/ant-sdk) — `antd`, language SDKs, local dev tooling, and `antd-mcp` - [`ant-client`](https://github.com/WithAutonomi/ant-client) — Direct CLI and native Rust path: `ant`, `ant-core`, and local devnet tooling - [`ant-node`](https://github.com/WithAutonomi/ant-node) — Node runtime, chunk storage, payment verification, and replication behavior +- [`ant-protocol`](https://github.com/WithAutonomi/ant-protocol) — Shared wire protocol crate for chunk messages, payment proofs, and devnet manifests - [`self_encryption`](https://github.com/WithAutonomi/self_encryption) — Client-side self-encryption crate used for content processing before network storage - [`ant-keygen`](https://github.com/WithAutonomi/ant-keygen) — ML-DSA-65 release-signing utility diff --git a/docs/glossary.md b/docs/glossary.md index a767eff..d70c259 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -3,50 +3,64 @@ + + @@ -60,6 +74,8 @@ Canonical terms used throughout this docs set. **ant-keygen** — ML-DSA-65 release-signing utility. +**ant-protocol** — Shared wire protocol crate used by `ant-core` and `ant-node` for chunk messages, payment proofs, and devnet manifests. + **ant-sdk** — Daemon-based developer interface built around `antd`, REST/gRPC APIs, and language SDKs. **antd** — Local daemon that exposes REST on `http://localhost:8082` and gRPC on `localhost:50051` by default. diff --git a/docs/how-to-guides/build-a-read-only-application.md b/docs/how-to-guides/build-a-read-only-application.md index 24db615..c6999e8 100644 --- a/docs/how-to-guides/build-a-read-only-application.md +++ b/docs/how-to-guides/build-a-read-only-application.md @@ -3,15 +3,15 @@ @@ -84,8 +84,8 @@ The private retrieval response is JSON with the content returned as base64 in th For the CLI route, 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/how-to-guides/deploy-to-mainnet.md b/docs/how-to-guides/deploy-to-mainnet.md index e603c47..9d4063c 100644 --- a/docs/how-to-guides/deploy-to-mainnet.md +++ b/docs/how-to-guides/deploy-to-mainnet.md @@ -3,15 +3,15 @@ @@ -33,7 +33,7 @@ For daemon-based deployments, provide wallet and EVM settings through the enviro export AUTONOMI_WALLET_KEY="" export EVM_RPC_URL="https://your-rpc-endpoint" export EVM_PAYMENT_TOKEN_ADDRESS="0x..." -export EVM_DATA_PAYMENTS_ADDRESS="0x..." +export EVM_PAYMENT_VAULT_ADDRESS="0x..." ``` For direct-network CLI deployments, provide: @@ -77,9 +77,8 @@ curl -X POST http://127.0.0.1:8082/v1/data/public \ The `ant` CLI expects bootstrap peers and an EVM network setting for mainnet-style writes: ```bash -SECRET_KEY=0x... ant file upload photo.jpg \ - --bootstrap 1.2.3.4:12000 \ - --evm-network arbitrum-one +SECRET_KEY=0x... ant --bootstrap 1.2.3.4:12000 --evm-network arbitrum-one \ + file upload photo.jpg ``` If you use the private mode, the CLI saves a local `.datamap` file and uses that for later download. diff --git a/docs/how-to-guides/manage-keys.md b/docs/how-to-guides/manage-keys.md index 478645b..0e0676c 100644 --- a/docs/how-to-guides/manage-keys.md +++ b/docs/how-to-guides/manage-keys.md @@ -3,15 +3,22 @@ + @@ -97,13 +104,10 @@ If you do not want `antd` to hold a wallet key, run it without `AUTONOMI_WALLET_ ```bash EVM_RPC_URL=https://your-rpc-endpoint \ EVM_PAYMENT_TOKEN_ADDRESS=0x... \ -EVM_DATA_PAYMENTS_ADDRESS=0x... \ -EVM_MERKLE_PAYMENTS_ADDRESS=0x... \ +EVM_PAYMENT_VAULT_ADDRESS=0x... \ ./target/release/antd ``` -Include `EVM_MERKLE_PAYMENTS_ADDRESS` when you want Merkle batch payment support in this configuration. - That keeps signing outside the daemon and pushes transaction submission into your wallet or signer integration. ## Verify it worked diff --git a/docs/how-to-guides/run-as-daemon.md b/docs/how-to-guides/run-as-daemon.md index fbab64a..a5c643c 100644 --- a/docs/how-to-guides/run-as-daemon.md +++ b/docs/how-to-guides/run-as-daemon.md @@ -1,5 +1,13 @@ # Use the Daemon as a Local Service + + Run the Autonomi Daemon, `antd`, as a long-lived local service when you want one stable Autonomi gateway that multiple applications, scripts, or background processes can share. Use this setup if you want: @@ -26,7 +34,7 @@ Create `/etc/antd.env`: AUTONOMI_WALLET_KEY= EVM_RPC_URL=https://your-rpc-endpoint EVM_PAYMENT_TOKEN_ADDRESS=0x... -EVM_DATA_PAYMENTS_ADDRESS=0x... +EVM_PAYMENT_VAULT_ADDRESS=0x... ``` You only need the wallet and EVM settings if this daemon will perform paid writes. diff --git a/docs/how-to-guides/setup-local-network.md b/docs/how-to-guides/setup-local-network.md index 0069393..9bd2d07 100644 --- a/docs/how-to-guides/setup-local-network.md +++ b/docs/how-to-guides/setup-local-network.md @@ -3,15 +3,15 @@ diff --git a/docs/how-to-guides/test-your-application.md b/docs/how-to-guides/test-your-application.md index da63c47..c6fc9bb 100644 --- a/docs/how-to-guides/test-your-application.md +++ b/docs/how-to-guides/test-your-application.md @@ -3,22 +3,22 @@ diff --git a/docs/how-to-guides/use-external-signers.md b/docs/how-to-guides/use-external-signers.md index a0ed48c..f7df557 100644 --- a/docs/how-to-guides/use-external-signers.md +++ b/docs/how-to-guides/use-external-signers.md @@ -3,22 +3,29 @@ + @@ -45,17 +52,16 @@ The daemon does not have an `--external-signer` flag. External-signer mode is th ```bash EVM_RPC_URL=https://your-rpc-endpoint \ EVM_PAYMENT_TOKEN_ADDRESS=0x... \ -EVM_DATA_PAYMENTS_ADDRESS=0x... \ -EVM_MERKLE_PAYMENTS_ADDRESS=0x... \ +EVM_PAYMENT_VAULT_ADDRESS=0x... \ ./target/release/antd ``` -Include `EVM_MERKLE_PAYMENTS_ADDRESS` when you want Merkle batch payment support in the external-signer flow. - ### 2. Prepare the upload For in-memory data, call `POST /v1/data/prepare`. +The prepare response includes `payment_type` so your signer knows whether to submit a `wave_batch` payment or a `merkle` payment. + ```bash DATA_B64=$(printf 'Hello, Autonomi!' | base64) @@ -69,6 +75,7 @@ Expected response shape: ```json { "upload_id": "", + "payment_type": "wave_batch", "payments": [ { "quote_hash": "0x...", @@ -77,7 +84,7 @@ Expected response shape: } ], "total_amount": "", - "data_payments_address": "0x...", + "payment_vault_address": "0x...", "payment_token_address": "0x...", "rpc_url": "https://your-rpc-endpoint" } @@ -89,7 +96,11 @@ For file uploads, the equivalent is `POST /v1/upload/prepare` with a local `path Use your signer stack to submit the EVM payment transactions described by the prepare response. -`antd` does not sign or broadcast those transactions in this flow. Your signer must return the resulting transaction hashes keyed by the quoted payment entries. +For `wave_batch`, submit the quoted payments and capture the resulting transaction hashes. + +For `merkle`, submit the Merkle payment call and capture the `winner_pool_hash` from the `MerklePaymentMade` event. + +`antd` does not sign or broadcast those transactions in this flow. Your signer must return either the resulting transaction hashes or the Merkle winner pool hash, depending on `payment_type`. ### 4. Finalize the upload @@ -101,6 +112,14 @@ curl -X POST http://localhost:8082/v1/upload/finalize \ -d '{"upload_id":"","tx_hashes":{"0xquote":"0xtx"},"store_data_map":true}' ``` +For `merkle` uploads, send `winner_pool_hash` instead of `tx_hashes`: + +```bash +curl -X POST http://localhost:8082/v1/upload/finalize \ + -H "Content-Type: application/json" \ + -d '{"upload_id":"","winner_pool_hash":"0x...","store_data_map":true}' +``` + Expected response shape: ```json diff --git a/docs/how-to-guides/use-the-mcp-server.md b/docs/how-to-guides/use-the-mcp-server.md index d615ad3..683d0e0 100644 --- a/docs/how-to-guides/use-the-mcp-server.md +++ b/docs/how-to-guides/use-the-mcp-server.md @@ -3,8 +3,8 @@ diff --git a/docs/index.md b/docs/index.md index ccbcc6a..31b8921 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,7 +1,36 @@ # Introduction -Autonomi is a decentralized peer-to-peer network for permanent, immutable data storage. Data is encrypted before upload, stored using content-addressing, and paid for once at upload.\ -\ + + + + + +Autonomi is a decentralized peer-to-peer network for permanent, immutable data storage. Data is encrypted before upload, stored using content addressing, and paid for once at upload. + These guides will help you get started building with the Autonomi Network! ## How to build on Autonomi @@ -12,15 +41,15 @@ You can build on Autonomi in several ways, from SDKs in more than 15 languages t Use the SDKs if you want the easiest starting point for application development in Python, Node.js / TypeScript, Go, Rust, Java, C#, Kotlin, Swift, Ruby, PHP, Dart, Zig, and other supported languages. -A daemon called `antd` running on the users machine, exposing REST and gRPC endpoints giving your application a stable REST and gRPC interface to the network. +`antd` runs on your machine and exposes REST and gRPC endpoints, giving your application a stable local interface to the network. Start with [Build with the SDKs](getting-started/install.md), then [Using the Autonomi Daemon](getting-started/using-the-autonomi-daemon.md), then [Your First Upload with the SDKs](getting-started/hello-world.md). ### Use the CLI -[Use the ant CLI ](getting-started/using-ant-client.md)when you want direct shell access for uploads, downloads, wallet checks, chunk operations, or node-management workflows. +[Use the ant CLI](getting-started/using-ant-client.md) when you want direct shell access for uploads, downloads, wallet checks, chunk operations, or node-management workflows. -### Build in directly in Rust +### Build directly in Rust Build in Rust without the daemon when you want direct programmatic control over networking, uploads, and payments in your application. diff --git a/docs/rust-reference/overview.md b/docs/rust-reference/overview.md index 45c06b5..bb1db88 100644 --- a/docs/rust-reference/overview.md +++ b/docs/rust-reference/overview.md @@ -3,15 +3,15 @@ diff --git a/docs/sdk-reference/daemon-cli.md b/docs/sdk-reference/daemon-cli.md index 2faa1fa..b26f3fc 100644 --- a/docs/sdk-reference/daemon-cli.md +++ b/docs/sdk-reference/daemon-cli.md @@ -3,8 +3,8 @@ @@ -46,8 +46,7 @@ Runs the local REST and gRPC gateway daemon for Autonomi. | `AUTONOMI_WALLET_KEY` | Direct-wallet private key for paid uploads | | `EVM_RPC_URL` | EVM RPC endpoint | | `EVM_PAYMENT_TOKEN_ADDRESS` | Payment token contract | -| `EVM_DATA_PAYMENTS_ADDRESS` | Data payments contract | -| `EVM_MERKLE_PAYMENTS_ADDRESS` | Optional Merkle payments contract | +| `EVM_PAYMENT_VAULT_ADDRESS` | Payment vault contract | **Examples:** diff --git a/docs/sdk-reference/mcp-server.md b/docs/sdk-reference/mcp-server.md index fb863f8..261edac 100644 --- a/docs/sdk-reference/mcp-server.md +++ b/docs/sdk-reference/mcp-server.md @@ -3,12 +3,12 @@ -Reference for the `antd-mcp` server that exposes the `antd` daemon as MCP tools for AI agents and MCP-compatible clients. +Reference for the `antd-mcp` server that exposes the `antd` daemon as 15 MCP tools for AI agents and MCP-compatible clients. ## Server command @@ -147,19 +147,25 @@ Fetches a raw chunk and returns base64-encoded data. **Tool:** `prepare_upload(path)` -Prepares a file upload for external signing and returns payment details. +Prepares a file upload for external signing and returns payment details plus a `payment_type` discriminator. ### Prepare a Data Upload **Tool:** `prepare_data_upload(data)` -Prepares a data upload for external signing. The input is base64-encoded. +Prepares a data upload for external signing. The input is base64-encoded, and the response includes a `payment_type` discriminator. ### Finalize an Upload **Tool:** `finalize_upload(upload_id, tx_hashes)` -Finalizes an externally-signed upload. +Finalizes an externally-signed wave-batch upload. + +### Finalize a Merkle Upload + +**Tool:** `finalize_merkle_upload(upload_id, winner_pool_hash)` + +Finalizes an externally-signed Merkle upload after the on-chain payment emits `MerklePaymentMade`. ## Payment modes diff --git a/docs/sdk-reference/overview.md b/docs/sdk-reference/overview.md index e670b8d..3c7fc9f 100644 --- a/docs/sdk-reference/overview.md +++ b/docs/sdk-reference/overview.md @@ -3,8 +3,8 @@ @@ -64,7 +64,7 @@ The `antd` REST surface groups into these areas: | Health | `/health` | | Data | `/v1/data/public`, `/v1/data/private`, `/v1/data/cost` | | Chunks | `/v1/chunks` | -| Files and directories | `/v1/files/upload/public`, `/v1/files/download/public`, `/v1/dirs/upload/public`, `/v1/dirs/download/public`, `/v1/cost/file` | +| Files and directories | `/v1/files/upload/public`, `/v1/files/download/public`, `/v1/dirs/upload/public`, `/v1/dirs/download/public`, `/v1/files/cost` | | Wallet | `/v1/wallet/address`, `/v1/wallet/balance`, `/v1/wallet/approve` | | External signer flow | `/v1/data/prepare`, `/v1/upload/prepare`, `/v1/upload/finalize` | diff --git a/docs/sdk-reference/rest-api.md b/docs/sdk-reference/rest-api.md index 7e9e38f..fd030fa 100644 --- a/docs/sdk-reference/rest-api.md +++ b/docs/sdk-reference/rest-api.md @@ -3,8 +3,8 @@ @@ -376,7 +376,7 @@ curl -X POST http://localhost:8082/v1/dirs/download/public \ ### Estimate File Cost -**Endpoint:** `POST /v1/cost/file` +**Endpoint:** `POST /v1/files/cost` Estimates upload cost for a local file. @@ -398,7 +398,7 @@ Estimates upload cost for a local file. **Example:** ```bash -curl -X POST http://localhost:8082/v1/cost/file \ +curl -X POST http://localhost:8082/v1/files/cost \ -H "Content-Type: application/json" \ -d '{"path":"/absolute/path/to/document.pdf","is_public":true}' ``` @@ -489,6 +489,7 @@ Prepares an in-memory data upload for external signing. ```json { "upload_id": "", + "payment_type": "wave_batch", "payments": [ { "quote_hash": "0x...", @@ -497,12 +498,14 @@ Prepares an in-memory data upload for external signing. } ], "total_amount": "", - "data_payments_address": "0x...", + "payment_vault_address": "0x...", "payment_token_address": "0x...", "rpc_url": "http://127.0.0.1:8545" } ``` +For Merkle uploads, the response instead includes `payment_type: "merkle"` plus `depth`, `pool_commitments`, and `merkle_payment_timestamp`. + **Example:** ```bash @@ -546,7 +549,8 @@ Finalizes a prepared upload after the external signer has submitted payment tran | Name | Type | Required | Description | |------|------|----------|-------------| | `upload_id` | string | Yes | Value returned by a prepare endpoint | -| `tx_hashes` | object | Yes | Map of `quote_hash` to `tx_hash` | +| `tx_hashes` | object | No | Map of `quote_hash` to `tx_hash` for `wave_batch` uploads | +| `winner_pool_hash` | string | No | Winner pool hash for `merkle` uploads | | `store_data_map` | boolean | No | If `true`, also stores the DataMap on-network | **Response:** @@ -569,6 +573,8 @@ curl -X POST http://localhost:8082/v1/upload/finalize \ -d '{"upload_id":"","tx_hashes":{"0xquote":"0xtx"},"store_data_map":true}' ``` +For Merkle uploads, send `winner_pool_hash` instead of `tx_hashes`. + ## Error codes | Code | Meaning | Resolution | diff --git a/repo-registry.yml b/repo-registry.yml index 705af36..3465eb9 100644 --- a/repo-registry.yml +++ b/repo-registry.yml @@ -113,8 +113,8 @@ repos: ant-merkle: class: targeted-foundational - org: MaidSafe # moving to WithAutonomi - url: https://github.com/maidsafe/ant-merkle + org: WithAutonomi + url: https://github.com/WithAutonomi/ant-merkle watch_mode: targeted default_for_drafting: false topics: @@ -123,6 +123,21 @@ repos: - merkle-payment-flows on_change: reverify-linked-pages + ant-protocol: + class: targeted-foundational + org: WithAutonomi + url: https://github.com/WithAutonomi/ant-protocol + watch_mode: targeted + default_for_drafting: false + topics: + - protocol + - wire-format + - chunk-messages + - payment-proof + - devnet-manifest + on_change: reverify-linked-pages + notes: "Shared wire-protocol, payment-proof, and devnet-manifest crate consumed by ant-client and ant-node." + # === SPECIALIST === # Only relevant for certain docs areas. Used only for explicitly related pages. @@ -140,17 +155,6 @@ repos: # === WATCHLIST === # Not source-of-truth for new docs. Flag if still referenced. - ant-evm: - class: watchlist - org: WithAutonomi - url: https://github.com/WithAutonomi/ant-evm - watch_mode: issue-only - default_for_drafting: false - topics: - - legacy-payment-references - on_change: flag-if-still-referenced - notes: "Collapsed into evmlib. Watch until all references disappear from merged code." - # === EXCLUDED === # Ignored by default. Do not read, reference, or verify against.