@blockula/sdk 0.1.0 → 0.3.0

package/README.md

@@ -27,4 +27,10 @@ const wallet = await createPasskeyWallet({ username: "vlad" });
 
 Amounts are FANG strings (`"1.5"`) or bigint drops (1 FANG = 10⁹ drops). Every transaction result includes a plain-English `summary`.
 
+- `send("alice.boo", …)` resolves the name first and signs the **address**, so whoever you checked is exactly who gets paid.
+- Node errors throw `ApiError` (`.status`: 429 means rate limited). A transaction that fails at execution throws `TxFailedError` from `waitForTx`.
+- Pass `rpId` to `createPasskeyWallet`/`unlockPasskeyWallet` to pin wallets to your production domain. Passkeys are bound to that hostname for good.
+
+The public testnet is `https://blockula-testnet.fly.dev`, and the wallet is https://blockula-wallet.vercel.app.
+
 ⚠️ Early and unaudited: test chains only.

package/dist/index.d.ts

@@ -55,10 +55,56 @@ export declare class Wallet {
         expiresInBlocks: number;
     }): Promise<any>;
     removeKey(keyIdHex: string): Promise<any>;
+    /**
+     * Offer a validator: bonds `bond` FANG from this account. `consensusKeyHex` is the validator
+     * node's ML-DSA-65 public key (see `blockula validator init`). Pending until an admin approves.
+     */
+    registerValidator(opts: {
+        consensusKey: string;
+        p2pAddr: string;
+        httpAddr: string;
+        bond: string | number | bigint;
+        pop: string;
+    }): Promise<any>;
+    /** Season 0 admins only. */
+    approveValidator(validator: string): Promise<any>;
+    /** Season 0 admins only. */
+    removeValidator(validator: string): Promise<any>;
+    /** Claim a GitHub handle. Verify it by creating a public gist (as that user) containing this account's address. */
+    linkGithub(handle: string, gistId: string): Promise<any>;
+    unlinkGithub(handle: string): Promise<any>;
+    /** Put a bounty on a GitHub issue. `expiresInBlocks` from now (max ~1 year). */
+    createHunt(opts: {
+        repo: string;
+        issue: number;
+        amount: string | number | bigint;
+        title: string;
+        expiresInBlocks: number;
+    }): Promise<any>;
+    fundHunt(huntId: number, amount: string | number | bigint): Promise<any>;
+    /** Pay a hunt's bounty (creator or admin). `to` may be a .boo name; it's resolved and the address is signed. */
+    awardHunt(huntId: number, to: string, pr: number, familiarKey?: string): Promise<any>;
+    cancelHunt(huntId: number): Promise<any>;
+    /** Mark one of this account's session keys (an agent) as a Familiar. */
+    registerFamiliar(keyIdHex: string, label: string): Promise<any>;
+    /** Reclaim the bond of a removed validator this account owns. */
+    unbond(validator: string): Promise<any>;
     balance(): Promise<string>;
     /** Dev/test chains only: drip 100 FANG to this wallet. */
     faucet(wait?: boolean): Promise<any>;
 }
