@blockula/sdk 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jack Dishman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,30 @@
-# Temporary Holding Version
+# @blockula/sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+🧛 TypeScript SDK for **Blockula**, a post-quantum blockchain. It covers ML-DSA-65 (FIPS 204) wallets, `.boo` names, transfers, multi-key accounts, agent session keys, and passkey-unlocked wallets.
+
+```bash
+npm install @blockula/sdk
+```
+
+```ts
+import { Client, Wallet } from "@blockula/sdk";
+
+const wallet = Wallet.generate(new Client("http://localhost:7070"));
+await wallet.faucet();                        // test chains: 100 FANG
+await wallet.registerName("vlad");            // vlad.boo
+await wallet.send("alice.boo", "1.5", { memo: "trick or treat" });
+
+// Let an agent spend up to 10 FANG/day from this account (enforced on-chain)
+await wallet.addSessionKey(agentKeyId, "claude", { limit: "10", periodBlocks: 86_400, expiresInBlocks: 30 * 86_400 });
+```
+
+In the browser, a passkey unlocks the wallet. There's no seed phrase, and the passkey's (non-quantum-safe) signature is never used on-chain. Its PRF output derives the ML-DSA key:
+
+```ts
+import { createPasskeyWallet, unlockPasskeyWallet } from "@blockula/sdk/passkey";
+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`.
+
+⚠️ Early and unaudited: test chains only.

package/dist/index.d.ts

