@smartledger/bsv 7.5.0 → 7.5.2

package/bsv.d.ts

@@ -176,19 +176,30 @@ declare module '@smartledger/bsv' {
         toAddress(): Address;
         toPublicKey(): PublicKey;
         toString(): string;
-        toObject(): object;
-        toJSON(): object;
+        /** Deliberate export, INCLUDING the secret scalar. Round-trips with fromObject(). */
+        toObject(): { bn: string; compressed: boolean; network: string };
+        /**
+         * What JSON.stringify() calls — the scalar is REDACTED. Use toObject() or toWIF()
+         * when you actually intend to export the secret.
+         */
+        toJSON(): { bn: '[REDACTED]'; compressed: boolean; network: string };
         toWIF(): string;
         toHex(): string;
         toBigNumber(): any; //BN;
         toBuffer(): Buffer;
         inspect(): string;
 
-        static fromString(str: string): PrivateKey;
-        static fromWIF(str: string): PrivateKey;
-        static fromRandom(netowrk?: string): PrivateKey;
-        static fromBuffer(buf: Buffer, network: string | Networks.Network): PrivateKey;
-        static fromHex(hex: string, network: string | Networks.Network): PrivateKey;
+        /**
+         * From a WIF string, or a hex-encoded scalar. `network` is honoured; for a WIF,
+         * which encodes its own network, a conflicting value throws.
+         */
+        static fromString(str: string, network?: string | Networks.Network): PrivateKey;
+        static fromWIF(str: string, network?: string | Networks.Network): PrivateKey;
+        static fromRandom(network?: string): PrivateKey;
+        /** `compressed` defaults to true, matching every other constructor path. */
+        static fromBuffer(buf: Buffer, network?: string | Networks.Network, compressed?: boolean): PrivateKey;
+        /** `compressed` defaults to true, matching every other constructor path. */
+        static fromHex(hex: string, network?: string | Networks.Network, compressed?: boolean): PrivateKey;
         static getValidationError(data: string): any | null;
         static isValid(data: string): boolean;
     }
@@ -219,6 +230,11 @@ declare module '@smartledger/bsv' {
         static isValid(data: string): boolean;
     }
 
