@1sat/wallet-toolbox 0.0.8 → 0.0.9

package/dist/api/locks/index.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Locks Module
+ *
+ * Functions for time-locking BSV.
+ */
+import { type WalletInterface, type WalletOutput } from "@bsv/sdk";
+export interface LockBsvRequest {
+    /** Amount in satoshis to lock */
+    satoshis: number;
+    /** Block height until which to lock */
+    until: number;
+}
+export interface LockData {
+    /** Total locked satoshis */
+    totalLocked: number;
+    /** Unlockable satoshis (matured locks) */
+    unlockable: number;
+    /** Next unlock block height */
+    nextUnlock: number;
+}
+export interface LockOperationResponse {
+    txid?: string;
+    rawtx?: string;
+    error?: string;
+}
+/**
+ * List locked outputs from the lock basket.
+ * Returns WalletOutput[] directly - use tags for metadata (lock:until:).
+ */
+export declare function listLocks(cwi: WalletInterface, limit?: number): Promise<WalletOutput[]>;
+/**
+ * Get lock data summary.
+ */
+export declare function getLockData(cwi: WalletInterface, chain?: "main" | "test", wocApiKey?: string): Promise<LockData>;
+/**
+ * Lock BSV until a block height.
+ * Derives lock address using hardcoded keyID.
+ */
+export declare function lockBsv(cwi: WalletInterface, requests: LockBsvRequest[]): Promise<LockOperationResponse>;
+/**
+ * Unlock matured BSV locks.
+ * Uses createSignature with stored keyID to sign unlock transactions.
+ */
+export declare function unlockBsv(cwi: WalletInterface, chain?: "main" | "test", wocApiKey?: string): Promise<LockOperationResponse>;

package/dist/api/locks/index.js