@@ -0,0 +1,79 @@
+import { type Action, type Tx, type UnsignedTx } from "./tx.js";
+export * from "./tx.js";
+export declare const DEFAULT_RPC = "http://localhost:7070";
+export declare function addressFromPublicKey(publicKey: Uint8Array): string;
+/** A key's id: BLAKE3(public key) as hex. Same 32 bytes as inside the `boo1…` address it derives. */
+export declare function keyId(publicKey: Uint8Array): string;
+export declare function isAddress(s: string): boolean;
+/**
+ * Wallet = one ML-DSA-65 key (from a 32-byte seed, FIPS 204 ξ) acting for one account.
+ * By default the account is the key's own address. Call `actAs(account)` to use a key that
+ * was added to another account (a second device, or an agent session key).
+ */
+export declare class Wallet {
+    readonly seed: Uint8Array;
+    client: Client;
+    readonly publicKey: Uint8Array;
+    /** This key's own address. */
+    readonly address: string;
+    /** The account this wallet acts for (defaults to `address`). */
+    account: string;
+    /** WebAuthn credential id, when the wallet was unlocked by a passkey. Not secret. */
+    credentialId?: Uint8Array;
+    private readonly secretKey;
+    private constructor();
+    get keyId(): string;
+    /** Act for another account this key has been authorized on. Accepts a name or address. */
+    actAs(account: string): Promise<this>;
+    static generate(client?: Client): Wallet;
+    static fromSeed(seed: string | Uint8Array, client?: Client): Wallet;
+    /**
+     * Derive a wallet from a WebAuthn PRF output. The passkey never signs transactions
+     * (its P-256 signatures aren't quantum-safe); it only unlocks this ML-DSA key.
+     */
+    static fromPasskeyPrf(prfOutput: Uint8Array, client?: Client): Wallet;
+    get seedHex(): string;
+    sign(tx: UnsignedTx): Tx;
+    build(action: Action, memo?: string): Promise<Tx>;
+    /** Send FANG to a `.boo` name or `boo1…` address. `amount` is in FANG ("1.5") or bigint drops. */
+    send(to: string, amount: string | number | bigint, opts?: {
+        memo?: string;
+        wait?: boolean;
+    }): Promise<any>;
+    registerName(name: string, opts?: {
+        wait?: boolean;
+    }): Promise<any>;
+    /** Authorize another device's key (e.g. a second passkey) with full control. */
+    addOwnerKey(keyIdHex: string, label: string): Promise<any>;
+    /**
+     * Let an agent/app key spend from this account, transfers only, within a limit.
+     * Example: `addSessionKey(agentKeyId, "claude", { limit: "10", periodBlocks: 86_400, expiresInBlocks: 30 * 86_400 })`.
+     */
+    addSessionKey(keyIdHex: string, label: string, opts: {
+        limit: string | number | bigint;
+        periodBlocks: number;
+        expiresInBlocks: number;
+    }): Promise<any>;
+    removeKey(keyIdHex: string): Promise<any>;
+    balance(): Promise<string>;
+    /** Dev/test chains only: drip 100 FANG to this wallet. */
+    faucet(wait?: boolean): Promise<any>;
+}
+export declare class Client {
+    readonly rpc: string;
+    constructor(rpc?: string);
+    private call;
+    status(): Promise<any>;
+    blocks(limit?: number): Promise<any>;
+    block(heightOrHash: number | string): Promise<any>;
+    tx(id: string): Promise<any>;
+    account(addressOrName: string): Promise<any>;
+    name(name: string): Promise<any>;
+    /** 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>;
+    resolve(nameOrAddress: string): Promise<string>;
+    submit(tx: Tx, wait?: boolean): Promise<any>;
+    faucet(to: string, wait?: boolean): Promise<any>;
+    waitForTx(id: string, timeoutMs?: number): Promise<any>;
+}

package/dist/index.js

@@ -0,0 +1,167 @@
+import { ml_dsa65 } from "@noble/post-quantum/ml-dsa.js";
+import { blake3 } from "@noble/hashes/blake3.js";
+import { bytesToHex, hexToBytes, randomBytes, utf8ToBytes } from "@noble/hashes/utils.js";
+import { bech32m } from "@scure/base";
+import { minFee, parseFang, signingBytes } from "./tx.js";
+export * from "./tx.js";
+export const DEFAULT_RPC = "http://localhost:7070";
+export function addressFromPublicKey(publicKey) {
+    return bech32m.encode("boo", bech32m.toWords(blake3(publicKey)));
+}
+/** A key's id: BLAKE3(public key) as hex. Same 32 bytes as inside the `boo1…` address it derives. */
+export function keyId(publicKey) {
+    return bytesToHex(blake3(publicKey));
+}
+export function isAddress(s) {
+    try {
+        const { prefix, words } = bech32m.decode(s);
+        return prefix === "boo" && bech32m.fromWords(words).length === 32;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Wallet = one ML-DSA-65 key (from a 32-byte seed, FIPS 204 ξ) acting for one account.
+ * By default the account is the key's own address. Call `actAs(account)` to use a key that
+ * was added to another account (a second device, or an agent session key).
+ */
+export class Wallet {
+    seed;
+    client;
+    publicKey;
+    /** This key's own address. */
+    address;
+    /** The account this wallet acts for (defaults to `address`). */
+    account;
+    /** WebAuthn credential id, when the wallet was unlocked by a passkey. Not secret. */
+    credentialId;
+    secretKey;
+    constructor(seed, client = new Client()) {
+        this.seed = seed;
+        this.client = client;
+        const keys = ml_dsa65.keygen(seed);
+        this.publicKey = keys.publicKey;
+        this.secretKey = keys.secretKey;
+        this.address = addressFromPublicKey(keys.publicKey);
+        this.account = this.address;
+    }
+    get keyId() {
+        return keyId(this.publicKey);
+    }
+    /** Act for another account this key has been authorized on. Accepts a name or address. */
+    async actAs(account) {
+        this.account = await this.client.resolve(account);
+        return this;
+    }
+    static generate(client) {
+        return new Wallet(randomBytes(32), client);
+    }
+    static fromSeed(seed, client) {
+        const bytes = typeof seed === "string" ? hexToBytes(seed) : seed;
+        if (bytes.length !== 32)
+            throw new Error("seed must be 32 bytes");
+        return new Wallet(bytes, client);
+    }
+    /**
+     * Derive a wallet from a WebAuthn PRF output. The passkey never signs transactions
+     * (its P-256 signatures aren't quantum-safe); it only unlocks this ML-DSA key.
+     */
+    static fromPasskeyPrf(prfOutput, client) {
+        return new Wallet(blake3(prfOutput, { context: utf8ToBytes("blockula passkey wallet v1") }), client);
+    }
+    get seedHex() {
+        return bytesToHex(this.seed);
+    }
+    sign(tx) {
+        const signature = ml_dsa65.sign(signingBytes(tx), this.secretKey);
+        return { ...tx, public_key: bytesToHex(this.publicKey), signature: bytesToHex(signature) };
+    }
+    async build(action, memo = "") {
+        const [status, account] = await Promise.all([this.client.status(), this.client.account(this.account).catch(() => null)]);
+        const unsigned = { chain_id: status.chain_id, from: this.account, nonce: account?.next_nonce ?? 0, fee: "0", action, memo };
+        unsigned.fee = minFee(unsigned).toString();
+        return this.sign(unsigned);
+    }
+    /** 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);
+        return this.client.submit(tx, opts.wait ?? true);
+    }
+    async registerName(name, opts = {}) {
+        const tx = await this.build({ type: "register_name", name });
+        return this.client.submit(tx, opts.wait ?? true);
+    }
+    /** Authorize another device's key (e.g. a second passkey) with full control. */
+    async addOwnerKey(keyIdHex, label) {
+        return this.client.submit(await this.build({ type: "add_key", key_id: keyIdHex, label, role: { type: "owner" } }));
+    }
+    /**
+     * Let an agent/app key spend from this account, transfers only, within a limit.
+     * Example: `addSessionKey(agentKeyId, "claude", { limit: "10", periodBlocks: 86_400, expiresInBlocks: 30 * 86_400 })`.
+     */
+    async addSessionKey(keyIdHex, label, opts) {
+        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 }));
+    }
+    async removeKey(keyIdHex) {
+        return this.client.submit(await this.build({ type: "remove_key", key_id: keyIdHex }));
+    }
+    balance() {
+        return this.client.account(this.account).then((a) => a.balance_display, () => "0 FANG");
+    }
+    /** Dev/test chains only: drip 100 FANG to this wallet. */
+    faucet(wait = true) {
+        return this.client.faucet(this.account, wait);
+    }
+}
+export class Client {
+    rpc;
+    constructor(rpc = DEFAULT_RPC) {
+        this.rpc = rpc;
+    }
+    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();
+        if (!res.ok)
+            throw new Error(json.error ?? res.statusText);
+        return json;
+    }
+    status() { return this.call("/status"); }
+    blocks(limit = 20) { return this.call(`/blocks?limit=${limit}`); }
+    block(heightOrHash) { return this.call(`/block/${heightOrHash}`); }
+    tx(id) { return this.call(`/tx/${id}`); }
+    account(addressOrName) { return this.call(`/account/${encodeURIComponent(addressOrName)}`); }
+    name(name) { return this.call(`/name/${encodeURIComponent(name)}`); }
+    /** 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)}`); }
+    async resolve(nameOrAddress) {
+        if (isAddress(nameOrAddress))
+            return nameOrAddress;
+        const r = await this.name(nameOrAddress);
+        if (r.available)
+            throw new Error(`${r.name} isn't registered`);
+        return r.owner.address;
+    }
+    async submit(tx, wait = true) {
+        const { id } = await this.call("/tx", tx);
+        return wait ? this.waitForTx(id) : this.tx(id);
+    }
+    async faucet(to, wait = true) {
+        const { id } = await this.call("/faucet", { to });
+        return wait ? this.waitForTx(id) : this.tx(id);
+    }
+    async waitForTx(id, timeoutMs = 15_000) {
+        const start = Date.now();
+        for (;;) {
+            const tx = await this.tx(id);
+            if (tx.status === "finalized")
+                return 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

@@ -0,0 +1,12 @@
+import { Client, Wallet } from "./index.js";
+/** Create a new passkey and the wallet it unlocks. */
+export declare function createPasskeyWallet(opts: {
+    username: string;
+    client?: Client;
+    rpName?: string;
+}): Promise<Wallet>;
+/** Unlock an existing passkey wallet (shows the OS passkey picker). */
+export declare function unlockPasskeyWallet(opts?: {
+    client?: Client;
+    credentialId?: Uint8Array;
+}): Promise<Wallet>;

