@blockula/sdk 0.0.0-stage → 0.2.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,36 @@
-# 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`.
+
+- `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

@@ -0,0 +1,110 @@
+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>;
+    /**
+     * 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>;
+    /** 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);
+    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>;
+    /** Active set for the current epoch, pending/approved validators, next-epoch set, epoch timing. */
+    validators(): 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,231 @@
+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) {
+    // 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;
+    }
+    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 = {}) {
+        // 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 = {}) {
+        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) {
+        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 }));
+    }
+    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 }));
+    }
+    /** 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");
+    }
+    /** Dev/test chains only: drip 100 FANG to this wallet. */
+    faucet(wait = true) {
+        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) {
+        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 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 ApiError(res.status, 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)}`); }
+    /** Active set for the current epoch, pending/approved validators, next-epoch set, epoch timing. */
+    validators() { return this.call("/validators"); }
+    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`);
+        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 (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

@@ -0,0 +1,14 @@
+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;
+    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

@@ -0,0 +1,64 @@
+// 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");
+/**
+ * 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);
+    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(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 }],
+            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, 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(opts.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,75 @@
+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;
+}
+/** 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;
+};
+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;
+/** 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. */
+export declare function parseFang(amount: string | number | bigint): bigint;
+export declare function formatFang(drops: bigint | string): string;

package/dist/tx.js

@@ -0,0 +1,106 @@
+// 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;
+        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;
+    }
+    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;
+    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.2.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"
+  }
+}