@did-btcr2/api 0.2.1 → 0.2.2

package/dist/types/api.d.ts

@@ -1,95 +1,628 @@
-import { BitcoinCoreRpcClient, BitcoinNetworkConnection, BitcoinRestClient, BlockV3, RawTransactionV2, RestClientConfigParams, RpcClientConfig } from '@did-btcr2/bitcoin';
+import { BitcoinConnection, BitcoinCoreRpcClient, BitcoinRestClient, type BlockV3, type HttpExecutor, type NetworkName, type RawTransactionRest, type RawTransactionV2, type RestConfig, type RpcConfig } from '@did-btcr2/bitcoin';
 import type { Bytes, CryptosuiteName, DocumentBytes, Entropy, HashBytes, Hex, HexString, JSONObject, KeyBytes, PatchOperation, ProofBytes, SchnorrKeyPairObject, SignatureBytes } from '@did-btcr2/common';
 import { IdentifierTypes } from '@did-btcr2/common';
-import type { MultikeyObject, SignedBTCR2Update } from '@did-btcr2/cryptosuite';
-import { SchnorrMultikey } from '@did-btcr2/cryptosuite';
-import { SchnorrKeyPair } from '@did-btcr2/keypair';
-import type { Btcr2DidDocument, DidCreateOptions, ResolutionOptions, SidecarData } from '@did-btcr2/method';
-import { DidDocument, DidDocumentBuilder, Identifier } from '@did-btcr2/method';
-import type { DidResolutionResult, DidService, DidVerificationMethod } from '@web5/dids';
+import { BIP340Cryptosuite, BIP340DataIntegrityProof, BTCR2Update, DataIntegrityConfig, DataIntegrityProofObject, type FromPublicKey, type Multikey, MultikeyObject, SchnorrMultikey, SignedBTCR2Update, UnsignedBTCR2Update, VerificationResult } from '@did-btcr2/cryptosuite';
+import { CompressedSecp256k1PublicKey, SchnorrKeyPair, Secp256k1SecretKey } from '@did-btcr2/keypair';
+import { type GenerateKeyOptions, type ImportKeyOptions, KeyIdentifier, KeyManager, type SignOptions } from '@did-btcr2/kms';
+import type { Btcr2DidDocument, DidCreateOptions, ResolutionOptions } from '@did-btcr2/method';
+import { DidDocument, DidDocumentBuilder, Identifier, IdentifierComponents } from '@did-btcr2/method';
+import { Did, type DidResolutionResult, type DidService, type DidVerificationMethod } from '@web5/dids';
 export { DidDocument, DidDocumentBuilder, Identifier, IdentifierTypes };