package/dist/passkey.js

@@ -0,0 +1,59 @@
+// Browser-only: passkey-backed Blockula wallets via the WebAuthn PRF extension.
+//
+// The passkey (Face ID / Touch ID / security key) produces a symmetric PRF secret,
+// which deterministically derives the ML-DSA-65 wallet key. Same passkey → same wallet
+// on every synced device, with no seed phrase. The passkey's own P-256 signature is never
+// 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;
+}
+function walletFrom(cred, prf, client) {
+    const wallet = Wallet.fromPasskeyPrf(prf, client);
+    if (cred)
+        wallet.credentialId = new Uint8Array(cred.rawId);
+    return wallet;
+}
+async function prfFromCredential(cred) {
+    const ext = cred?.getClientExtensionResults();
+    const first = ext?.prf?.results?.first;
+    if (!first) {
+        throw new Error("This passkey provider doesn't support the PRF extension. Try iCloud Keychain, Google Password Manager or 1Password.");
+    }
+    return new Uint8Array(first);
+}
+/** Create a new passkey and the wallet it unlocks. */
+export async function createPasskeyWallet(opts) {
+    const cred = (await navigator.credentials.create({
+        publicKey: {
+            rp: { id: 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 }],
+            authenticatorSelection: { residentKey: "required", userVerification: "required" },
+            extensions: { prf: { eval: { first: PRF_SALT } } },
+        },
+    }));
+    // Some authenticators only return PRF output on get(), not create(). Only retry with get()
+    // when the authenticator said PRF is enabled, so PRF-less providers fail fast with one prompt.
+    const ext = cred?.getClientExtensionResults();
+    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 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(),
+            challenge: crypto.getRandomValues(new Uint8Array(32)),
+            userVerification: "required",
+            allowCredentials: opts.credentialId ? [{ type: "public-key", id: opts.credentialId }] : [],
+            extensions: { prf: { eval: { first: PRF_SALT } } },
+        },
+    }));
+    return walletFrom(cred, await prfFromCredential(cred), opts.client);
+}

package/dist/tx.d.ts

