@smartledger/bsv 5.5.3 → 6.0.1

package/bsv.d.ts

@@ -14,9 +14,24 @@ declare module '@smartledger/bsv' {
     export namespace crypto {
         class BN { }
 
-        namespace ECDSA {
-            function sign(message: Buffer, key: PrivateKey): Signature;
-            function verify(hashbuf: Buffer, sig: Signature, pubkey: PublicKey, endian?: 'little'): boolean;
+        class ECDSA {
+            hashbuf?: Buffer;
+            sig?: Signature;
+            pubkey?: PublicKey;
+            /** Result of the last verify() call. */
+            verified?: boolean;
+            /**
+             * @returns the ECDSA INSTANCE (always truthy) — the pass/fail result is on
+             * `.verified`. Treating this return value as a boolean silently accepts
+             * forged signatures; read `.verified` or use `verifyBool()`.
+             */
+            verify(): this;
+            /** Boolean verification — true only when the signature is valid (the safe form). */
+            verifyBool(): boolean;
+            /** Static: sign a hash. */
+            static sign(message: Buffer, key: PrivateKey): Signature;
+            /** Static: returns a real boolean (safe). */
+            static verify(hashbuf: Buffer, sig: Signature, pubkey: PublicKey, endian?: 'little'): boolean;
         }
 
         namespace Hash {
@@ -646,6 +661,54 @@ declare module '@smartledger/bsv' {
         function parseAnchorPayload(opReturnData: string): AnchorParseResult;
     }
 
+    // -------- SPV (trustless Merkle inclusion proofs) -------------------
+
+    export namespace SPV {
+        /** A Merkle branch proof. All hashes are DISPLAY-order hex; a node of '*' means "duplicate the working hash". */
+        interface MerkleProof { txid: string; index: number; nodes: string[]; merkleRoot: string; }
+        interface InclusionParams {
+            txid: string;
+            index: number;
+            nodes: string[];
+            /** a bsv.BlockHeader, an 80-byte Buffer, or 80-byte hex. */
+            header: any;
+            /** default true — require the header to meet its proof-of-work target. */
+            requirePow?: boolean;
+        }
+        interface InclusionResult {
+            valid: boolean;
+            rootMatches: boolean;
+            powValid: boolean;
+            merkleRoot: string;
+            blockHash: string;
+        }
+        /** Recompute the Merkle root from a branch proof (display-order hex). */
+        function merkleRootFromBranch(txid: string, index: number, nodes: string[]): string;
+        /** Verify a branch proof against an expected root. */
+        function verifyMerkleProof(proof: MerkleProof): boolean;
+        /** Verify a tx is included in a block: branch -> root, root == header.merkleRoot, PoW. */
+        function verifyTxInclusion(params: InclusionParams): InclusionResult;
+
+        interface HeaderChainResult {
+            valid: boolean;
+            reason?: string;
+            count: number;
+            anchorHash?: string;
+            tipHash?: string;
+            work?: number;
+        }
+        /**
+         * Verify consecutive headers (oldest->newest): each links to the previous and
+         * meets its PoW target; optionally the tip/anchor must equal opts.trustedHash.
+         * Validates linkage + per-header PoW, NOT the difficulty-retarget schedule —
+         * supply a trusted checkpoint hash for adversarial settings.
+         */
+        function verifyHeaderChain(
+            headers: Array<any>,
+            opts?: { requirePow?: boolean; trustedHash?: string }
+        ): HeaderChainResult;
+    }
+
     // -------- GDAF (Global Digital Attestation Framework) ---------------
 
     export class GDAF {
@@ -760,8 +823,14 @@ declare module '@smartledger/bsv' {
     // to evolving internal shapes.
 
     export namespace SmartContract {
+        /**
+         * @deprecated NON-ENFORCING — builds a constant hash-lock that reduces to
+         * plain P2PK and binds nothing about the spend. Use `policy()` (declarative
+         * OP_PUSH_TX), `PushTx`, `Token`, or `valueCovenant`. `createFromP2PKH` throws
+         * unless the instance is constructed with `{ allowNonEnforcing: true }`.
+         */
         class Covenant {
-            constructor(privateKey: PrivateKey, options?: object);
+            constructor(privateKey: PrivateKey, options?: { allowNonEnforcing?: boolean; [key: string]: any });
             [key: string]: any;
         }
         class Preimage {
@@ -772,8 +841,13 @@ declare module '@smartledger/bsv' {
             constructor(sighashType: number);
             [key: string]: any;
         }
+        /**
+         * @deprecated NON-ENFORCING — same constant hash-lock flaw as Covenant (reduces
+         * to P2PK). Use `policy()` / `PushTx` / `Token`. `buildLockingScript` and
+         * `createCovenant` throw unless constructed with `{ allowNonEnforcing: true }`.
+         */
         class Builder {
-            constructor(privateKey: PrivateKey, options?: object);
+            constructor(privateKey: PrivateKey, options?: { allowNonEnforcing?: boolean; [key: string]: any });
             [key: string]: any;
         }
         class UTXOGenerator {
@@ -836,6 +910,10 @@ declare module '@smartledger/bsv' {
         function ownershipToken(fee: number, ownerHash: Buffer): Script;
         /** OP_PUSH_TX value/output covenant: coins can only go where the covenant says. */
         function valueCovenant(expectedHashOutputs: Buffer): Script;
+        /** Ordinal covenant locking script (value-preserving; safe for 1-sat ordinals). */
+        function ordinalLock(owner: Buffer, auth?: Authorizer): Script;
+        /** Transfer a 1-sat (or N-sat) ordinal without burning it (see Token.transferOrdinal). */
+        function transferOrdinal(signer: any, newOwnerHash: Buffer, spend: Transaction, ordinalSats: number, lockingScript: Script, opts?: OrdinalOpts): Script;
 
         namespace CovenantHelpers {
             const SIGHASH: number;
@@ -850,26 +928,73 @@ declare module '@smartledger/bsv' {
             function scriptNum(n: number): Buffer;
         }
 
+        interface GrindOpts { maxTries?: number; start?: number; field?: 'nLockTime' | 'sequence'; sighashType?: number; }
+        interface GrindResult { preimage: Buffer; tries: number; field?: string; nonce?: number; }
+
         namespace PushTx {
             const Gx: Buffer;
             const PUBKEY: Buffer;
-            function pushTxCore(script: Script): Script;
+            /** SIGHASH_ALL|FORKID (0x41) — the default. */
+            const SIGHASH_ALL_FORKID: number;
+            /** SIGHASH_SINGLE|FORKID (0x43). */
+            const SIGHASH_SINGLE_FORKID: number;
+            /** SIGHASH_SINGLE|ANYONECANPAY|FORKID (0xc3) — marketplace / partially-signed. */
+            const SIGHASH_SINGLE_ANYONECANPAY_FORKID: number;
+            /** SIGHASH_ALL|ANYONECANPAY|FORKID (0xc1) — commit ALL outputs, open inputs (OrdLock). */
+            const SIGHASH_ALL_ANYONECANPAY_FORKID: number;
+            /**
+             * Append the in-script signature generator + OP_CHECKSIG. `opts.sighashType`
+             * sets the flag baked into the synthetic signature (default 0x41); the spender
+             * must push the matching BIP-143 preimage (grind with the same sighashType).
+             */
+            function pushTxCore(script: Script, opts?: { sighashType?: number }): Script;
             function authenticator(): Script;
+            /** Assert the spend is SIGHASH_ALL|FORKID. */
+            function assertSighashAll(script: Script): Script;
+            /** Assert the spend uses a specific SIGHASH flag (pairs with pushTxCore/grind opts). */
+            function assertSighashType(script: Script, sighashType: number): Script;
             function extractHashOutputs(script: Script): Script;
             function hashOutputs(outputs: Transaction.Output[]): Buffer;
             function valueCovenant(expectedHashOutputs: Buffer): Script;
             function sFromPreimage(preimage: Buffer): Buffer | null;
-            function grind(spend: Transaction, inputIndex: number, lockingScript: Script, satoshis: number, maxTries?: number): { preimage: Buffer; tries: number };
+            /** Grind a malleable field until the in-script signature is canonical. Legacy: a bare number is maxTries. */
+            function grind(spend: Transaction, inputIndex: number, lockingScript: Script, satoshis: number, opts?: GrindOpts | number): GrindResult;
         }
 
         namespace PELS {
             function pelsCovenant(fee: number): Script;
         }
 
+        /** Pluggable authorization scheme for Token covenants. */
+        interface Authorizer {
+            commit(owner: any): Buffer;
+            emit(script: Script): Script;
+            unlockArgs(spend: Transaction, inputIndex: number, lockingScript: Script, satoshis: number, signer: any): any[];
+        }
+        namespace Authorizers {
+            /** Single-key (default): owner id = HASH160(pubkey). */
+            function singleKey(): Authorizer;
+            /** m-of-n multisig authorizer. */
+            function multisig(m: number, keys: PublicKey[]): Authorizer;
+            /** Arbitrary predicate authorizer over a fixed 20-byte commitment. */
+            function predicate(commit: Buffer, emit: (script: Script) => Script): Authorizer;
+        }
+        interface TransferOpts { auth?: Authorizer; inputIndex?: number; grind?: GrindOpts; allowLowValue?: boolean; }
+        interface MultiLayout { before?: Buffer; after?: Buffer; tokenValue: Buffer; }
+        interface OrdinalOpts { auth?: Authorizer; inputIndex?: number; tokenIndex?: number; grind?: GrindOpts; }
         namespace Token {
-            function ownershipToken(fee: number, ownerHash: Buffer): Script;
-            function ownerId(secret: Buffer): Buffer;
-            function unlockTransfer(ownerSecret: Buffer, newOwnerHash: Buffer, preimage: Buffer): Script;
+            /** Single-output perpetual NFT (value = input - fee). NOT for 1-sat ordinals — use ordinalLock/transferOrdinal. */
+            function ownershipToken(fee: number, owner: Buffer, auth?: Authorizer): Script;
+            /** Multi-output token: the recreated output carries its own value and may sit among other outputs. */
+            function ownershipTokenMulti(owner: Buffer, auth?: Authorizer): Script;
+            /** Value-preserving ordinal covenant (safe for 1-sat ordinals). */
+            function ordinalLock(owner: Buffer, auth?: Authorizer): Script;
+            /** Owner id from a key (HASH160 of the pubkey) for the single-key authorizer. */
+            function ownerId(key: PrivateKey | PublicKey): Buffer;
+            function unlockTransfer(signer: any, newOwnerHash: Buffer, spend: Transaction, satoshis: number, lockingScript: Script, opts?: TransferOpts): Script;
+            function unlockTransferMulti(signer: any, newOwnerHash: Buffer, spend: Transaction, satoshis: number, lockingScript: Script, layout: MultiLayout, opts?: TransferOpts): Script;
+            /** Transfer a 1-sat (or N-sat) ordinal without burning it; recreates the token output at exactly `ordinalSats`. */
+            function transferOrdinal(signer: any, newOwnerHash: Buffer, spend: Transaction, ordinalSats: number, lockingScript: Script, opts?: OrdinalOpts): Script;
         }
 
         interface LockSpec { lock: Script; meta: { [k: string]: any }; [k: string]: any; }
@@ -916,6 +1041,160 @@ declare module '@smartledger/bsv' {
         }
     }
 
+    // -------- Ordinals (1Sat Ordinals inscriptions + marketplace) -------
+
+    export namespace Ordinals {
+        interface InscriptionParams {
+            contentType?: string | Buffer;
+            content?: string | Buffer;
+            lock?: Script | Buffer | string;
+            address?: Address | string;
+            satoshis?: number;
+        }
+        interface ParsedInscription {
+            contentType: string;
+            content: Buffer;
+            contentText: string;
+            lock: Script;
+        }
+        /** Build a 1Sat Ordinals inscription locking script (base lock + inert envelope). */
+        function buildInscription(params: InscriptionParams): Script;
+        /** Parse an inscription out of a locking script; null if none present. */
+        function parseInscription(script: Script | Buffer | string): ParsedInscription | null;
+        /** True if the script carries an inscription envelope. */
+        function isInscription(script: Script | Buffer | string): boolean;
+        /** Build the 1-sat Transaction.Output carrying an inscription. */
+        function createInscriptionOutput(params: InscriptionParams): Transaction.Output;
+        /** Build one 1-sat inscription output per item. */
+        function batchInscriptionOutputs(items: InscriptionParams[]): Transaction.Output[];
+
+        // ---- Marketplace: OrdLock "pay the seller or cancel" covenant ----
+        /** SIGHASH_ALL|ANYONECANPAY|FORKID (0xc1) — the flag OrdLock commits/grinds under. */
+        const ORDLOCK_SIGHASH: number;
+        /** A payment spec: a full Output, an {address,satoshis} pair, or serialized-output bytes. */
+        type PaymentSpec = Transaction.Output | Buffer | { address?: Address | PublicKey | PrivateKey | string; payTo?: Address | PublicKey | PrivateKey | string; satoshis?: number; price?: number };
+        interface OrdLockParams {
+            seller: Address | PublicKey | PrivateKey | string | Buffer;
+            price?: number;
+            payTo?: Address | PublicKey | PrivateKey | string | Transaction.Output;
+            /** Extra payments appended after the `price` output (royalties, marketplace fee). */
+            royalties?: PaymentSpec[];
+            /** Pin an explicit ordered list of payment outputs (overrides price/payTo/royalties). */
+            payOutputs?: PaymentSpec[];
+            payOutput?: Transaction.Output | Buffer;
+            inscription?: { contentType?: string | Buffer; content?: string | Buffer };
+            satoshis?: number;
+        }
+        interface ParsedPayment { satoshis: number; script: Script; address: string | null; }
+        interface ParsedOrdLock {
+            seller: { pubKeyHash: Buffer; address: string };
+            payOutputs: ParsedPayment[];
+            payBlob: Buffer;
+            totalPrice: number;
+            inscription: null | { contentType: string; content: Buffer; contentText: string };
+        }
+        interface PurchaseParams {
+            spend: Transaction;
+            lockingScript: Script;
+            satoshis?: number;
+            inputIndex?: number;
+            payoutIndex?: number;
+            /** Number of pinned payment outputs (auto-derived from the listing when omitted). */
+            payoutCount?: number;
+            /** Assert the pinned block matches the listing before signing (default true). */
+            validate?: boolean;
+            /** A pre-computed parseOrdLock(lockingScript) result, to avoid re-parsing. */
+            parsed?: ParsedOrdLock;
+            payOutput?: Transaction.Output | Buffer;
+            grind?: SmartContract.GrindOpts;
+        }
+        interface ParseOpts {
+            /** Network for returned address strings ('livenet' | 'testnet'); default livenet. */
+            network?: string;
+        }
+        interface CancelParams {
+            privateKey: PrivateKey;
+            spend: Transaction;
+            lockingScript: Script;
+            satoshis?: number;
+            inputIndex?: number;
+            sighashType?: number;
+        }
+        interface Outpoint { txid?: string; prevTxId?: string; outputIndex?: number; vout?: number; }
+        interface FundingCoin extends Outpoint { script: Script | Buffer | string; satoshis: number; privateKey: PrivateKey; }
+        interface OrdinalCoin extends Outpoint { script: Script | Buffer | string; satoshis?: number; privateKey: PrivateKey; }
+        interface BuildListingTxParams extends OrdLockParams {
+            ordinal: OrdinalCoin;
+            funding?: FundingCoin[];
+            fee?: number;
+            changeAddress?: Address | PublicKey | PrivateKey | string;
+        }
+        interface ListingTxResult { tx: Transaction; listingScript: Script; listingOutpoint: { txid: string; outputIndex: number }; }
+        interface BuildPurchaseTxParams {
+            listing: Outpoint & { script: Script | Buffer | string; satoshis?: number };
+            ordinalDestination: Address | PublicKey | PrivateKey | string;
+            funding: FundingCoin[];
+            payOutputs?: PaymentSpec[];
+            fee?: number;
+            changeAddress?: Address | PublicKey | PrivateKey | string;
+            grind?: SmartContract.GrindOpts;
+        }
+        /** Build an OrdLock listing (locking) script pinning the required payment output(s). */
+        function buildOrdLock(params: OrdLockParams): Script;
+        /** Parse an OrdLock listing into its economic terms; null if not an OrdLock. */
+        function parseOrdLock(script: Script | Buffer | string, opts?: ParseOpts): ParsedOrdLock | null;
+        /** True if the script is a recognizable OrdLock listing. */
+        function isOrdLock(script: Script | Buffer | string, opts?: ParseOpts): boolean;
+        /** Build the 1-sat Transaction.Output that lists an ordinal for sale. */
+        function listInscriptionOutput(params: OrdLockParams): Transaction.Output;
+        /** Build a P2PKH payment Output from an address/pubkey/key (or pass an Output through). */
+        function payOutputFor(payTo: Address | PublicKey | PrivateKey | string | Transaction.Output, price: number): Transaction.Output;
+        /** Build (and assign) the unlocking script that PURCHASES a listed ordinal. */
+        function purchaseOrdLock(params: PurchaseParams): Script;
+        /** Build (and assign) the unlocking script that CANCELS a listing. */
+        function cancelOrdLock(params: CancelParams): Script;
+        /** Assemble a complete, signed listing tx: move a P2PKH ordinal into an OrdLock output. */
+        function buildListingTx(params: BuildListingTxParams): ListingTxResult;
+        /** Assemble a complete, signed purchase tx from a listing UTXO and buyer P2PKH coins. */
+        function buildPurchaseTx(params: BuildPurchaseTxParams): Transaction;
+
+        // ---- BSV-20 / BSV-21 fungible-token inscriptions ----
+        namespace BSV20 {
+            type IntLike = string | number;
+            interface Owner { address?: Address | string; lock?: Script | Buffer | string; contentType?: string; satoshis?: number; }
+            /** A parsed BSV-20 payload. Amounts are integer strings (may exceed 2^53). */
+            interface Payload {
+                p: 'bsv-20';
+                op: 'deploy' | 'mint' | 'transfer' | 'deploy+mint' | string;
+                tick?: string;
+                id?: string;
+                amt?: string;
+                max?: string;
+                lim?: string;
+                dec?: string;
+                sym?: string;
+                icon?: string;
+            }
+            const CONTENT_TYPE: string;
+            /** Deploy a v1 (ticker) token. */
+            function buildDeploy(params: Owner & { tick: string; max: IntLike; lim?: IntLike; dec?: IntLike }): Script;
+            /** Mint an amount of a v1 (ticker) token. */
+            function buildMint(params: Owner & { tick: string; amt: IntLike }): Script;
+            /** Transfer an amount of a token — provide `tick` (v1) or `id` (v2 / BSV-21). */
+            function buildTransfer(params: Owner & { amt: IntLike; tick?: string; id?: string }): Script;
+            /** Deploy + mint a BSV-21 (id-based) supply in one operation. */
+            function buildDeployMint(params: Owner & { amt: IntLike; dec?: IntLike; sym?: string; icon?: string }): Script;
+            function createDeployOutput(params: Owner & { tick: string; max: IntLike; lim?: IntLike; dec?: IntLike }): Transaction.Output;
+            function createMintOutput(params: Owner & { tick: string; amt: IntLike }): Transaction.Output;
+            function createTransferOutput(params: Owner & { amt: IntLike; tick?: string; id?: string }): Transaction.Output;
+            function createDeployMintOutput(params: Owner & { amt: IntLike; dec?: IntLike; sym?: string; icon?: string }): Transaction.Output;
+            /** Parse a BSV-20 payload from a script, JSON string, or object; null if none. */
+            function parseBsv20(input: Script | Buffer | string | object): Payload | null;
+            /** True if the input carries a valid BSV-20 inscription. */
+            function isBsv20(input: Script | Buffer | string | object): boolean;
+        }
+    }
+
     // -------- BrowserUTXOManager ----------------------------------------
 
     export class BrowserUTXOManager {