-export type { BlockV3, Bytes, CryptosuiteName, DidResolutionResult, DidService, DidVerificationMethod, DocumentBytes, HashBytes, Hex, JSONObject, KeyBytes, MultikeyObject, PatchOperation, ProofBytes, RawTransactionV2, RestClientConfigParams, RpcClientConfig, SchnorrKeyPairObject, SignatureBytes };
-export type NetworkName = 'mainnet' | 'testnet4' | 'signet' | 'regtest';
+export type { BlockV3, Bytes, CryptosuiteName, DidResolutionResult, DidService, DidVerificationMethod, DocumentBytes, HashBytes, Hex, HttpExecutor, JSONObject, KeyBytes, MultikeyObject, NetworkName, PatchOperation, ProofBytes, RawTransactionV2, RestConfig, RpcConfig, SchnorrKeyPairObject, SignatureBytes };
+/**
+ * Pluggable logger interface. All methods are optional-call; the default
+ * implementation is a silent no-op.
+ * @public
+ */
+export type Logger = {
+    debug(message: string, ...args: unknown[]): void;
+    info(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+    error(message: string, ...args: unknown[]): void;
+};
+/**
+ * The two supported DID identifier types.
+ *
+ * Note: the upstream `DidCreateOptions.idType` is typed as `string` rather
+ * than a union. This local alias provides compile-time safety at the API
+ * facade level. Upstream runtime validation in `Identifier.encode()` still
+ * catches invalid values.
+ * @public
+ */
+export type IdType = 'KEY' | 'EXTERNAL';
+/**
+ * A branded string representing a DID identifier (e.g. `did:btcr2:k1q...`).
+ * Use branded types to prevent accidentally passing a txid where a DID is
+ * expected, or vice versa, at compile time.
+ *
+ * @example
+ * ```ts
+ * const did = api.generateDid().did as DidString;
+ * api.resolveDid(did); // OK
+ * api.btc.getTransaction(did); // Type error — DidString is not TxId
+ * ```
+ * @public
+ */
+export type DidString = string & {
+    readonly __brand: 'DidString';
+};
+/**
+ * A branded string representing a Bitcoin transaction ID (64-char hex).
+ * @public
+ */
+export type TxId = string & {
+    readonly __brand: 'TxId';
+};
+/**
+ * Result of a DID resolution attempt. Wraps the standard
+ * {@link DidResolutionResult} with a discriminated `ok` flag for ergonomic
+ * pattern matching without exception handling.
+ *
+ * @example
+ * ```ts
+ * const result = await api.tryResolveDid(did);
+ * if (result.ok) {
+ *   console.log(result.document);
+ * } else {
+ *   console.log(result.error, result.errorMessage);
+ * }
+ * ```
+ * @public
+ */
+export type ResolutionResult = {
+    ok: true;
+    document: Btcr2DidDocument;
+    metadata: DidResolutionResult['didDocumentMetadata'];
+    raw: DidResolutionResult;
+} | {
+    ok: false;
+    error: string;
+    errorMessage?: string;
+    raw: DidResolutionResult;
+};
+/**
+ * Bitcoin API configuration options.
+ * The `network` field is required and determines default REST/RPC endpoints.
+ * Optional `rest` and `rpc` fields override individual endpoints on top of
+ * the network defaults.
+ *
+ * @example
+ * ```ts
+ * // Use regtest defaults (localhost Polar + Esplora)
+ * { network: 'regtest' }
+ *
+ * // Use testnet4 with a custom REST endpoint
+ * { network: 'testnet4', rest: { host: 'https://my-mempool.example/api' } }
+ *
+ * // Use regtest with custom RPC credentials, default REST
+ * { network: 'regtest', rpc: { host: 'http://mynode:18443', username: 'u', password: 'p' } }
+ * ```
+ * @public
+ */
 export type BitcoinApiConfig = {
-    /** Shortcut to compute base URLs and params via @did-btcr2/bitcoin getNetwork */
-    network?: NetworkName;
-    /** Override REST client settings */
-    rest?: RestClientConfigParams;
-    /** Override RPC client settings */
-    rpc?: RpcClientConfig;
-    /** Default number of confirmations to consider "final" */
-    defaultConfirmations?: number;
+    /** Bitcoin network name (e.g., 'regtest', 'testnet4', 'bitcoin'). */
+    network: NetworkName;
+    /** Override REST client settings on top of network defaults. */
+    rest?: Partial<RestConfig>;
+    /** Override RPC client settings on top of network defaults. */
+    rpc?: RpcConfig;
+    /**
+     * Optional HTTP executor for sans-I/O usage. Defaults to global `fetch`.
+     * Inject a custom executor to intercept requests in tests or route through
+     * a proxy without monkey-patching globals.
+     */
+    executor?: HttpExecutor;
+    /**
+     * Optional request timeout in milliseconds for REST calls.
+     * When set, wraps the HTTP executor with an `AbortSignal.timeout()`.
+     * Has no effect when a custom `executor` is provided (the custom
+     * executor is responsible for its own timeouts).
+     */
+    timeoutMs?: number;
 };
+/**
+ * Top-level API configuration options.
+ * @public
+ */
 export type ApiConfig = {
-    bitcoin?: BitcoinApiConfig;
+    btc?: BitcoinApiConfig;
+    kms?: KeyManager;
+    /** Optional logger. Defaults to a silent no-op logger. */
+    logger?: Logger;
 };
+/**
+ * Schnorr keypair operations.
+ * @public
+ */
 export declare class KeyPairApi {
-    /** Generate a new Schnorr keypair (secp256k1). */
-    static generate(): SchnorrKeyPair;
-    /** Import from secret key bytes or bigint. */
-    static fromSecret(ent: Entropy): SchnorrKeyPair;
+    /**
+     * Generate a new Schnorr keypair.
+     * @returns The generated Schnorr keypair.
+     */
+    generate(): SchnorrKeyPair;
+    /**
+     * Create a Schnorr keypair from secret key bytes or hex string.
+     * @param data The secret key bytes or hex string.
+     * @returns The created Schnorr keypair.
+     */
+    fromSecret(data: KeyBytes | HexString): SchnorrKeyPair;
+    /** Create a secret key from entropy (bytes or bigint). */
+    secretKeyFrom(ent: Entropy): Secp256k1SecretKey;
+    /** Create a compressed public key from bytes. */
+    publicKeyFrom(byt: Bytes): CompressedSecp256k1PublicKey;
+    /** Deserialize a keypair from a JSON object. */
+    fromJSON(obj: SchnorrKeyPairObject): SchnorrKeyPair;
+    /** Serialize a keypair to a JSON object. */
+    toJSON(kp: SchnorrKeyPair): SchnorrKeyPairObject;
+    /** Compare two keypairs for equality. */
+    equals(kp1: SchnorrKeyPair, kp2: SchnorrKeyPair): boolean;
+}
+/**
+ * Schnorr cryptosuite operations.
+ *
+ * Optionally stateful: call {@link use} to set a current cryptosuite, then
+ * call {@link createProof}, {@link verifyProof}, or {@link toDataIntegrityProof}
+ * without passing an explicit instance. Pass an explicit instance to any
+ * method to override the current one for that call.
+ * @public
+ */
+export declare class CryptosuiteApi {
+    #private;
+    /** The currently active cryptosuite, or `undefined` if none is set. */
+    get current(): BIP340Cryptosuite | undefined;
+    /**
+     * Set the current cryptosuite for subsequent operations.
+     * @param cs The cryptosuite to activate.
+     * @returns `this` for chaining.
+     */
+    use(cs: BIP340Cryptosuite): this;
+    /** Clear the current cryptosuite. */
+    clear(): void;
+    /**
+     * Create a new Schnorr cryptosuite from a multikey.
+     * @param multikey The Schnorr multikey to use.
+     * @returns The created Schnorr cryptosuite.
+     */
+    create(multikey: SchnorrMultikey): BIP340Cryptosuite;
+    /**
+     * Convenience: resolve a key from the KMS and create a cryptosuite in one step.
+     * @param id The multikey ID (e.g. '#initialKey').
+     * @param controller The DID that controls this key.
+     * @param keyId The KMS key identifier to resolve.
+     * @param kms The KeyManagerApi instance holding the key.
+     * @returns The created Schnorr cryptosuite.
+     */
+    createFromKms(id: string, controller: string, keyId: KeyIdentifier, kms: KeyManagerApi): BIP340Cryptosuite;
+    /**
+     * Convert a cryptosuite to a Data Integrity Proof instance.
+     * Uses the current cryptosuite when `cryptosuite` is omitted.
+     * @param cryptosuite Optional explicit cryptosuite to convert.
+     * @returns The Data Integrity Proof instance.
+     */
+    toDataIntegrityProof(cryptosuite?: BIP340Cryptosuite): BIP340DataIntegrityProof;
+    /**
+     * Create a proof for a document.
+     * Uses the current cryptosuite when `cryptosuite` is omitted.
+     * @param document The document to create the proof for.
+     * @param config Configuration for the proof creation.
+     * @param cryptosuite Optional explicit cryptosuite; defaults to current.
+     * @returns The created proof.
+     */
+    createProof(document: BTCR2Update, config: DataIntegrityConfig, cryptosuite?: BIP340Cryptosuite): DataIntegrityProofObject;
+    /**
+     * Verify a proof for a document.
+     * Uses the current cryptosuite when `cryptosuite` is omitted.
+     * @param document The document to verify the proof for.
+     * @param cryptosuite Optional explicit cryptosuite; defaults to current.
+     * @returns The full verification result.
+     */
+    verifyProof(document: SignedBTCR2Update, cryptosuite?: BIP340Cryptosuite): VerificationResult;
 }
+/**
+ * Data Integrity Proof operations.
+ *
+ * Optionally stateful: call {@link use} to set a current proof instance, then
+ * call {@link addProof} or {@link verifyProof} without passing an explicit
+ * instance. Pass an explicit instance to override for that call.
+ * @public
+ */
+export declare class DataIntegrityProofApi {
+    #private;
+    /** The currently active proof instance, or `undefined` if none is set. */
+    get current(): BIP340DataIntegrityProof | undefined;
+    /**
+     * Set the current proof instance for subsequent operations.
+     * @param p The proof instance to activate.
+     * @returns `this` for chaining.
+     */
+    use(p: BIP340DataIntegrityProof): this;
+    /** Clear the current proof instance. */
+    clear(): void;
+    /**
+     * Create a BIP340DataIntegrityProof instance with the given cryptosuite.
+     * @param cryptosuite The cryptosuite to use for proof operations.
+     * @returns The created BIP340DataIntegrityProof instance.
+     */
+    create(cryptosuite: BIP340Cryptosuite): BIP340DataIntegrityProof;
+    /**
+     * Add a proof to a document.
+     * Uses the current proof instance when `proof` is omitted.
+     * @param document The document to add the proof to.
+     * @param config Configuration for adding the proof.
+     * @param proof Optional explicit proof instance; defaults to current.
+     * @returns A document with a proof added.
+     */
+    addProof(document: UnsignedBTCR2Update, config: DataIntegrityConfig, proof?: BIP340DataIntegrityProof): SignedBTCR2Update;
+    /**
+     * Convenience: create a cryptosuite, proof instance, and sign a document
+     * in one call. Requires a multikey with signing capability.
+     * @param multikey The Schnorr multikey (must include secret key).
+     * @param document The unsigned document to sign.
+     * @param config The Data Integrity proof configuration.
+     * @returns The signed document with proof attached.
+     */
+    signDocument(multikey: SchnorrMultikey, document: UnsignedBTCR2Update, config: DataIntegrityConfig): SignedBTCR2Update;
+    /**
+     * Verify a proof using a BIP340DataIntegrityProof instance.
+     * Uses the current proof instance when `proof` is omitted.
+     * @param document The document to verify the proof for.
+     * @param expectedPurpose The expected proof purpose.
+     * @param mediaType The media type of the document.
+     * @param expectedDomain The expected domain for the proof.
+     * @param expectedChallenge The expected challenge for the proof.
+     * @param proof Optional explicit proof instance; defaults to current.
+     * @returns The result of verifying the proof.
+     */
+    verifyProof(document: string, expectedPurpose: string, mediaType?: string, expectedDomain?: string, expectedChallenge?: string, proof?: BIP340DataIntegrityProof): VerificationResult;
+}
+/**
+ * Schnorr multikey operations.
+ *
+ * Optionally stateful: call {@link use} to set a current multikey, then
+ * call {@link sign}, {@link verify}, or {@link toVerificationMethod} without
+ * passing an explicit instance. Pass an explicit instance to any method to
+ * override the current one for that call.
+ * @public
+ */
 export declare class MultikeyApi {
+    #private;
+    /** The currently active multikey, or `undefined` if none is set. */
+    get current(): SchnorrMultikey | undefined;
+    /**
+     * Set the current multikey for subsequent operations.
+     * @param mk The multikey to activate.
+     * @returns `this` for chaining.
+     */
+    use(mk: SchnorrMultikey): this;
+    /** Clear the current multikey. */
+    clear(): void;
+    /**
+     * Create a new Schnorr multikey from a keypair.
+     * @param id The multikey ID.
+     * @param controller The multikey controller.
+     * @param keyPair The Schnorr keypair to use.
+     * @returns The created Schnorr multikey.
+     */
+    create(id: string, controller: string, keyPair: SchnorrKeyPair): SchnorrMultikey;
+    /**
+     * Create a Schnorr multikey from raw secret key bytes.
+     * @param id The multikey ID.
+     * @param controller The multikey controller.
+     * @param secretKeyBytes The secret key bytes.
+     * @returns The created Schnorr multikey.
+     */
+    fromSecretKey(id: string, controller: string, secretKeyBytes: Bytes): SchnorrMultikey;
+    /**
+     * Create a verification-only multikey from public key bytes.
+     * @param params The id, controller, and publicKeyBytes.
+     * @returns The created Multikey.
+     */
+    fromPublicKey(params: FromPublicKey): Multikey;
+    /**
+     * Convenience: resolve a key from the KMS and create a multikey in one step.
+     * @param id The multikey ID.
+     * @param controller The multikey controller DID.
+     * @param keyId The KMS key identifier to resolve.
+     * @param kms The KeyManagerApi instance holding the key.
+     * @returns The created Multikey (verification-only; public key from KMS).
+     */
+    fromKms(id: string, controller: string, keyId: KeyIdentifier, kms: KeyManagerApi): Multikey;
+    /**
+     * Reconstruct a multikey from a DID document's verification method.
+     * @param verificationMethod The verification method to convert.
+     * @returns The reconstructed multikey.
+     */
+    fromVerificationMethod(verificationMethod: DidVerificationMethod): SchnorrMultikey;
     /**
-     * Create a Schnorr Multikey wrapper (includes verificationMethod, sign/verify).
-     * If secret is present, the multikey can sign.
-     */
-    static create(params: {
-        id: string;
-        controller: string;
-        keys: SchnorrKeyPair;
-    }): SchnorrMultikey;
-    /** Produce a DID Verification Method JSON from a multikey. */
-    static toVerificationMethod(mk: SchnorrMultikey): DidVerificationMethod;
-    /** Sign bytes via the multikey (requires secret). */
-    static sign(mk: SchnorrMultikey, data: Bytes): Promise<SignatureBytes>;
-    /** Verify signature via multikey. */
-    static verify(mk: SchnorrMultikey, data: Bytes, signature: SignatureBytes): Promise<boolean>;
+     * Produce a DID Verification Method JSON from a multikey.
+     * Uses the current multikey when `mk` is omitted.
+     * @param mk Optional explicit multikey; defaults to current.
+     */
+    toVerificationMethod(mk?: SchnorrMultikey): DidVerificationMethod;
+    /**
+     * Sign bytes via the multikey (requires secret).
+     * Uses the current multikey when `mk` is omitted.
+     * @param data The data to sign.
+     * @param mk Optional explicit multikey; defaults to current.
+     */
+    sign(data: Bytes, mk?: SchnorrMultikey): SignatureBytes;
+    /**
+     * Verify signature via multikey.
+     * Uses the current multikey when `mk` is omitted.
+     * @param data The data that was signed.
+     * @param signature The signature to verify.
+     * @param mk Optional explicit multikey; defaults to current.
+     */
+    verify(data: Bytes, signature: SignatureBytes, mk?: SchnorrMultikey): boolean;
 }
+/**
+ * Aggregated cryptographic operations sub-facade.
+ *
+ * Provides direct access to the four sub-facades ({@link keypair},
+ * {@link multikey}, {@link cryptosuite}, {@link proof}) plus top-level
+ * convenience methods that orchestrate the full signing/verification
+ * pipeline using their stateful defaults.
+ *
+ * @example Stateful pipeline
+ * ```ts
+ * const api = createApi();
+ * const kp  = api.crypto.keypair.generate();
+ * const mk  = api.crypto.multikey.create('#key-1', 'did:btcr2:test', kp);
+ *
+ * // Set the active multikey — flows through to cryptosuite and proof
+ * api.crypto.activate(mk);
+ *
+ * // Now sign without threading instances
+ * const signed = api.crypto.signDocument(unsignedDoc, proofConfig);
+ * ```
+ * @public
+ */
 export declare class CryptoApi {
-    static keyPairApi: KeyPairApi;
-    static multikeyApi: MultikeyApi;
+    /** Schnorr keypair operations. */
+    readonly keypair: KeyPairApi;
+    /** Schnorr Multikey operations (optionally stateful). */
+    readonly multikey: MultikeyApi;
+    /** Schnorr Cryptosuite operations (optionally stateful). */
+    readonly cryptosuite: CryptosuiteApi;
+    /** Data Integrity Proof operations (optionally stateful). */
+    readonly proof: DataIntegrityProofApi;
+    /**
+     * Activate a multikey and propagate through the full pipeline.
+     * Sets the current multikey, creates a cryptosuite from it, and creates
+     * a proof instance from the cryptosuite — all three sub-facades become
+     * ready for stateful operations.
+     * @param mk The multikey to activate (must include a secret key for signing).
+     * @returns `this` for chaining.
+     */
+    activate(mk: SchnorrMultikey): this;
+    /**
+     * Clear stateful defaults from all sub-facades.
+     */
+    deactivate(): void;
+    /**
+     * Sign data using the current multikey.
+     * Shorthand for `crypto.multikey.sign(data)`.
+     * @param data The data to sign.
+     * @returns The signature bytes.
+     */
+    sign(data: Bytes): SignatureBytes;
+    /**
+     * Verify a signature using the current multikey.
+     * Shorthand for `crypto.multikey.verify(data, signature)`.
+     * @param data The data that was signed.
+     * @param signature The signature to verify.
+     * @returns `true` if the signature is valid.
+     */
+    verify(data: Bytes, signature: SignatureBytes): boolean;
+    /**
+     * Sign a BTCR2 update document using the current proof instance.
+     * Shorthand for `crypto.proof.addProof(document, config)`.
+     *
+     * Requires {@link activate} to have been called first, or the three
+     * sub-facades to have been configured individually.
+     * @param document The unsigned BTCR2 update document.
+     * @param config The Data Integrity proof configuration.
+     * @returns The signed document with proof attached.
+     */
+    signDocument(document: UnsignedBTCR2Update, config: DataIntegrityConfig): SignedBTCR2Update;
+    /**
+     * Verify a signed BTCR2 update document using the current cryptosuite.
+     * Shorthand for `crypto.cryptosuite.verifyProof(document)`.
+     * @param document The signed document to verify.
+     * @returns The full verification result.
+     */
+    verifyDocument(document: SignedBTCR2Update): VerificationResult;
 }
+/**
+ * Bitcoin network operations sub-facade.
+ * Always backed by a {@link BitcoinConnection} so it can be passed to
+ * resolve/update without extra configuration.
+ *
+ * Lazily initialized by {@link DidBtcr2Api} to avoid connection overhead
+ * when Bitcoin features are not used.
+ * @public
+ */
 export declare class BitcoinApi {
-    readonly rest: BitcoinRestClient;
-    readonly rpc: BitcoinCoreRpcClient;
-    readonly defaultConfirmations: number;
-    constructor(cfg?: BitcoinApiConfig);
-    /** Fetch a transaction by txid via REST. */
-    getTransaction(txid: string): Promise<import("@did-btcr2/bitcoin").RawTransactionRest>;
-    /** Broadcast a raw tx (hex) via REST. */
+    /** The underlying BitcoinConnection used for all operations. */
+    readonly connection: BitcoinConnection;
+    /** REST client for the active network. */
+    get rest(): BitcoinRestClient;
+    /**
+     * RPC client for the active network, or `undefined` if not configured.
+     * Use {@link requireRpc} when RPC is expected to be available.
+     */
+    get rpc(): BitcoinCoreRpcClient | undefined;
+    /** Whether an RPC client is available for this network. */
+    get hasRpc(): boolean;
+    /**
+     * RPC client for the active network.
+     * @throws {Error} If RPC was not configured for this network.
+     */
+    requireRpc(): BitcoinCoreRpcClient;
+    /**
+     * Create a BitcoinApi for a specific network with optional endpoint overrides.
+     * Uses BitcoinConnection.forNetwork() — no env vars consulted.
+     * @param cfg The network and optional REST/RPC overrides.
+     */
+    constructor(cfg: BitcoinApiConfig);
+    /**
+     * Fetch a transaction by txid via REST.
+     * @param txid The transaction ID (64-character hex string).
+     * @returns The fetched transaction.
+     */
+    getTransaction(txid: string): Promise<RawTransactionRest>;
+    /**
+     * Broadcast a raw tx (hex) via REST.
+     * @param rawTxHex The raw transaction hex string.
+     */
     send(rawTxHex: string): Promise<string>;
-    /** Get UTXOs for an address via REST. */
+    /**
+     * Get UTXOs for an address via REST.
+     * @param address The Bitcoin address.
+     */
     getUtxos(address: string): Promise<import("@did-btcr2/bitcoin").AddressUtxo[]>;
-    /** Get a block by hash or height via REST. */
+    /**
+     * Get a block by hash or height via REST.
+     * @param params Block identifier — at least one of `hash` or `height` is required.
+     */
     getBlock(params: {
         hash?: string;
         height?: number;
-    }): Promise<import("@did-btcr2/bitcoin").BlockResponse | undefined>;
+    }): Promise<import("@did-btcr2/bitcoin").EsploraBlock | undefined>;
+    /** Convert BTC to satoshis (integer-safe string-split arithmetic). */
+    static btcToSats(btc: number): number;
+    /** Convert satoshis to BTC (integer-safe string-split arithmetic). */
+    static satsToBtc(sats: number): number;
 }