@@ -0,0 +1,48 @@
+export type KeyRole = {
+    type: "owner";
+}
+/** Transfers only, at most `limit` drops (amount + fee) per `period_blocks`, until block `expires_at`. */
+ | {
+    type: "session";
+    limit: string;
+    period_blocks: number;
+    expires_at: number;
+};
+export type Action = {
+    type: "transfer";
+    to: string;
+    amount: string;
+} | {
+    type: "register_name";
+    name: string;
+} | {
+    type: "add_key";
+    key_id: string;
+    label: string;
+    role: KeyRole;
+} | {
+    type: "remove_key";
+    key_id: string;
+};
+export interface UnsignedTx {
+    chain_id: string;
+    /** The account acting; the signing key must be authorized on it. */
+    from: string;
+    nonce: number;
+    fee: string;
+    action: Action;
+    memo: string;
+}
+export interface Tx extends UnsignedTx {
+    public_key: string;
+    signature: string;
+}
+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;
+/** 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. */
+export declare function parseFang(amount: string | number | bigint): bigint;
+export declare function formatFang(drops: bigint | string): string;

package/dist/tx.js

@@ -0,0 +1,76 @@
+// Canonical transaction encoding. Must stay byte-identical to node/src/types.rs `Tx::signing_bytes`.
+export const PUBLIC_KEY_LEN = 1952;
+export const SIGNATURE_LEN = 3309;
+export const DROPS_PER_FANG = 1000000000n;
+const utf8 = new TextEncoder();
+class Writer {
+    parts = [];
+    bytes(b) { for (const x of b)
+        this.parts.push(x); }
+    u8(n) { this.parts.push(n & 0xff); }
+    u16(n) { this.u8(n); this.u8(n >> 8); }
+    u64(n) { for (let i = 0n; i < 8n; i++)
+        this.u8(Number((n >> (8n * i)) & 0xffn)); }
+    str(s) { const b = utf8.encode(s); this.u16(b.length); this.bytes(b); }
+    done() { return Uint8Array.from(this.parts); }
+}
+export function signingBytes(tx) {
+    const w = new Writer();
+    w.bytes(utf8.encode("BLOCKULA_TX_V2"));
+    w.str(tx.chain_id);
+    w.str(tx.from);
+    w.u64(BigInt(tx.nonce));
+    w.u64(BigInt(tx.fee));
+    const a = tx.action;
+    switch (a.type) {
+        case "transfer":
+            w.u8(0);
+            w.str(a.to);
+            w.u64(BigInt(a.amount));
+            break;
+        case "register_name":
+            w.u8(1);
+            w.str(a.name);
+            break;
+        case "add_key":
+            w.u8(2);
+            w.str(a.key_id);
+            w.str(a.label);
+            if (a.role.type === "owner")
+                w.u8(0);
+            else {
+                w.u8(1);
+                w.u64(BigInt(a.role.limit));
+                w.u64(BigInt(a.role.period_blocks));
+                w.u64(BigInt(a.role.expires_at));
+            }
+            break;
+        case "remove_key":
+            w.u8(3);
+            w.str(a.key_id);
+            break;
+    }
+    w.str(tx.memo);
+    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;
+    return 10000n + BigInt(size) * 10n;
+}
+/** "1.5" → 1500000000n drops. Accepts numbers, decimal strings or bigint drops. */
+export function parseFang(amount) {
+    if (typeof amount === "bigint")
+        return amount;
+    const s = String(amount).trim();
+    if (!/^\d+(\.\d{1,9})?$/.test(s))
+        throw new Error(`invalid FANG amount: ${s}`);
+    const [whole, frac = ""] = s.split(".");
+    return BigInt(whole) * DROPS_PER_FANG + BigInt(frac.padEnd(9, "0"));
+}
+export function formatFang(drops) {
+    const d = BigInt(drops);
+    const whole = d / DROPS_PER_FANG;
+    const frac = (d % DROPS_PER_FANG).toString().padStart(9, "0").replace(/0+$/, "");
+    return `${whole}${frac ? "." + frac : ""} FANG`;
+}

package/package.json

@@ -1,6 +1,48 @@
 {
   "name": "@blockula/sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "\ud83e\udddb TypeScript SDK for Blockula \u2014 post-quantum wallets (ML-DSA-65), .boo names, transfers",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js",
+    "./passkey": "./dist/passkey.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "tsx test/e2e.ts"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@noble/hashes": "^2.4.0",
+    "@noble/post-quantum": "^0.7.1",
+    "@scure/base": "^2.4.0"
+  },
+  "devDependencies": {
+    "@types/node": "*",
+    "tsx": "*",
+    "typescript": "*"
+  },
+  "author": "Jack Dishman",
+  "keywords": [
+    "blockula",
+    "post-quantum",
+    "ml-dsa",
+    "passkey",
+    "webauthn",
+    "blockchain",
+    "wallet"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}