+/** An error response from a Blockula node. `status` is the HTTP status (429 = rate limited). */
+export declare class ApiError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+/** A transaction that was rejected at execution (fee charged) or dropped from the mempool. */
+export declare class TxFailedError extends Error {
+    readonly id: string;
+    readonly reason: string;
+    readonly tx: any;
+    constructor(id: string, reason: string, tx: any);
+}
 export declare class Client {
     readonly rpc: string;
     constructor(rpc?: string);
@@ -72,6 +118,13 @@ export declare class Client {
     /** Accounts a key is authorized on (its own address, plus any it was added to). */
     keyAccounts(keyIdHex: string): Promise<any>;
     search(q: string): Promise<any>;
+    /** Active set for the current epoch, pending/approved validators, next-epoch set, epoch timing. */
+    validators(): Promise<any>;
+    /** Hunts (bounties on GitHub issues), biggest first. */
+    hunts(status?: "open" | "awarded" | "cancelled" | "expired"): Promise<any>;
+    hunt(id: number): Promise<any>;
+    /** Off-chain check of a GitHub link (gist owned by the handle containing the address). */
+    github(handle: string): Promise<any>;
     resolve(nameOrAddress: string): Promise<string>;
     submit(tx: Tx, wait?: boolean): Promise<any>;
     faucet(to: string, wait?: boolean): Promise<any>;

package/dist/index.js

@@ -13,6 +13,9 @@ export function keyId(publicKey) {
     return bytesToHex(blake3(publicKey));
 }
 export function isAddress(s) {
+    // Addresses are canonical lowercase; the node rejects any other casing.
+    if (s !== s.toLowerCase())
+        return false;
     try {
         const { prefix, words } = bech32m.decode(s);
         return prefix === "boo" && bech32m.fromWords(words).length === 32;
@@ -85,7 +88,10 @@ export class Wallet {
     }
     /** Send FANG to a `.boo` name or `boo1…` address. `amount` is in FANG ("1.5") or bigint drops. */
     async send(to, amount, opts = {}) {
-        const tx = await this.build({ type: "transfer", to, amount: parseFang(amount).toString() }, opts.memo);
+        // Sign the resolved address, not the name: what you checked is exactly who gets paid,
+        // even if the name changes hands before the block is sealed.
+        const recipient = await this.client.resolve(to);
+        const tx = await this.build({ type: "transfer", to: recipient, amount: parseFang(amount).toString() }, opts.memo);
         return this.client.submit(tx, opts.wait ?? true);
     }
     async registerName(name, opts = {}) {
@@ -101,6 +107,10 @@ export class Wallet {
      * Example: `addSessionKey(agentKeyId, "claude", { limit: "10", periodBlocks: 86_400, expiresInBlocks: 30 * 86_400 })`.
      */
     async addSessionKey(keyIdHex, label, opts) {
+        if (!Number.isSafeInteger(opts.periodBlocks) || opts.periodBlocks < 1)
+            throw new Error("periodBlocks must be a positive whole number of blocks");
+        if (!Number.isSafeInteger(opts.expiresInBlocks) || opts.expiresInBlocks < 1)
+            throw new Error("expiresInBlocks must be a positive whole number of blocks");
         const { height } = await this.client.status();
         const role = { type: "session", limit: parseFang(opts.limit).toString(), period_blocks: opts.periodBlocks, expires_at: height + opts.expiresInBlocks };
         return this.client.submit(await this.build({ type: "add_key", key_id: keyIdHex, label, role }));
@@ -108,6 +118,52 @@ export class Wallet {
     async removeKey(keyIdHex) {
         return this.client.submit(await this.build({ type: "remove_key", key_id: keyIdHex }));
     }
+    /**
+     * Offer a validator: bonds `bond` FANG from this account. `consensusKeyHex` is the validator
+     * node's ML-DSA-65 public key (see `blockula validator init`). Pending until an admin approves.
+     */
+    async registerValidator(opts) {
+        return this.client.submit(await this.build({ type: "register_validator", consensus_key: opts.consensusKey, p2p_addr: opts.p2pAddr, http_addr: opts.httpAddr, bond: parseFang(opts.bond).toString(), pop: opts.pop }));
+    }
+    /** Season 0 admins only. */
+    async approveValidator(validator) {
+        return this.client.submit(await this.build({ type: "approve_validator", validator }));
+    }
+    /** Season 0 admins only. */
+    async removeValidator(validator) {
+        return this.client.submit(await this.build({ type: "remove_validator", validator }));
+    }
+    /** Claim a GitHub handle. Verify it by creating a public gist (as that user) containing this account's address. */
+    async linkGithub(handle, gistId) {
+        return this.client.submit(await this.build({ type: "link_github", handle, gist_id: gistId }));
+    }
+    async unlinkGithub(handle) {
+        return this.client.submit(await this.build({ type: "unlink_github", handle }));
+    }
+    /** Put a bounty on a GitHub issue. `expiresInBlocks` from now (max ~1 year). */
+    async createHunt(opts) {
+        const { height } = await this.client.status();
+        return this.client.submit(await this.build({ type: "create_hunt", repo: opts.repo, issue: opts.issue, amount: parseFang(opts.amount).toString(), expires_at: height + opts.expiresInBlocks, title: opts.title }));
+    }
+    async fundHunt(huntId, amount) {
+        return this.client.submit(await this.build({ type: "fund_hunt", hunt_id: huntId, amount: parseFang(amount).toString() }));
+    }
+    /** Pay a hunt's bounty (creator or admin). `to` may be a .boo name; it's resolved and the address is signed. */
+    async awardHunt(huntId, to, pr, familiarKey) {
+        const addr = await this.client.resolve(to);
+        return this.client.submit(await this.build({ type: "award_hunt", hunt_id: huntId, to: addr, pr, ...(familiarKey ? { familiar_key: familiarKey } : {}) }));
+    }
+    async cancelHunt(huntId) {
+        return this.client.submit(await this.build({ type: "cancel_hunt", hunt_id: huntId }));
+    }
+    /** Mark one of this account's session keys (an agent) as a Familiar. */
+    async registerFamiliar(keyIdHex, label) {
+        return this.client.submit(await this.build({ type: "register_familiar", key_id: keyIdHex, label }));
+    }
+    /** Reclaim the bond of a removed validator this account owns. */
+    async unbond(validator) {
+        return this.client.submit(await this.build({ type: "unbond", validator }));
+    }
     balance() {
         return this.client.account(this.account).then((a) => a.balance_display, () => "0 FANG");
     }
@@ -116,6 +172,28 @@ export class Wallet {
         return this.client.faucet(this.account, wait);
     }
 }
+/** An error response from a Blockula node. `status` is the HTTP status (429 = rate limited). */
+export class ApiError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+        this.name = "ApiError";
+    }
+}
+/** A transaction that was rejected at execution (fee charged) or dropped from the mempool. */
+export class TxFailedError extends Error {
+    id;
+    reason;
+    tx;
+    constructor(id, reason, tx) {
+        super(`tx ${id} failed: ${reason}`);
+        this.id = id;
+        this.reason = reason;
+        this.tx = tx;
+        this.name = "TxFailedError";
+    }
+}
 export class Client {
     rpc;
     constructor(rpc = DEFAULT_RPC) {
@@ -123,9 +201,16 @@ export class Client {
     }
     async call(path, body) {
         const res = await fetch(this.rpc.replace(/\/$/, "") + "/api" + path, body === undefined ? undefined : { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(body) });
-        const json = await res.json();
+        const text = await res.text();
+        let json;
+        try {
+            json = JSON.parse(text);
+        }
+        catch {
+            throw new ApiError(res.status, res.ok ? "the node returned something that isn't JSON" : `node error ${res.status} ${res.statusText}`.trim());
+        }
         if (!res.ok)
-            throw new Error(json.error ?? res.statusText);
+            throw new ApiError(res.status, json.error ?? res.statusText);
         return json;
     }
     status() { return this.call("/status"); }
@@ -137,9 +222,18 @@ export class Client {
     /** Accounts a key is authorized on (its own address, plus any it was added to). */
     keyAccounts(keyIdHex) { return this.call(`/key/${keyIdHex}`); }
     search(q) { return this.call(`/search/${encodeURIComponent(q)}`); }
+    /** Active set for the current epoch, pending/approved validators, next-epoch set, epoch timing. */
+    validators() { return this.call("/validators"); }
+    /** Hunts (bounties on GitHub issues), biggest first. */
+    hunts(status) { return this.call(`/hunts${status ? `?status=${status}` : ""}`); }
+    hunt(id) { return this.call(`/hunt/${id}`); }
+    /** Off-chain check of a GitHub link (gist owned by the handle containing the address). */
+    github(handle) { return this.call(`/github/${encodeURIComponent(handle)}`); }
     async resolve(nameOrAddress) {
         if (isAddress(nameOrAddress))
             return nameOrAddress;
+        if (/^boo1/i.test(nameOrAddress.trim()))
+            throw new Error(`${nameOrAddress} isn't a valid address (check for typos; addresses are lowercase)`);
         const r = await this.name(nameOrAddress);
         if (r.available)
             throw new Error(`${r.name} isn't registered`);
@@ -159,6 +253,8 @@ export class Client {
             const tx = await this.tx(id);
             if (tx.status === "finalized")
                 return tx;
+            if (tx.status === "failed")
+                throw new TxFailedError(id, tx.error ?? "unknown reason", tx);
             if (Date.now() - start > timeoutMs)
                 throw new Error(`tx ${id} still pending after ${timeoutMs}ms`);
             await new Promise((r) => setTimeout(r, 250));

package/dist/passkey.d.ts

@@ -4,9 +4,11 @@ export declare function createPasskeyWallet(opts: {
     username: string;
     client?: Client;
     rpName?: string;
+    rpId?: string;
 }): Promise<Wallet>;
 /** Unlock an existing passkey wallet (shows the OS passkey picker). */
 export declare function unlockPasskeyWallet(opts?: {
     client?: Client;
     credentialId?: Uint8Array;
+    rpId?: string;
 }): Promise<Wallet>;

package/dist/passkey.js

@@ -6,8 +6,13 @@
 // used on-chain, so the account stays quantum-safe.
 import { Wallet } from "./index.js";
 const PRF_SALT = new TextEncoder().encode("blockula/wallet/v1");
-function rpId() {
-    return location.hostname;
+/**
+ * The WebAuthn relying-party id. Passkeys (and so wallets) are bound to it: a wallet created
+ * under one rpId can't be unlocked under another. Pin it to your production domain; it must be
+ * the page's hostname or a registrable parent of it.
+ */
+function rpId(explicit) {
+    return explicit ?? location.hostname;
 }
 function walletFrom(cred, prf, client) {
     const wallet = Wallet.fromPasskeyPrf(prf, client);
@@ -27,7 +32,7 @@ async function prfFromCredential(cred) {
 export async function createPasskeyWallet(opts) {
     const cred = (await navigator.credentials.create({
         publicKey: {
-            rp: { id: rpId(), name: opts.rpName ?? "Blockula" },
+            rp: { id: rpId(opts.rpId), name: opts.rpName ?? "Blockula" },
             user: { id: crypto.getRandomValues(new Uint8Array(16)), name: opts.username, displayName: opts.username },
             challenge: crypto.getRandomValues(new Uint8Array(32)),
             pubKeyCredParams: [{ type: "public-key", alg: -7 }, { type: "public-key", alg: -8 }, { type: "public-key", alg: -257 }],
@@ -41,14 +46,14 @@ export async function createPasskeyWallet(opts) {
     if (ext?.prf?.results?.first)
         return walletFrom(cred, new Uint8Array(ext.prf.results.first), opts.client);
     if (ext?.prf?.enabled)
-        return unlockPasskeyWallet({ client: opts.client, credentialId: cred ? new Uint8Array(cred.rawId) : undefined });
+        return unlockPasskeyWallet({ client: opts.client, rpId: opts.rpId, credentialId: cred ? new Uint8Array(cred.rawId) : undefined });
     return walletFrom(cred, await prfFromCredential(cred), opts.client);
 }
 /** Unlock an existing passkey wallet (shows the OS passkey picker). */
 export async function unlockPasskeyWallet(opts = {}) {
     const cred = (await navigator.credentials.get({
         publicKey: {
-            rpId: rpId(),
+            rpId: rpId(opts.rpId),
             challenge: crypto.getRandomValues(new Uint8Array(32)),
             userVerification: "required",
             allowCredentials: opts.credentialId ? [{ type: "public-key", id: opts.credentialId }] : [],

package/dist/tx.d.ts

@@ -23,6 +23,66 @@ export type Action = {
 } | {
     type: "remove_key";
     key_id: string;
+}
+/** Bond `bond` drops and offer `consensus_key` (hex ML-DSA-65 public key) as a validator. */
+ | {
+    type: "register_validator";
+    consensus_key: string;
+    p2p_addr: string;
+    http_addr: string;
+    bond: string;
+    /** Proof of possession: the consensus key's ML-DSA-65 signature over `popMessage(...)` with context `POP_CONTEXT` (see `blockula validator pop`). */
+    pop: string;
+}
+/** Season 0 allowlist (admin accounts only). */
+ | {
+    type: "approve_validator";
+    validator: string;
+} | {
+    type: "remove_validator";
+    validator: string;
+}
+/** Reclaim the bond of a removed validator you own, one epoch after it left. */
+ | {
+    type: "unbond";
+    validator: string;
+}
+/** Claim a GitHub handle; a public gist by that handle containing your boo1 address verifies it. */
+ | {
+    type: "link_github";
+    handle: string;
+    gist_id: string;
+} | {
+    type: "unlink_github";
+    handle: string;
+}
+/** Escrow a bounty on a GitHub issue ("owner/name", issue number). */
+ | {
+    type: "create_hunt";
+    repo: string;
+    issue: number;
+    amount: string;
+    expires_at: number;
+    title: string;
+} | {
+    type: "fund_hunt";
+    hunt_id: number;
+    amount: string;
+} | {
+    type: "award_hunt";
+    hunt_id: number;
+    to: string;
+    pr: number;
+    familiar_key?: string;
+} | {
+    type: "cancel_hunt";
+    hunt_id: number;
+}
+/** Mark one of your session keys as an agent Familiar. */
+ | {
+    type: "register_familiar";
+    key_id: string;
+    label: string;
 };
 export interface UnsignedTx {
     chain_id: string;
@@ -41,6 +101,10 @@ export declare const PUBLIC_KEY_LEN = 1952;
 export declare const SIGNATURE_LEN = 3309;
 export declare const DROPS_PER_FANG = 1000000000n;
 export declare function signingBytes(tx: UnsignedTx): Uint8Array;
+/** FIPS 204 context string for validator proofs of possession (node/src/types.rs `POP_CONTEXT`). */
+export declare const POP_CONTEXT: Uint8Array<ArrayBuffer>;
+/** What a validator's consensus key signs to register (node/src/types.rs `pop_message`). */
+export declare function popMessage(chainId: string, owner: string, p2pAddr: string, httpAddr: string): Uint8Array;
 /** Mirrors `min_fee` in node/src/types.rs: base fee is priced per byte and burned. */
 export declare function minFee(tx: UnsignedTx): bigint;
 /** "1.5" → 1500000000n drops. Accepts numbers, decimal strings or bigint drops. */

package/dist/tx.js

@@ -49,10 +49,78 @@ export function signingBytes(tx) {
             w.u8(3);
             w.str(a.key_id);
             break;
+        case "register_validator":
+            w.u8(4);
+            w.str(a.consensus_key);
+            w.str(a.p2p_addr);
+            w.str(a.http_addr);
+            w.u64(BigInt(a.bond));
+            w.str(a.pop);
+            break;
+        case "approve_validator":
+            w.u8(5);
+            w.str(a.validator);
+            break;
+        case "remove_validator":
+            w.u8(6);
+            w.str(a.validator);
+            break;
+        case "unbond":
+            w.u8(7);
+            w.str(a.validator);
+            break;
+        case "link_github":
+            w.u8(8);
+            w.str(a.handle);
+            w.str(a.gist_id);
+            break;
+        case "unlink_github":
+            w.u8(9);
+            w.str(a.handle);
+            break;
+        case "create_hunt":
+            w.u8(10);
+            w.str(a.repo);
+            w.u64(BigInt(a.issue));
+            w.u64(BigInt(a.amount));
+            w.u64(BigInt(a.expires_at));
+            w.str(a.title);
+            break;
+        case "fund_hunt":
+            w.u8(11);
+            w.u64(BigInt(a.hunt_id));
+            w.u64(BigInt(a.amount));
+            break;
+        case "award_hunt":
+            w.u8(12);
+            w.u64(BigInt(a.hunt_id));
+            w.str(a.to);
+            w.u64(BigInt(a.pr));
+            w.str(a.familiar_key ?? "");
+            break;
+        case "cancel_hunt":
+            w.u8(13);
+            w.u64(BigInt(a.hunt_id));
+            break;
+        case "register_familiar":
+            w.u8(14);
+            w.str(a.key_id);
+            w.str(a.label);
+            break;
     }
     w.str(tx.memo);
     return w.done();
 }
+/** FIPS 204 context string for validator proofs of possession (node/src/types.rs `POP_CONTEXT`). */
+export const POP_CONTEXT = utf8.encode("blockula/validator-pop/v1");
+/** What a validator's consensus key signs to register (node/src/types.rs `pop_message`). */
+export function popMessage(chainId, owner, p2pAddr, httpAddr) {
+    const w = new Writer();
+    w.bytes(utf8.encode("BLOCKULA_VALIDATOR_POP_V1"));
+    for (const s of [chainId, owner, p2pAddr, httpAddr])
+        w.str(s);
+    return w.done();
+}
 /** Mirrors `min_fee` in node/src/types.rs: base fee is priced per byte and burned. */
 export function minFee(tx) {
     const size = signingBytes(tx).length + PUBLIC_KEY_LEN + SIGNATURE_LEN;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blockula/sdk",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "\ud83e\udddb TypeScript SDK for Blockula \u2014 post-quantum wallets (ML-DSA-65), .boo names, transfers",
   "type": "module",
   "main": "dist/index.js",
@@ -44,5 +44,14 @@
   },
   "publishConfig": {
     "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jackdishman/blockula.git",
+    "directory": "sdk-ts"
+  },
+  "homepage": "https://github.com/jackdishman/blockula#readme",
+  "bugs": {
+    "url": "https://github.com/jackdishman/blockula/issues"
   }
 }