@blockula/sdk 1.0.0 → 1.0.3

package/README.md

@@ -11,8 +11,8 @@ npm install @blockula/sdk
 ```ts
 import { Client, Wallet, encodeKeyGrant } from "@blockula/sdk";
 
-const wallet = Wallet.generate(Client.testnet());  // the public testnet, every pin set: tboo1… addresses
-await wallet.faucet();                        // test chains: 100 test FANG
+const wallet = Wallet.generate(Client.local());   // `blockula dev` on this machine
+await wallet.faucet();                        // dev chains: 100 FANG
 await wallet.registerName("vlad");            // vlad.boo
 await wallet.send("alice.boo", "1.5", { memo: "trick or treat" });
 
@@ -22,19 +22,17 @@ const agentGrantCode = encodeKeyGrant(await agent.keyGrant(wallet.account));
 await wallet.addSessionKey(agentGrantCode, "claude", { limit: "10", periodBlocks: 86_400, expiresInBlocks: 30 * 86_400 });
 ```
 
-On a `blockula dev` chain, use `Client.local()` (or `new Client("http://localhost:7070")`).
+For a chain you made (`blockula summon`), pass its node: `new Client("https://<your node>", { chainId, genesisHash })`.
 
 ## Which network?
 
 ```ts
-Client.testnet();                                   // the public testnet
-new Client({ network: "testnet" });                 // the same
-new Client("http://localhost:7171", { network: "testnet" });  // your own node, held to the testnet's pins
 Client.local();                                     // blockula dev on this machine
+new Client("http://localhost:7171", { network: "testnet" });  // a blockula-testnet-2 node you run, held to its pins
 new Client("http://<your node>:7070", { chainId: "mychain", genesisHash: "…" });  // a chain of your own
 ```
 
-`NETWORKS` lists what each preset pins: the chain id, the genesis hash, the address prefix and the genesis clock. A client made for a network checks them on every status it reads, including the one each signature is made against, and refuses a node on another chain (`ChainMismatchError`). The prefix is known up front, so `wallet.address` is `tboo1…` on the testnet before the first request. Pins you pass as well must agree with the network's.
+The public testnet (`blockula-testnet-2`) was retired in November 2026 and has no public node, so the `testnet` preset has no RPC: `Client.testnet()` and `new Client({ network: "testnet" })` throw unless you pass a node's URL (`Client.testnet({ rpc })`). `NETWORKS` lists what each preset pins: the chain id, the genesis hash, the address prefix and the genesis clock. A client made for a network checks them on every status it reads, including the one each signature is made against, and refuses a node on another chain (`ChainMismatchError`). The prefix is known up front, so `wallet.address` is `tboo1…` on the testnet before the first request. Pins you pass as well must agree with the network's.
 
 A wallet signs nothing for a node that says it's on `blockula-1` unless its client pins that chain (`chainId: "blockula-1"`): it throws `MainnetNotAllowedError` instead.
 