@@ -0,0 +1,233 @@
+/**
+ * Locks Module
+ *
+ * Functions for time-locking BSV.
+ */
+import { Hash, PublicKey, Script, Transaction, TransactionSignature, Utils, } from "@bsv/sdk";
+import { LOCK_BASKET, LOCK_PREFIX, LOCK_SUFFIX, MIN_UNLOCK_SATS } from "../constants";
+import { getChainInfo } from "../balance";
+// Hardcoded keyID for all locks - deterministic derivation
+const LOCK_KEY_ID = "lock";
+/**
+ * Build lock script for time-locked BSV.
+ */
+function buildLockScript(address, until) {
+    const pkh = Utils.fromBase58Check(address).data;
+    return new Script()
+        .writeScript(Script.fromHex(LOCK_PREFIX))
+        .writeBin(pkh)
+        .writeNumber(until)
+        .writeScript(Script.fromHex(LOCK_SUFFIX));
+}
+/**
+ * List locked outputs from the lock basket.
+ * Returns WalletOutput[] directly - use tags for metadata (lock:until:).
+ */
+export async function listLocks(cwi, limit = 10000) {
+    const result = await cwi.listOutputs({
+        basket: LOCK_BASKET,
+        includeTags: true,
+        limit,
+    });
+    return result.outputs;
+}
+/**
+ * Get lock data summary.
+ */
+export async function getLockData(cwi, chain = "main", wocApiKey) {
+    const lockData = { totalLocked: 0, unlockable: 0, nextUnlock: 0 };
+    const chainInfo = await getChainInfo(chain, wocApiKey);
+    const currentHeight = chainInfo?.blocks || 0;
+    const outputs = await listLocks(cwi);
+    for (const o of outputs) {
+        const lockTag = o.tags?.find((t) => t.startsWith("lock:until:"));
+        if (!lockTag)
+            continue;
+        const until = parseInt(lockTag.slice(11), 10);
+        lockData.totalLocked += o.satoshis;
+        if (until <= currentHeight) {
+            lockData.unlockable += o.satoshis;
+        }
+        else if (!lockData.nextUnlock || until < lockData.nextUnlock) {
+            lockData.nextUnlock = until;
+        }
+    }
+    if (lockData.unlockable < MIN_UNLOCK_SATS * outputs.length) {
+        lockData.unlockable = 0;
+    }
+    return lockData;
+}
+/**
+ * Lock BSV until a block height.
+ * Derives lock address using hardcoded keyID.
+ */
+export async function lockBsv(cwi, requests) {
+    try {
+        if (!requests || requests.length === 0) {
+            return { error: "no-lock-requests" };
+        }
+        // Derive lock address once (same for all locks)
+        const { publicKey } = await cwi.getPublicKey({
+            protocolID: [1, "lock"],
+            keyID: LOCK_KEY_ID,
+            counterparty: "self",
+            forSelf: true,
+        });
+        const lockAddress = PublicKey.fromString(publicKey).toAddress();
+        const outputs = [];
+        for (const req of requests) {
+            if (req.satoshis <= 0)
+                return { error: "invalid-satoshis" };
+            if (req.until <= 0)
+                return { error: "invalid-block-height" };
+            const lockingScript = buildLockScript(lockAddress, req.until);
+            outputs.push({
+                lockingScript: lockingScript.toHex(),
+                satoshis: req.satoshis,
+                outputDescription: `Lock ${req.satoshis} sats until block ${req.until}`,
+                basket: LOCK_BASKET,
+                tags: [`lock:until:${req.until}`],
+            });
+        }
+        const result = await cwi.createAction({
+            description: `Lock BSV in ${requests.length} output(s)`,
+            outputs,
+        });
+        if (!result.txid) {
+            return { error: "no-txid-returned" };
+        }
+        return { txid: result.txid, rawtx: result.tx ? Utils.toHex(result.tx) : undefined };
+    }
+    catch (error) {
+        return { error: error instanceof Error ? error.message : "unknown-error" };
+    }
+}
+/**
+ * Unlock matured BSV locks.
+ * Uses createSignature with stored keyID to sign unlock transactions.
+ */
+export async function unlockBsv(cwi, chain = "main", wocApiKey) {
+    try {
+        // Get current block height
+        const chainInfo = await getChainInfo(chain, wocApiKey);
+        const currentHeight = chainInfo?.blocks || 0;
+        if (currentHeight === 0) {
+            return { error: "could-not-get-block-height" };
+        }
+        // Get lock outputs from basket
+        const result = await cwi.listOutputs({
+            basket: LOCK_BASKET,
+            includeTags: true,
+            include: "locking scripts",
+            limit: 10000,
+        });
+        // Filter for matured locks
+        const maturedLocks = [];
+        for (const o of result.outputs) {
+            const untilTag = o.tags?.find((t) => t.startsWith("lock:until:"));
+            if (!untilTag)
+                continue;
+            const until = parseInt(untilTag.slice(11), 10);
+            if (until <= currentHeight) {
+                maturedLocks.push({ output: o, until });
+            }
+        }
+        if (maturedLocks.length === 0) {
+            return { error: "no-matured-locks" };
+        }
+        // Check minimum unlock amount
+        const totalSats = maturedLocks.reduce((sum, l) => sum + l.output.satoshis, 0);
+        if (totalSats < MIN_UNLOCK_SATS * maturedLocks.length) {
+            return { error: "insufficient-unlock-amount" };
+        }
+        // Find max until value for lockTime
+        const maxUntil = Math.max(...maturedLocks.map((l) => l.until));
+        // Build createAction args
+        const createResult = await cwi.createAction({
+            description: `Unlock ${maturedLocks.length} lock(s)`,
+            inputs: maturedLocks.map((l) => ({
+                outpoint: l.output.outpoint,
+                inputDescription: "Locked BSV",
+                unlockingScriptLength: 180, // sig + pubkey + preimage estimate
+                sequenceNumber: 0, // Must be < 0xffffffff for nLockTime
+            })),
+            outputs: [
+                {
+                    lockingScript: "", // Will be filled by wallet as change
+                    satoshis: 0, // Will be calculated by wallet
+                    outputDescription: "Unlocked BSV",
+                },
+            ],
+            lockTime: maxUntil,
+            options: { signAndProcess: false },
+        });
+        if ("error" in createResult && createResult.error) {
+            return { error: String(createResult.error) };
+        }
+        if (!createResult.signableTransaction) {
+            return { error: "no-signable-transaction" };
+        }
+        // Parse transaction from BEEF
+        const tx = Transaction.fromBEEF(createResult.signableTransaction.tx);
+        // Build unlocking scripts for each input
+        const spends = {};
+        for (let i = 0; i < maturedLocks.length; i++) {
+            const lock = maturedLocks[i];
+            const input = tx.inputs[i];
+            const lockingScript = Script.fromHex(lock.output.lockingScript);
+            // Build preimage for signature
+            const preimage = TransactionSignature.format({
+                sourceTXID: input.sourceTXID,
+                sourceOutputIndex: input.sourceOutputIndex,
+                sourceSatoshis: lock.output.satoshis,
+                transactionVersion: tx.version,
+                otherInputs: tx.inputs.filter((_, idx) => idx !== i),
+                outputs: tx.outputs,
+                inputIndex: i,
+                subscript: lockingScript,
+                inputSequence: 0,
+                lockTime: tx.lockTime,
+                scope: TransactionSignature.SIGHASH_ALL |
+                    TransactionSignature.SIGHASH_ANYONECANPAY |
+                    TransactionSignature.SIGHASH_FORKID,
+            });
+            // Hash preimage for signing
+            const sighash = Hash.sha256(Hash.sha256(preimage));
+            // Get signature via createSignature using hardcoded keyID
+            const { signature } = await cwi.createSignature({
+                protocolID: [1, "lock"],
+                keyID: LOCK_KEY_ID,
+                counterparty: "self",
+                hashToDirectlySign: Array.from(sighash),
+            });
+            // Get public key
+            const { publicKey } = await cwi.getPublicKey({
+                protocolID: [1, "lock"],
+                keyID: LOCK_KEY_ID,
+                counterparty: "self",
+                forSelf: true,
+            });
+            // Build unlocking script: <sig> <pubkey> <preimage>
+            const unlockingScript = new Script()
+                .writeBin(signature)
+                .writeBin(Utils.toArray(publicKey, "hex"))
+                .writeBin(Array.from(preimage));
+            spends[i] = { unlockingScript: unlockingScript.toHex() };
+        }
+        // Sign and broadcast
+        const signResult = await cwi.signAction({
+            reference: createResult.signableTransaction.reference,
+            spends,
+        });
+        if ("error" in signResult) {
+            return { error: String(signResult.error) };
+        }
+        return {
+            txid: signResult.txid,
+            rawtx: signResult.tx ? Utils.toHex(signResult.tx) : undefined,
+        };
+    }
+    catch (error) {
+        return { error: error instanceof Error ? error.message : "unknown-error" };
+    }
+}