+/**
+ * Key management operations sub-facade.
+ *
+ * Wraps a {@link KeyManager} interface. By default uses the built-in
+ * {@link Kms} implementation; a custom implementation can be injected
+ * via {@link ApiConfig}.
+ * @public
+ */
+export declare class KeyManagerApi {
+    /** The backing KeyManager instance. */
+    readonly kms: KeyManager;
+    /** Create a new KeyManagerApi, optionally backed by a custom KeyManager. */
+    constructor(kms?: KeyManager);
+    /** Generate a new key directly in the KMS. */
+    generateKey(options?: GenerateKeyOptions): KeyIdentifier;
+    /** Set the active key by its identifier. */
+    setActive(id: KeyIdentifier): void;
+    /** Get the public key bytes for a key identifier. */
+    getPublicKey(id?: KeyIdentifier): Bytes;
+    /** Import a Schnorr keypair into the KMS. */
+    import(kp: SchnorrKeyPair, options?: ImportKeyOptions): KeyIdentifier;
+    /**
+     * Export a Schnorr keypair from the KMS.
+     * Only supported when the backing KMS is the built-in {@link Kms} class.
+     * @throws {Error} If the backing KMS does not support key export.
+     */
+    export(id: KeyIdentifier): SchnorrKeyPair;
+    /** List all managed key identifiers. */
+    listKeys(): KeyIdentifier[];
+    /** Remove a key from the KMS. */
+    removeKey(id: KeyIdentifier, options?: {
+        force?: boolean;
+    }): void;
+    /**
+     * Sign data via the KMS.
+     * @param data The data to sign (must be non-empty).
+     * @param id Optional key identifier; uses the active key if omitted.
+     * @param options Signing options (scheme defaults to 'schnorr').
+     */
+    sign(data: Bytes, id?: KeyIdentifier, options?: SignOptions): SignatureBytes;
+    /** Verify a signature via the KMS. */
+    verify(signature: SignatureBytes, data: Bytes, id?: KeyIdentifier, options?: SignOptions): boolean;
+    /** Compute a SHA-256 digest. */
+    digest(data: Uint8Array): HashBytes;
+}
+/**
+ * DID identifier operations sub-facade (encode, decode, generate, parse).
+ * @public
+ */
 export declare class DidApi {
     /**
-     * Create a deterministic DID from a public key (bytes).
+     * Encode a DID from genesis bytes and options.
+     * @param genesisBytes The genesis document bytes.
+     * @param options The creation options.
+     * @returns The encoded DID string.
+     */
+    encode(genesisBytes: DocumentBytes, options: DidCreateOptions): string;
+    /**
+     * Decode a DID into its components.
+     * @param did The DID string to decode.
+     * @returns The decoded identifier components.
+     */
+    decode(did: string): IdentifierComponents;
+    /**
+     * Generate a new DID along with its keypair.
+     *
+     * When no `network` is given, defaults to `'regtest'` (upstream default).
+     * Pass an explicit network to generate DIDs for other networks.
+     *
+     * @param network Optional network to generate the DID for.
+     * @returns The generated keypair and DID string.
+     */
+    generate(network?: NetworkName): {
+        keyPair: SchnorrKeyPairObject;
+        did: string;
+    };
+    /**
+     * Check if a DID string is valid.
+     * @param did The DID string to validate.
+     * @returns `true` if valid, `false` otherwise.
+     */
+    isValid(did: string): boolean;
+    /**
+     * Parse a DID string into a Did instance.
+     * @param did The DID string to parse.
+     * @returns The parsed Did instance, or `null` if parsing failed.
+     */
+    parse(did: string): Did | null;
+}
+/**
+ * DID method operations sub-facade: create, resolve, update, deactivate.
+ *
+ * Lazily initialized by {@link DidBtcr2Api} because it depends on
+ * {@link BitcoinApi} which requires network configuration.
+ * @public
+ */
+export declare class DidMethodApi {
+    #private;
+    constructor(btc?: BitcoinApi, logger?: Logger);
+    /**
+     * Create a deterministic (k1) DID from a public key.
+     * Sets idType to KEY automatically.
+     * @param genesisBytes The compressed public key bytes (33 bytes).
+     * @param options Creation options (idType is set for you).
+     * @returns The created DID identifier string.
      */
-    createDeterministic({ genesisBytes, options }: {
-        genesisBytes: KeyBytes;
-        options: DidCreateOptions;
-    }): Promise<string>;
+    createDeterministic(genesisBytes: KeyBytes, options?: Omit<DidCreateOptions, 'idType'>): string;
     /**
-     * Create from an intermediate DID document (external genesis).
+     * Create a non-deterministic (x1) DID from external genesis document bytes.
+     * Sets idType to EXTERNAL automatically.
+     * @param genesisBytes The genesis document bytes.
+     * @param options Creation options (idType is set for you).
+     * @returns The created DID identifier string.
      */
-    createExternal({ genesisBytes, options }: {
-        genesisBytes: DocumentBytes;
-        options: DidCreateOptions;
-    }): Promise<string>;
+    createExternal(genesisBytes: DocumentBytes, options?: Omit<DidCreateOptions, 'idType'>): string;
     /**
-     * Resolve DID document from DID (did:btcr2:...).
+     * Resolve a DID. If a Bitcoin connection is configured on the API, it is
+     * injected automatically as the driver — unless the caller explicitly
+     * provides `drivers.bitcoin` (even as `undefined`) in the options.
+     * @param did The DID to resolve.
+     * @param options Resolution options.
+     * @returns The resolution result.
      */
-    resolve(did: string, options: ResolutionOptions): Promise<DidResolutionResult>;
+    resolve(did: string, options?: ResolutionOptions): Promise<DidResolutionResult>;
     /**
-     * Update a DID Document using a JSON Patch, signed as capabilityInvocation.
-     * You provide the prior DID Document (to pick VM), a JSON Patch, and a signer multikey.
-     * This delegates to MethodUpdate (which follows the cryptosuite rules internally).
+     * Update an existing DID document. If a Bitcoin connection is configured on
+     * the API, it is injected automatically.
+     * @param params The update parameters.
+     * @returns The signed update.
      */
     update({ sourceDocument, patches, sourceVersionId, verificationMethodId, beaconId, signingMaterial, bitcoin, }: {
         sourceDocument: Btcr2DidDocument;
@@ -98,16 +631,167 @@ export declare class DidApi {
         verificationMethodId: string;
         beaconId: string;
         signingMaterial?: KeyBytes | HexString;
-        bitcoin?: BitcoinNetworkConnection;
+        bitcoin?: BitcoinConnection;
     }): Promise<SignedBTCR2Update>;
-    /** Deactivate convenience: applies the standard `deactivated: true` patch. */
-    deactivate(): Promise<SidecarData>;
+    /**
+     * Get the signing method from a DID document by method ID.
+     * @param didDocument The DID document.
+     * @param methodId The method ID (if omitted, the first signing method is returned).
+     * @returns The found signing method.
+     */
+    getSigningMethod(didDocument: Btcr2DidDocument, methodId?: string): DidVerificationMethod;
+    /**
+     * Create a fluent builder for a DID update operation.
+     * @param sourceDocument The current DID document to update.
+     * @returns An {@link UpdateBuilder} for chaining update parameters.
+     *
+     * @example
+     * ```ts
+     * const signed = await api.btcr2
+     *   .buildUpdate(currentDoc)
+     *   .patch({ op: 'add', path: '/service/1', value: newService })
+     *   .version(2)
+     *   .signer('#initialKey')
+     *   .beacon('#beacon-0')
+     *   .execute();
+     * ```
+     */
+    buildUpdate(sourceDocument: Btcr2DidDocument): UpdateBuilder;
+    /** Deactivate a DID (not yet implemented in the core method). */
+    deactivate(): Promise<SignedBTCR2Update>;
 }
+/**
+ * Fluent builder for DID update operations. Reduces the cognitive load of
+ * the 7-parameter `update()` call by letting callers chain named steps.
+ *
+ * Created via {@link DidMethodApi.buildUpdate}.
+ * @public
+ */
+export declare class UpdateBuilder {
+    #private;
+    /** @internal */
+    constructor(methodApi: DidMethodApi, sourceDocument: Btcr2DidDocument);
+    /** Add a single JSON Patch operation. Can be called multiple times. */
+    patch(op: PatchOperation): this;
+    /** Set all patches at once (replaces any previously added). */
+    patches(ops: PatchOperation[]): this;
+    /** Set the source version ID. */
+    version(id: number): this;
+    /** Set the verification method ID used for signing. */
+    signer(methodId: string): this;
+    /** Set the beacon ID for the update announcement. */
+    beacon(beaconId: string): this;
+    /** Set the signing material (secret key bytes or hex). */
+    signingMaterial(material: KeyBytes | HexString): this;
+    /** Override the Bitcoin connection for this update. */
+    withBitcoin(connection: BitcoinConnection): this;
+    /**
+     * Execute the update.
+     * @throws {Error} If required fields (version, signer, beacon) are missing.
+     */
+    execute(): Promise<SignedBTCR2Update>;
+}
+/**
+ * Main DidBtcr2Api facade — the primary entry point for the SDK.
+ *
+ * Exposes sub-facades for Bitcoin, DID Method, KeyPair, Crypto, and
+ * KeyManager operations. Created via the {@link createApi} factory.
+ * @public
+ */
 export declare class DidBtcr2Api {
-    readonly bitcoin: BitcoinApi;
-    readonly did: DidApi;
-    readonly keys: KeyPairApi;
+    #private;
+    /** Cryptographic operations (keypair, multikey, cryptosuite, proof). */
     readonly crypto: CryptoApi;
+    /** DID identifier operations (encode, decode, generate, parse). */
+    readonly did: DidApi;
+    /** Key management operations. */
+    readonly kms: KeyManagerApi;
     constructor(config?: ApiConfig);
+    /**
+     * Bitcoin API sub-facade (lazily initialized).
+     * Only available when `btc` config was provided to the constructor.
+     * @throws {Error} If the instance has been disposed or no Bitcoin config was provided.
+     */
+    get btc(): BitcoinApi;
+    /**
+     * DID Method API sub-facade (lazily initialized with bitcoin wiring).
+     * @throws {Error} If the instance has been disposed.
+     */
+    get btcr2(): DidMethodApi;
+    /**
+     * Whether this API instance has been disposed.
+     */
+    get disposed(): boolean;
+    /**
+     * Create a DID using either deterministic (KEY) or external (EXTERNAL) mode.
+     * @param type The creation mode.
+     * @param genesisBytes Public key bytes (deterministic) or document bytes (external).
+     * @param options Creation options (idType is set for you).
+     * @returns The created DID identifier string.
+     */
+    createDid(type: 'deterministic' | 'external', genesisBytes: KeyBytes | DocumentBytes, options?: Omit<DidCreateOptions, 'idType'>): string;
+    /**
+     * Generate a new DID, create the keypair, and import it into the KMS.
+     * @param options Optional settings.
+     * @param options.setActive Whether to set the imported key as active in the KMS (default `true`).
+     * @param options.network Network for the generated DID (default `'regtest'`).
+     * @returns The generated DID string and KMS key identifier.
+     */
+    generateDid(options?: {
+        setActive?: boolean;
+        network?: NetworkName;
+    }): {
+        did: string;
+        keyId: KeyIdentifier;
+    };
+    /**
+     * Resolve a DID, automatically injecting the configured Bitcoin connection.
+     * @param did The DID to resolve.
+     * @param options Optional resolution options.
+     * @returns The resolution result.
+     */
+    resolveDid(did: string, options?: ResolutionOptions): Promise<DidResolutionResult>;
+    /**
+     * Resolve a DID and return a discriminated result instead of throwing.
+     * Useful when resolution failure is an expected outcome (e.g. checking
+     * whether a DID exists before creating it).
+     * @param did The DID to resolve.
+     * @param options Optional resolution options.
+     * @returns A {@link ResolutionResult} with `ok: true` on success or
+     *          `ok: false` with error details on failure.
+     */
+    tryResolveDid(did: string, options?: ResolutionOptions): Promise<ResolutionResult>;
+    /**
+     * Update a DID document: resolve the current state, apply patches, sign, and announce.
+     * Automatically injects the configured Bitcoin connection.
+     *
+     * If `sourceDocument` and `sourceVersionId` are both provided, resolution
+     * is skipped. Otherwise the DID is resolved first to obtain them.
+     * @param params The update parameters.
+     * @returns The signed update.
+     */
+    updateDid({ did, patches, verificationMethodId, beaconId, sourceDocument, sourceVersionId, }: {
+        did: string;
+        patches: PatchOperation[];
+        verificationMethodId: string;
+        beaconId: string;
+        sourceDocument?: Btcr2DidDocument;
+        sourceVersionId?: number;
+    }): Promise<SignedBTCR2Update>;
+    /**
+     * Release internal references. After disposal, accessing `btc`, `btcr2`,
+     * or calling top-level methods will throw.
+     *
+     * Note: the underlying {@link BitcoinConnection} does not hold persistent
+     * connections, so this is primarily a guard against accidental reuse.
+     */
+    dispose(): void;
 }
+/**
+ * Create a new {@link DidBtcr2Api} instance with the given configuration.
+ * @param config Optional configuration for the API.
+ * @returns The created DidBtcr2Api instance.
+ * @public
+ */
 export declare function createApi(config?: ApiConfig): DidBtcr2Api;
+//# sourceMappingURL=api.d.ts.map