@@ -98,16 +96,17 @@ await watchPayments(client, shopAddress, {
 
 ## Your own RPC node
 
-Any node serves the same API, and one on your machine isn't rate limited. To run one against the testnet:
+Any node serves the same API, and one on your machine isn't rate limited. To run one of a chain you know a node of:
 
 ```bash
-blockula join --genesis https://blockula-testnet.fly.dev --home ~/blockula-node --port 7171
+blockula join --genesis https://<a node of the chain> --home ~/blockula-node --port 7171
 ```
 
 ```ts
+const pins = { chainId: "mychain", genesisHash: "…" };              // a node on another chain is refused
 const client = new Client("http://localhost:7171", {
-  network: "testnet",                                         // its pins: a node on another chain is refused
-  witnesses: [new Client("https://blockula-testnet.fly.dev")], // names proven against a second node
+  ...pins,
+  witnesses: [new Client("https://<another node>", pins)],          // names proven against a second node
 });
 ```
 
@@ -160,7 +159,7 @@ wallet.validForBlocks = 600;
 Addresses are bech32m with the chain's prefix: `boo1…` by default, `tboo1…` on public testnets. `isAddress(s)` accepts any known prefix and `isAddress(s, "tboo")` exactly one; `addressFromPublicKey(pk, prefix)` renders one. A `Client` learns its chain's prefix from `/api/status` (`await client.addressPrefix()`), and wallets using that client sign with it (`wallet.address`, `wallet.account`). Pin it with `new Client(rpc, { prefix: "boo" })` to refuse a node on another network (see "Which chain?" below). Nodes reject addresses of another network's prefix.
 
 - Names in a signature (audit gap-7-1). Where the chain resolves a name itself (`send`, `awardHunt`, `vouch`/`unvouch`, `grantSoul`, `flagSybil`, `clawback`, `transferName`, proposal targets), a client with `witnesses` (below) signs the name's proven owner, and one without signs the **name itself** (`alice.boo`): the chain pays whoever owns it when the tx runs, so a lying node can't point it at another account now. It could still hold the signed tx and release it later in its validity window, which counts from the height that node reported, by when the name may have lapsed and been registered again: pay a name that's about to expire by address. `Wallet.build` refuses a height more than `maxHeadLeadBlocks` (30) ahead of the lowest head the witnesses report (every witness must answer, so one honest witness is enough), or past what a `genesisClock: { createdAtMs, blockTimeMs }` pin allows by this machine's clock (`HeightAheadError`, nothing signed); without either the height is the node's word. `client.recipient(name)` says which (`signed`, `byChain`, and `how` to show before signing); the address it reports for an unproven name is the node's word, for display. Where an address is needed (`delegate`, `undelegate`, `redelegate`, `unjail`, `actAs`, `keyGrant`), a name is resolved (`client.resolution`: `proven` and `how`), and on `blockula-1` nothing is signed with one only a single node vouched for: it throws `UnprovenNameError` (checked against the very status each tx is signed for). Pass the address once its owner has confirmed it, or give the client witnesses.
-- `wallet.address` uses the chain's prefix once the client knows it. A client made for a network (`Client.testnet()`) or pinned with `prefix` knows it up front. Otherwise it shows the `boo` form until the first request, so `await client.addressPrefix()` first if you display it.
+- `wallet.address` uses the chain's prefix once the client knows it. A client made for a network (`Client.testnet({ rpc })`) or pinned with `prefix` knows it up front. Otherwise it shows the `boo` form until the first request, so `await client.addressPrefix()` first if you display it.
 - Node errors throw `ApiError` (`.status`: 429 means rate limited, and `.retryAfterMs` says how long the node asked you to wait). A transaction the node reports as failed throws `TxFailedError` from `waitForTx` (`dropped` says whether it ran: see "Timeouts and pending transactions").
 - Pass `rpId` to `createPasskeyWallet`/`unlockPasskeyWallet` to pin wallets to your production domain. Passkeys are bound to that hostname for good.
 
@@ -250,8 +249,6 @@ Every request has a timeout (`new Client(rpc, { timeoutMs })`, default 15 s, at
 
 `verifyReleaseSignature(sig, checksumsFile, trustedKeyId)` checks a release's offline ML-DSA-65 signature (docs/OPERATIONS.md "Releases").
 
-The public testnet is `https://blockula-testnet.fly.dev`, and the wallet is https://testnet.blockula.app.
-
 Tests: `npm run test:vectors` (offline: passkey derivation, state-proof and tx-encoding vectors from the node, every protocol v1 helper against a fake node, pinning, proof freshness, timeouts, release signatures, and `test/integrators.ts`: network presets, the `blockula-1` pin, balances, the nonce queue, `sendMany`, `quote`, history, `watchPayments` and `onSigned`; `test/programs.ts` (programs: every answer check, the fuel and deposit arithmetic, receipts and balance reconciliation, `provenProgram`'s refusals one by one, and the Wallet's helpers against a fake node serving answers recorded from a dev chain), and `test/examples.ts`, which runs `examples/pay-from-a-script.mjs` against a fake node, so build first), `npm run test:kat` (ML-DSA known answers), `npm test` (end to end against `blockula dev`: `test/e2e.ts` and `test/e2e-integrators.ts`, on a chain with programs or without), `npm run test:programs` (`test/e2e-programs.ts`, which needs `blockula dev --programs`: on a chain without programs it says so and passes, and `BLOCKULA_E2E_PROGRAMS=1` makes that a failure, as CI sets it). The `examples/` directory at the repository's root has two runnable scripts: receiving payments, and paying from a script.
 
 ## Changes in 0.6

package/dist/index.d.ts

@@ -1233,6 +1233,54 @@ export interface HistoryPage {
      */
     paged: boolean;
 }
+/** An account as the node labels it: its primary `.boo` name when it has one (chain text). */
+export interface AccountLabel {
+    address: string;
+    name: string | null;
+    short: string;
+}
+/** One row of `/api/accounts`. */
+export interface DirectoryAccount {
+    account: AccountLabel;
+    /** Its active names, primary first. */
+    names: string[];
+    balance: string;
+    balance_display: string;
+    transferable: string;
+    transferable_display: string;
+    /** The height of its newest finalized tx this node holds, or null. */
+    last_active: number | null;
+    validator: boolean;
+    program: boolean;
+    /** A system account's role (treasury, community, …), or null. */
+    system: string | null;
+}
+/** A page of `/api/accounts`. */
+export interface AccountsPage {
+    sort: "balance" | "recent" | "names";
+    accounts: DirectoryAccount[];
+    /** The next page's `after`, or null at the end. */
+    next: string | null;
+    /** Rows in this listing (named accounts only for `names`). */
+    total: number;
+    accounts_total: number;
+}
+/** One row of `/api/names`. */
+export interface DirectoryName {
+    name: string;
+    owner: AccountLabel;
+    registered_at: number;
+    expires_at: number;
+    grace_until: number;
+    status: "active" | "grace";
+}
+/** A page of `/api/names`. */
+export interface NamesPage {
+    sort: "recent" | "alpha";
+    names: DirectoryName[];
+    next: string | null;
+    total: number;
+}
 export declare class Client {
     /** The chain's address prefix: given, learned from `/api/status`, or `boo` until then. */
     prefix: string;
@@ -1258,7 +1306,7 @@ export declare class Client {
     readonly network?: NetworkName;
     /** See `ClientOptions.wireTxs`. */
     readonly wireTxs: boolean;
-    /** The public testnet (`NETWORKS.testnet`), every pin set: `Client.testnet({ witnesses })`, or pass your own node's URL as `rpc`. */
+    /** A node of blockula-testnet-2 (`NETWORKS.testnet`), every pin set: `Client.testnet({ rpc })`. The public testnet was retired and has no public node, so `rpc` is required. */
     static testnet(opts?: Omit<ClientOptions, "network"> & {
         rpc?: string;
     }): Client;
@@ -1267,7 +1315,7 @@ export declare class Client {
         rpc?: string;
     }): Client;
     /**
-     * `new Client(rpc, opts)`, `new Client({ network: "testnet" })` (the network's public RPC), or
+     * `new Client(rpc, opts)`, `new Client({ network: "local" })` (the network's built-in RPC), or
      * `new Client(rpc, { network })` (your own node, held to that network's pins). The pins
      * (`opts`, and the network's) are checked on every status: a node reporting another prefix,
      * chain id or genesis hash is refused with `ChainMismatchError`.
@@ -1358,6 +1406,22 @@ export declare class Client {
         limit?: number;
     }): Promise<any>;
     search(q: string): Promise<any>;
+    /**
+     * The people directory: accounts richest first (`balance`), by their newest tx (`recent`; not
+     * offered on very large chains) or by name (`names`: named accounts only), a page at a time
+     * (pass the previous page's `next` as `after`; at most 100). Names are chain text: show them as text.
+     */
+    accounts(opts?: {
+        sort?: "balance" | "recent" | "names";
+        limit?: number;
+        after?: string;
+    }): Promise<AccountsPage>;
+    /** Registered names (active, or in their grace), newest registration first (`recent`) or alphabetically (`alpha`), a page at a time. */
+    names(opts?: {
+        sort?: "recent" | "alpha";
+        limit?: number;
+        after?: string;
+    }): Promise<NamesPage>;
     /** The validator set: `active` this epoch, `next_epoch` (with `joining`/`leaving`), `candidates`, `jailed`, `tombstoned` and `removed`, each with stake, self-bond, commission, jail and liveness; epoch timing; the churn limit and slashing parameters. */
     validators(): Promise<any>;
     /** Hunts (bounties on GitHub issues), biggest first. */

package/dist/index.js

@@ -6,7 +6,7 @@ import { DEFAULT_TIP_CAP_MULTIPLE, KEY_POP_CONTEXT, PUBLIC_KEY_LEN, SIGNATURE_LE
 import { NAMESPACES, checkProofResponse, decodeAccount, decodeName, decodeProgram } from "./proof.js";
 import { ANY_PROGRAM_VERSION, MAX_PROGRAM_BINDINGS, MAX_PROGRAM_CALLS, MAX_PROGRAM_CODE_BYTES, MAX_PROGRAM_INTERFACE_BYTES, ProgramAnswerError, ProgramsOffError, defaultFuelLimit, depositWithMargin, plainText, positiveFuel, programAddressArg, programBytesArg, programHashArg, programInputArg, programMethodArg, checkCode, checkFuel, checkInterface, checkParams, checkProgram, checkProgramsStatus, checkReceipt, checkView, outcomeWords, priceFuel, programCost, programRecordDeposit, programUploadDeposit, reserveFuel, uploadFuel } from "./programs.js";
 import { describeKind, reviewAction } from "./describe.js";
-import { NETWORKS, isNetworkName } from "./networks.js";
+import { NETWORKS, TESTNET_RETIRED, isNetworkName } from "./networks.js";
 export * from "./tx.js";
 export * from "./proof.js";
 export * from "./distribution.js";
@@ -1965,6 +1965,17 @@ function canonicalNodeUrl(u) {
         return u;
     }
 }
+/** `?sort=&limit=&after=` from the options that are set. */
+function pageQuery(opts) {
+    const q = new URLSearchParams();
+    if (opts.sort)
+        q.set("sort", opts.sort);
+    if (opts.limit !== undefined)
+        q.set("limit", String(opts.limit));
+    if (opts.after)
+        q.set("after", opts.after);
+    return q.size ? `?${q}` : "";
+}
 export class Client {
     /** The chain's address prefix: given, learned from `/api/status`, or `boo` until then. */
     prefix;
@@ -1987,7 +1998,7 @@ export class Client {
     network;
     /** See `ClientOptions.wireTxs`. */
     wireTxs;
-    /** The public testnet (`NETWORKS.testnet`), every pin set: `Client.testnet({ witnesses })`, or pass your own node's URL as `rpc`. */
+    /** A node of blockula-testnet-2 (`NETWORKS.testnet`), every pin set: `Client.testnet({ rpc })`. The public testnet was retired and has no public node, so `rpc` is required. */
     static testnet(opts = {}) {
         const { rpc, ...rest } = opts;
         return new Client(rpc, { ...rest, network: "testnet" });
@@ -1998,7 +2009,7 @@ export class Client {
         return new Client(rpc, { ...rest, network: "local" });
     }
     /**
-     * `new Client(rpc, opts)`, `new Client({ network: "testnet" })` (the network's public RPC), or
+     * `new Client(rpc, opts)`, `new Client({ network: "local" })` (the network's built-in RPC), or
      * `new Client(rpc, { network })` (your own node, held to that network's pins). The pins
      * (`opts`, and the network's) are checked on every status: a node reporting another prefix,
      * chain id or genesis hash is refused with `ChainMismatchError`.
@@ -2017,7 +2028,7 @@ export class Client {
         if (preset) {
             url ??= preset.rpc;
             if (url === undefined)
-                throw new Error(`no public ${preset.name} RPC is built into this SDK yet: pass the URL of a ${preset.name} node you trust, new Client(url, { network: "${preset.name}" })`);
+                throw new Error(preset.name === "testnet" ? TESTNET_RETIRED : `no public ${preset.name} RPC is built into this SDK: pass the URL of a ${preset.name} node you trust, new Client(url, { network: "${preset.name}" })`);
             opts = withPreset(opts, preset);
         }
         this.rpc = url ?? DEFAULT_RPC;
@@ -2220,6 +2231,18 @@ export class Client {
         return this.call(`/key/${keyIdHex}${q.size ? `?${q}` : ""}`);
     }
     search(q) { return this.call(`/search/${encodeURIComponent(q)}`); }
+    /**
+     * The people directory: accounts richest first (`balance`), by their newest tx (`recent`; not
+     * offered on very large chains) or by name (`names`: named accounts only), a page at a time
+     * (pass the previous page's `next` as `after`; at most 100). Names are chain text: show them as text.
+     */
+    accounts(opts = {}) {
+        return this.call(`/accounts${pageQuery(opts)}`);
+    }
+    /** Registered names (active, or in their grace), newest registration first (`recent`) or alphabetically (`alpha`), a page at a time. */
+    names(opts = {}) {
+        return this.call(`/names${pageQuery(opts)}`);
+    }
     /** The validator set: `active` this epoch, `next_epoch` (with `joining`/`leaving`), `candidates`, `jailed`, `tombstoned` and `removed`, each with stake, self-bond, commission, jail and liveness; epoch timing; the churn limit and slashing parameters. */
     validators() { return this.call("/validators"); }
     /** Hunts (bounties on GitHub issues), biggest first. */

package/dist/networks.d.ts

@@ -19,6 +19,8 @@ export interface NetworkPreset {
     /** The genesis clock of `genesisHash`'s genesis: it bounds the height a tx is signed against. */
     genesisClock?: NetworkClock;
 }
+/** Why `{ network: "testnet" }` needs a node URL: the public testnet has none any more. */
+export declare const TESTNET_RETIRED = "the public testnet (blockula-testnet-2) was retired in November 2026 and has no public node: run your own chain (`blockula dev`, `blockula summon`) and pass its URL, or pass the URL of a blockula-testnet-2 node you run, new Client(url, { network: \"testnet\" })";
 /** The networks this SDK knows: `new Client({ network })` pins what they list. */
 export declare const NETWORKS: Readonly<Record<NetworkName, Readonly<NetworkPreset>>>;
 /** Whether `s` names a network this SDK knows. */

package/dist/networks.js

@@ -1,21 +1,24 @@
 // The networks this SDK knows by name, and what a client for each pins (DEV-1).
 //
-// `new Client({ network: "testnet" })` (or `Client.testnet()`) talks to the public testnet and
-// pins its chain id, genesis hash, address prefix and genesis clock up front, so the first address
-// it renders is already `tboo1…` and a node on any other chain is refused before anything is
-// signed. `new Client("http://localhost:7171", { network: "testnet" })` does the same through your
-// own node. For a chain of your own, pin it yourself: `new Client(rpc, { chainId, genesisHash })`.
+// `new Client("http://localhost:7171", { network: "testnet" })` (or `Client.testnet({ rpc })`)
+// talks to your own node of blockula-testnet-2 and pins its chain id, genesis hash, address prefix
+// and genesis clock up front, so the first address it renders is already `tboo1…` and a node on
+// any other chain is refused before anything is signed. The public testnet was retired in November
+// 2026 and has no public node, so no RPC is built in for it: pass your node's URL. For a chain of
+// your own, pin it yourself: `new Client(rpc, { chainId, genesisHash })`.
 //
-// The testnet values match mcp/src/network.ts (`TESTNET_RPC`, `KNOWN_GENESIS`, `KNOWN_CLOCKS`) and
+// The testnet values match mcp/src/network.ts (`KNOWN_GENESIS`, `KNOWN_CLOCKS`) and
 // web/lib/config.ts; test/integrators.ts checks the MCP's.
+/** blockula-testnet-2, the retired public testnet: its pins, and no public RPC. */
 const TESTNET = {
     name: "testnet",
-    rpc: "https://blockula-testnet.fly.dev",
     chainId: "blockula-testnet-2",
     genesisHash: "b004e2f91b63429fc009088b16ec02b6d5388a03642699ae3dc6e325939f19b2",
     prefix: "tboo",
     genesisClock: { createdAtMs: 1792328803000, blockTimeMs: 1000 },
 };
+/** Why `{ network: "testnet" }` needs a node URL: the public testnet has none any more. */
+export const TESTNET_RETIRED = 'the public testnet (blockula-testnet-2) was retired in November 2026 and has no public node: run your own chain (`blockula dev`, `blockula summon`) and pass its URL, or pass the URL of a blockula-testnet-2 node you run, new Client(url, { network: "testnet" })';
 /** A `blockula dev` chain on this machine. Nothing is pinned: `--reset` makes a new chain each time. */
 const LOCAL = { name: "local", rpc: "http://localhost:7070" };
 const frozen = (p) => Object.freeze({ ...p, genesisClock: p.genesisClock ? Object.freeze({ ...p.genesisClock }) : undefined });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blockula/sdk",
-  "version": "1.0.0",
+  "version": "1.0.3",
   "description": "\ud83e\udddb TypeScript SDK for Blockula: wallets with post-quantum signatures (ML-DSA-65), .boo names and transfers. Experimental software, provided as is under MIT.",
   "type": "module",
   "main": "dist/index.js",