feat(pointer): create, update, read and resolve pointers

CLAUDE.md

@@ -73,6 +73,7 @@ ant-core/src/
 │       ├── payment.rs        # pay_for_storage, approve_token_spend
 │       ├── quote.rs          # get_store_quotes from network peers
 │       ├── merkle.rs         # Merkle batch payment (PaymentMode enum)
+│       ├── pointer.rs        # pointer_create/update/get/resolve (ADR-0016)
 │       └── cache.rs          # In-memory LRU chunk cache
 └── node/                     # Node management
     ├── mod.rs                # add_nodes, remove_node, reset
@@ -108,6 +109,7 @@ ant-cli/src/
     ├── data/
     │   ├── file.rs           # ant file upload/download
     │   ├── chunk.rs          # ant chunk put/get
+    │   ├── pointer.rs        # ant pointer keygen/address/create/update/get/resolve
     │   └── wallet.rs         # ant wallet address/balance
     └── node/
         ├── mod.rs

Cargo.toml

@@ -2,3 +2,8 @@
 members = ["ant-core", "ant-cli"]
 resolver = "2"
 
+[patch.crates-io]
+# The published ant-protocol 3.0.0 has no `Pointer` record or wire messages
+# (ADR-0016). Pin the pointer revision until a release includes it.
+# Versions are bumped at release; this immutable revision remains 3.0.0.
+ant-protocol = { git = "https://github.com/WithAutonomi/ant-protocol", rev = "d11d1010d93958fee6e63e4aace8770f39a0678b" }

README.md

@@ -71,6 +71,15 @@ There is no browser-specific recovery probe or relaxed payment threshold.
 The requested responder count must be satisfied before quote witnessing and
 storage-majority checks proceed.
 
+Pointers work from the browser too: `getPointer`, `resolvePointer`,
+`createPointer` and `updatePointer` on `BrowserNetworkClient`, and
+`pointerAddress(seed)` offline. They run the native client's own read quorum,
+corroboration and write quorum, and pay each state through the same wallet
+callback file uploads take. The owner key is passed as its 32-byte seed. Only
+nodes that advertise `pointer_protocol` are asked. A write can hand the paid
+record and proof to an `onPaid` callback; `storePaidPointer` stores them later
+without paying again.
+
 Browser protocol v5 and browser manifest v6 advertise only the payment chain ID
 and token/vault addresses. RPC providers belong to the application or wallet;
 the node's verification RPC URL is never sent to the browser. Paid uploads
@@ -292,6 +301,56 @@ $ ant chunk get a1b2c3d4... -o output.bin
 |------|-------------|
 | `-o, --output <PATH>` | Write to file instead of stdout. |
 
+### `ant pointer` — Pointer Operations
+
+A pointer is a mutable reference to a chunk or to another pointer, signed by an
+owner key that can never change. Every state is paid for; reads are free. The
+owner key is kept as a 32-byte seed in a file only its owner can read (`0600`
+on Unix; on Windows it takes its directory's permissions, so keep it in your
+user profile). Losing it means the pointer can never be updated again.
+
+#### `ant pointer keygen --output <FILE>`
+
+Create a new owner key and print the address of the pointer it controls. Never
+overwrites an existing file.
+
+```
+$ ant pointer keygen --output owner.key
+Owner key written to owner.key
+9f3c...
+```
+
+#### `ant pointer address --key <FILE>`
+
+Print the address of the pointer a key controls. Needs no network.
+
+#### `ant pointer create --key <FILE> <TARGET> [--kind chunk|pointer]`
+
+Create the pointer, pointing at `TARGET` (hex). Requires `SECRET_KEY` to pay.
+Refused before paying if the pointer already exists.
+
+#### `ant pointer update --key <FILE> <TARGET> [--kind chunk|pointer]`
+
+Point it at `TARGET`, one past the counter the network serves (or create it).
+Requires `SECRET_KEY` to pay for the new state.
+
+#### `ant pointer get <ADDRESS>`
+
+Print a pointer's counter, target and state.
+
+```
+$ ant pointer get 9f3c...
+address:  9f3c...
+counter:  1
+kind:     chunk
+target:   a1b2...
+state_id: 5e7d...
+```
+
+#### `ant pointer resolve <ADDRESS>`
+
+Follow a chain of pointers to the target at its end.
+
 ### `ant wallet` — Wallet Operations
 
 Inspect the EVM wallet derived from `SECRET_KEY`.

ant-cli/Cargo.toml

@@ -19,10 +19,14 @@ clap = { version = "4", features = ["derive", "env"] }
 colored = "3.1.1"
 hex = "0.4"
 indicatif = "0.17"
+rand = "0.8"
 rmp-serde = "1"
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"
 tokio = { version = "1", features = ["full"] }
 tracing = "0.1"
 tracing-subscriber = { version = "0.3", features = ["env-filter"] }
 tracing-appender = "0.2"
+
+[dev-dependencies]
+tempfile = "3"

ant-cli/src/cli.rs

@@ -2,7 +2,7 @@ use ant_core::data::MultiAddr;
 use clap::{ArgAction, Parser, Subcommand};
 use std::path::PathBuf;
 
-use crate::commands::data::{ChunkAction, FileAction, WalletAction};
+use crate::commands::data::{ChunkAction, FileAction, PointerAction, WalletAction};
 use crate::commands::node::NodeCommand;
 use crate::commands::update::UpdateArgs;
 
@@ -110,6 +110,11 @@ pub enum Commands {
         #[command(subcommand)]
         action: ChunkAction,
     },
+    /// Pointer operations (owner-signed mutable references, paid per update)
+    Pointer {
+        #[command(subcommand)]
+        action: PointerAction,
+    },
     /// Update the ant binary to the latest version
     Update(UpdateArgs),
 }

ant-cli/src/commands/data/mod.rs

@@ -1,7 +1,9 @@
 pub mod chunk;
 pub mod file;
+pub mod pointer;
 pub mod wallet;
 
 pub use chunk::ChunkAction;
 pub use file::FileAction;
+pub use pointer::PointerAction;
 pub use wallet::WalletAction;