+    /**
+     * Callable with or without `new` — `bsv.Message(msg)` is the form the docs and
+     * examples use, and was previously untyped.
+     */
+    export function Message(message: string | Buffer): Message;
     export class Message {
         constructor(message: string | Buffer);
 
@@ -333,7 +349,13 @@ declare module '@smartledger/bsv' {
         function buildP2SHMultisigIn(pubkeys: PublicKey[], threshold: number, signatures: Buffer[], opts: object): Script;
         function buildPublicKeyHashOut(address: Address): Script;
         function buildPublicKeyOut(pubkey: PublicKey): Script;
+        /**
+         * Bare `OP_RETURN <data>`. Prefer buildSafeDataOut: a bare OP_RETURN is not
+         * provably unspendable.
+         */
         function buildDataOut(data: string | Buffer, encoding?: string): Script;
+        /** `OP_FALSE OP_RETURN <data>` — provably unspendable. Partner of isSafeDataOut(). */
+        function buildSafeDataOut(data: string | Buffer, encoding?: string): Script;
         function buildScriptHashOut(script: Script): Script;
         function buildPublicKeyIn(signature: crypto.Signature | Buffer, sigtype: number): Script;
         function buildPublicKeyHashIn(publicKey: PublicKey, signature: crypto.Signature | Buffer, sigtype: number): Script;
@@ -457,7 +479,7 @@ declare module '@smartledger/bsv' {
 
         function add(data: any): Network;
         function remove(network: Network): void;
-        function get(args: string | number | Network, keys: string | string[]): Network;
+        function get(args: string | number | Network, keys?: string | string[]): Network;
     }
 
     export class Address {
@@ -613,27 +635,55 @@ declare module '@smartledger/bsv' {
 
     // -------- StatusList2021 --------------------------------------------
 
-    export type CredentialStatus = 'valid' | 'revoked' | 'suspended' | string;
+    /**
+     * 'suspended' is part of the StatusList2021 vocabulary but is NOT writable here:
+     * this implementation hardcodes statusPurpose 'revocation' and uses one bit, so
+     * updateStatusList throws on it rather than recording a suspension as a revocation.
+     */
+    export type CredentialStatus = 'valid' | 'revoked' | 'suspended';
 
     export namespace StatusList {
+        /**
+         * Reading revocation state verifies the list JWT's signature and pins its issuer;
+         * both are required and were previously absent from these declarations.
+         */
+        interface StatusListReadParams {
+            listVcJwt: string;
+            index: number;
+            /** Required: the issuer this list must be signed by. */
+            expectedIssuerDid: string;
+            /** Supply exactly one key source. */
+            didResolver?: (did: string) => Promise<{ jwks: { keys: Jwk[] } }>;
+            issuerJwks?: { keys: Jwk[] };
+            issuerPublicJwk?: Jwk;
+            allowedAlgs?: string[];
+        }
         function createStatusList(params: {
             issuerDid: string;
             privateJwk: Jwk;
             listId?: string;
             listSize?: number;
         }): Promise<{ listVcJwt: string; listId: string }>;
-        function updateStatusList(params: {
-            listVcJwt: string;
-            index: number;
+        /**
+         * Verifying the existing list before building on it requires pinning its issuer,
+         * so `expectedIssuerDid` plus one key source are mandatory at runtime.
+         */
+        function updateStatusList(params: StatusListReadParams & {
             status: CredentialStatus;
             privateJwk: Jwk;
         }): Promise<{ listVcJwt: string }>;
-        function getCredentialStatusEntry(params: { listVcJwt: string; index: number }): CredentialStatus;
+        /**
+         * ASYNC — returns a Promise. Declared synchronous until 7.5.2, which meant
+         * `if (getCredentialStatusEntry(...) === 'revoked')` type-checked and was ALWAYS
+         * false, so every revoked credential passed. Await it.
+         */
+        function getCredentialStatusEntry(params: StatusListReadParams): Promise<CredentialStatus>;
     }
 
     // -------- Anchor (top-level hash anchoring) -------------------------
 
-    export type AnchorKind = 'VC_ANCHOR_SHA256' | 'STATUSLIST_SHA256' | 'PRESENTATION_SHA256' | string;
+    /** Closed set: the runtime rejects anything else with "Invalid kind. Must be one of: ...". */
+    export type AnchorKind = 'VC_ANCHOR_SHA256' | 'STATUSLIST_SHA256' | 'PRESENTATION_SHA256';
 
     export interface AnchorPayload {
         json: object;
@@ -712,6 +762,24 @@ declare module '@smartledger/bsv' {
 
     // -------- GDAF (Global Digital Attestation Framework) ---------------
 
+    /** A spendable output supplied to the anchoring helpers. */
+    export interface Utxo {
+        txId: string;
+        outputIndex: number;
+        script: string;
+        satoshis: number;
+    }
+
+    export interface AnchorOptions {
+        /** UTXOs funding the anchor transaction. */
+        utxos?: Utxo[];
+        /**
+         * Serialised into the OP_RETURN: PUBLIC AND PERMANENT. Anchoring a PrivateKey, or
+         * any key-shaped field (`bn`, `wif`, `privateJwk`, `seed`, `xprv`, ...), throws.
+         */
+        metadata?: object;
+    }
+
     export class GDAF {
         constructor(options?: {
             attestationSigner?: object;
@@ -747,10 +815,15 @@ declare module '@smartledger/bsv' {
         verifyMembershipProof(proof: object, validSet: string[]): boolean;
 
         // Anchoring
-        anchorCredential(credential: object, privateKey: PrivateKey, options?: object): object;
-        anchorBatch(credentials: object[], privateKey: PrivateKey, options?: object): object;
-        registerDID(did: string, didDocument: object, privateKey: PrivateKey, options?: object): object;
-        revokeCredential(credentialId: string, reason: string, privateKey: PrivateKey, options?: object): object;
+        /**
+         * Anchor options. `metadata` is JSON-serialised into the OP_RETURN and is therefore
+         * PUBLIC AND PERMANENT — anchoring anything key-shaped throws. A bare UTXO array is
+         * also accepted in place of this object.
+         */
+        anchorCredential(credentialHash: string | Buffer, privateKey: PrivateKey, options?: AnchorOptions | Utxo[]): Promise<object>;
+        anchorBatch(credentialHashes: Array<string | Buffer>, privateKey: PrivateKey, options?: AnchorOptions | Utxo[]): Promise<object>;
+        registerDID(did: string, didDocument: object, privateKey: PrivateKey, options?: AnchorOptions | Utxo[]): Promise<object>;
+        revokeCredential(credentialId: string, reason: string, privateKey: PrivateKey, options?: AnchorOptions | Utxo[]): Promise<object>;
         queryAnchoredData(hash: string): object;
 
         // Schemas
@@ -908,7 +981,8 @@ declare module '@smartledger/bsv' {
         /** Perpetually Enforcing Locking Script: every spend recreates the same script (value - fee). */
         function perpetualCovenant(fee: number): Script;
         /** Stateful ownership token (NFT) locking script. */
-        function ownershipToken(fee: number, ownerHash: Buffer): Script;
+        /** Alias of SmartContract.Token.ownershipToken, authorizer included. */
+        function ownershipToken(fee: number, ownerHash: Buffer, auth?: SmartContract.Authorizer): 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). */
@@ -975,8 +1049,12 @@ declare module '@smartledger/bsv' {
         namespace Authorizers {
             /** Single-key (default): owner id = HASH160(pubkey). */
             function singleKey(): Authorizer;
-            /** m-of-n multisig authorizer. */
-            function multisig(m: number, keys: PublicKey[]): Authorizer;
+            /**
+             * m-of-n multisig authorizer. `nKeys` is the NUMBER of keys, not the keys —
+             * the descriptor supplies them at spend time. (Locks.multisig genuinely does
+             * take keys, which is what made this easy to walk into.)
+             */
+            function multisig(m: number, nKeys: number): Authorizer;
             /** Arbitrary predicate authorizer over a fixed 20-byte commitment. */
             function predicate(commit: Buffer, emit: (script: Script) => Script): Authorizer;
         }
@@ -1326,7 +1404,8 @@ declare module '@smartledger/bsv' {
     export function getClaimSchemaNames(): string[];
     export function getClaimSchema(schemaName: string): object;
     export function createClaimTemplate(schemaName: string): object;
-    export function canonicalizeClaim(claim: object): object;
+    /** Returns the canonical JSON STRING, not an object. */
+    export function canonicalizeClaim(claim: object): string;
     export function hashClaim(claim: object): string;
     export function addCustomClaimSchema(name: string, schema: object): void;