package/dist/api/ordinals/index.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Ordinals Module
+ *
+ * Functions for managing ordinals/inscriptions.
+ * Returns WalletOutput[] directly from the SDK - no custom mapping needed.
+ */
+import { type WalletInterface, type WalletOutput, type CreateActionArgs, type ListOutputsArgs } from "@bsv/sdk";
+import type { OneSatServices } from "../../services/OneSatServices";
+export interface TransferOrdinalRequest {
+    /** Outpoint of the ordinal to transfer (txid_vout or txid.vout format) */
+    outpoint: string;
+    /** Destination address or paymail */
+    destination: string;
+}
+export interface ListOrdinalRequest {
+    /** Outpoint of ordinal to list */
+    outpoint: string;
+    /** Price in satoshis */
+    price: number;
+    /** Address that receives payment on purchase (BRC-29 receive address) */
+    payAddress: string;
+    /** Address that can cancel the listing (optional - derived from CWI if not provided) */
+    cancelAddress?: string;
+}
+export interface PurchaseOrdinalRequest {
+    /** Outpoint of listing to purchase */
+    outpoint: string;
+    /** Marketplace address for fees */
+    marketplaceAddress?: string;
+    /** Marketplace fee rate (0-1) */
+    marketplaceRate?: number;
+}
+export interface OrdinalOperationResponse {
+    txid?: string;
+    rawtx?: string;
+    error?: string;
+}
+/**
+ * Derive a cancel address for an ordinal listing.
+ * Uses the outpoint as keyID with security level 1 (self-only).
+ */
+export declare function deriveCancelAddress(cwi: WalletInterface, outpoint: string): Promise<string>;
+/**
+ * List ordinals from the 1sat basket.
+ * Returns WalletOutput[] directly - use tags for metadata (origin:, type:, name:, own:, list:).
+ */
+export declare function listOrdinals(cwi: WalletInterface, options?: Partial<ListOutputsArgs>): Promise<WalletOutput[]>;
+/**
+ * Build CreateActionArgs for transferring an ordinal.
+ * Does NOT execute - returns params for createAction.
+ */
+export declare function buildTransferOrdinal(cwi: WalletInterface, request: TransferOrdinalRequest): Promise<CreateActionArgs | {
+    error: string;
+}>;
+/**
+ * Build CreateActionArgs for listing an ordinal for sale.
+ * Does NOT execute - returns params for createAction.
+ * If cancelAddress is not provided, it will be derived from the CWI.
+ */
+export declare function buildListOrdinal(cwi: WalletInterface, request: ListOrdinalRequest): Promise<CreateActionArgs | {
+    error: string;
+}>;
+/**
+ * Transfer an ordinal to a new address.
+ */
+export declare function transferOrdinal(cwi: WalletInterface, request: TransferOrdinalRequest): Promise<OrdinalOperationResponse>;
+/**
+ * List an ordinal for sale on the global orderbook.
+ */
+export declare function listOrdinal(cwi: WalletInterface, request: ListOrdinalRequest): Promise<OrdinalOperationResponse>;
+/**
+ * Cancel an ordinal listing.
+ * Uses the origin tag to recover the keyID for signing.
+ * Cancel unlock script: <sig> <pubkey> OP_1
+ */
+export declare function cancelListing(cwi: WalletInterface, outpoint: string): Promise<OrdinalOperationResponse>;
+/**
+ * Purchase an ordinal from the global orderbook.
+ *
+ * Flow:
+ * 1. Fetch listing BEEF to get the locking script
+ * 2. Decode OrdLock to get price and payout
+ * 3. Build P2PKH output for buyer
+ * 4. Build payment output for seller
+ * 5. Build custom OrdLock purchase unlock (preimage only, no signature)
+ */
+export declare function purchaseOrdinal(cwi: WalletInterface, request: PurchaseOrdinalRequest, services?: OneSatServices): Promise<OrdinalOperationResponse>;