@dignetwork/dig-sdk 0.1.0 → 0.2.0

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { W as WalletBackend, a as WalletSession, S as SignResult, I as InjectedChiaProvider } from './dig-client-entry-BIzuZ7Rs.cjs';
-export { D as DEFAULT_RPC, b as DIG_CLIENT_WASM_SHA256, c as DigClient, d as DigClientOptions, e as DigClientWasm, P as ParsedUrn, R as ReadOptions, f as ReadResult, U as UrnKeys, g as WasmConfig, h as configureWasm, i as isUrn, l as loadDigClientWasm, p as parseUrn, r as reconstructUrn, j as reconstructUrnWithRoot } from './dig-client-entry-BIzuZ7Rs.cjs';
+import { W as WalletBackend, a as WalletSession, S as SignResult, I as InjectedChiaProvider } from './dig-client-entry-ChYxUvBn.cjs';
+export { C as CollectionItem, b as CollectionItemMetadata, c as CollectionItemsPage, d as CollectionMeta, D as DEFAULT_RPC, e as DIG_CLIENT_WASM_SHA256, f as DigClient, g as DigClientOptions, h as DigClientWasm, P as ParsedUrn, R as ReadOptions, i as ReadResult, U as UrnKeys, j as WasmConfig, k as configureWasm, l as isUrn, m as loadDigClientWasm, p as parseUrn, r as reconstructUrn, n as reconstructUrnWithRoot } from './dig-client-entry-ChYxUvBn.cjs';
 
 /** A wallet transport: connect, then `request` CHIP-0002 methods through it. */
 interface WalletTransport {
@@ -175,6 +175,176 @@ declare class InjectedTransport implements WalletTransport {
 /** True iff `err` looks like a transient relay-publish failure (request never reached the wallet). */
 declare function isTransientPublishError(err: unknown): boolean;
 
+/** A payment asset: XCH, or a CAT identified by its tail hash (e.g. $DIG). */
+type PaymentAssetSpec = {
+    xch: true;
+    assetId?: undefined;
+} | {
+    xch?: false;
+    assetId: string;
+};
+/**
+ * The subset of `@dignetwork/chip35-dl-coin-wasm` the Paywall drives. The full wasm module satisfies
+ * this shape, so `import("@dignetwork/chip35-dl-coin-wasm")` (or the SDK's "./spend" re-export) can
+ * be passed directly. Declared as a structural type so the SDK does not statically import the
+ * (bundler-only) wasm and tests can inject a spy.
+ */
+interface MonetizationSpends {
+    /** wasm-bindgen init. Called once before building spends (a no-op if the runtime needs none). */
+    init?: () => unknown;
+    /** SHA-256-derive a 32-byte unlock nonce from request bytes. */
+    paymentNonce?: (requestBytes: Uint8Array) => Uint8Array;
+    /** Build the coin spends for an XCH payment. Returns `{ coinSpends, receipt }`. */
+    buildPayment?: (buyerSyntheticKey: Uint8Array, selectedCoins: unknown, ownerPuzzleHash: Uint8Array, amount: bigint, nonce: Uint8Array, fee: bigint) => {
+        coinSpends: unknown;
+        receipt: unknown;
+    };
+    /** Build the coin spends for a CAT (incl. DIG) payment. Returns `{ coinSpends, receipt }`. */
+    buildCatPayment?: (buyerSyntheticKey: Uint8Array, selectedCats: unknown, ownerPuzzleHash: Uint8Array, amount: bigint, nonce: Uint8Array) => {
+        coinSpends: unknown;
+        receipt: unknown;
+    };
+    /** Verify an observed payment unlocks the paywall. Returns `{ ok, error? }`. */
+    verifyPaymentReceipt?: (observed: unknown, ownerPuzzleHash: Uint8Array, minAmount: bigint, requiredAsset: unknown, requireNonce?: Uint8Array | null) => {
+        ok: boolean;
+        error?: string;
+    };
+    /** Prove NFT ownership (optionally gating on a launcher id). Returns `{ ok, proof?, error? }`. */
+    proveNftOwnership?: (parentSpend: unknown, claimedOwnerPuzzleHash: Uint8Array, requiredNft?: Uint8Array | null) => {
+        ok: boolean;
+        proof?: unknown;
+        error?: string;
+    };
+    /** Prove collection/creator membership for an owner. Returns `{ ok, proof?, error? }`. */
+    proveCollectionMembership?: (parentSpend: unknown, claimedOwnerPuzzleHash: Uint8Array, requiredDid: Uint8Array) => {
+        ok: boolean;
+        proof?: unknown;
+        error?: string;
+    };
+}
+/** Options for constructing a `Paywall`. */
+interface PaywallOptions {
+    /**
+     * The canonical chip35 monetization spends. Defaults to a lazy
+     * `import("@dignetwork/chip35-dl-coin-wasm")` (and calls its `init()`), so a bundled dapp needs to
+     * pass nothing. Inject a builder for non-bundler runtimes or tests.
+     */
+    spends?: MonetizationSpends;
+}
+/** Arguments for `Paywall.requestPayment`. */
+interface RequestPaymentArgs {
+    /** Amount to pay, in mojos (XCH) or base units (CAT). Number or bigint. */
+    amount: number | bigint;
+    /** The dapp owner's puzzle hash to pay (hex, with or without `0x`). */
+    owner: string;
+    /** Pay in this CAT (tail hash hex). Omit for XCH. */
+    assetId?: string;
+    /**
+     * A free-form unlock identifier (e.g. `dappId|resource|user`). When given without an explicit
+     * `nonce`, the Paywall derives the 32-byte nonce from it via the wasm `paymentNonce` (deterministic
+     * convenience). Ignored when `nonce` is supplied.
+     */
+    memo?: string;
+    /** An explicit 32-byte unlock nonce (hex). Overrides `memo`. Random 32 bytes are used if neither. */
+    nonce?: string;
+    /** Network fee in mojos (XCH payments only; CAT rings net to zero). Defaults to 0. */
+    fee?: number | bigint;
+    /** Cap on the number of buyer coins to source from the wallet. */
+    coinLimit?: number;
+}
+/** The result of a successful `requestPayment`: the wallet signature + the wasm receipt + spends. */
+interface PaymentResult {
+    /** The aggregated BLS signature the wallet returned for the coin spends. */
+    signature: string;
+    /** The `PaymentReceipt` the wasm produced — persist it; `verifyReceipt` later checks the chain. */
+    receipt: unknown;
+    /** The exact coin spends the wasm built and the wallet signed. */
+    coinSpends: unknown;
+    /** The 32-byte unlock nonce embedded in the payment (hex). */
+    nonce: string;
+}
+/** Arguments for `Paywall.verifyReceipt`. */
+interface VerifyReceiptArgs {
+    /** The `ObservedPayment` the dapp filled in after reading the owner's coin from the chain. */
+    observed: unknown;
+    /** The owner puzzle hash that must have been paid (hex). */
+    owner: string;
+    /** The minimum amount that must have been paid (mojos / base units). */
+    minAmount: number | bigint;
+    /** The required asset. Defaults to XCH; pass `{ assetId }` to require a CAT. */
+    asset?: PaymentAssetSpec;
+    /** Require this exact 32-byte nonce (hex) to be present in the payment. */
+    nonce?: string;
+}
+/** Arguments for `Paywall.proveAccess` — gate on NFT ownership XOR collection membership. */
+interface ProveAccessArgs {
+    /** The coin spend that created the NFT's current coin (the wasm `CoinSpend` shape). */
+    parentSpend: unknown;
+    /** The puzzle hash claiming ownership (hex). */
+    owner: string;
+    /** Gate on this specific NFT launcher id (hex). Mutually exclusive with `collection`. */
+    nft?: string;
+    /** Gate on membership of this collection/creator DID (hex). Mutually exclusive with `nft`. */
+    collection?: string;
+}
+/**
+ * High-level pay-to-unlock helper. Construct it from a connected `ChiaProvider`; it builds payment
+ * spends via the canonical chip35 wasm and pushes them to the wallet for signing.
+ *
+ * @example
+ * const provider = await ChiaProvider.connect({ mode: "auto", walletConnect });
+ * const paywall = new Paywall(provider); // chip35 wasm loaded lazily under a bundler
+ * // Charge 0.25 XCH to unlock a resource:
+ * const { receipt } = await paywall.requestPayment({
+ *   amount: 250_000_000_000n,
+ *   owner: dappOwnerPuzzleHashHex,
+ *   memo: `unlock:${resourceId}:${userId}`,
+ * });
+ * // Later, gate access by re-checking the receipt against the chain:
+ * const { ok } = await paywall.verifyReceipt({ observed, owner: dappOwnerPuzzleHashHex, minAmount: 250_000_000_000n });
+ */
+declare class Paywall {
+    private readonly provider;
+    private readonly injectedSpends?;
+    private spendsReady?;
+    constructor(provider: ChiaProvider, options?: PaywallOptions);
+    /**
+     * Resolve the canonical monetization spends (injected, or lazily imported + `init()`ed). Memoized.
+     * This is the ONLY source of coin-spend construction in the Paywall — there is no fallback that
+     * hand-rolls a spend.
+     */
+    private spends;
+    /** The wallet's first synthetic public key, as bytes (the buyer key the spends are built against). */
+    private buyerKey;
+    /** Resolve the 32-byte unlock nonce: explicit hex, else derived from `memo`, else random. */
+    private resolveNonce;
+    /**
+     * Charge the buyer (the connected wallet) `amount` to pay the dapp `owner`, then push the
+     * wasm-built coin spends to the wallet for signing. Returns the wallet signature + the receipt.
+     * Builds via the canonical wasm `buildPayment` (XCH) or `buildCatPayment` (CAT) — never hand-rolled.
+     */
+    requestPayment(args: RequestPaymentArgs): Promise<PaymentResult>;
+    /**
+     * Verify an observed on-chain payment unlocks the paywall (pay-to-unlock). Delegates to the wasm
+     * `verifyPaymentReceipt`; returns its `{ ok, error? }` verdict. `ok:true` grants access.
+     */
+    verifyReceipt(args: VerifyReceiptArgs): Promise<{
+        ok: boolean;
+        error?: string;
+    }>;
+    /**
+     * Prove the `owner` holds access: gate on a specific NFT (`nft` launcher id) via the wasm
+     * `proveNftOwnership`, or on collection/creator membership (`collection` DID) via
+     * `proveCollectionMembership`. Returns `{ ok, proof?, error? }`. The caller still confirms the
+     * proof's coin is unspent on-chain for liveness.
+     */
+    proveAccess(args: ProveAccessArgs): Promise<{
+        ok: boolean;
+        proof?: unknown;
+        error?: string;
+    }>;
+}
+
 /** The canonical CHIP-0002 / chia method names the SDK negotiates with the wallet. */
 declare const WALLET_METHODS: readonly ["chip0002_connect", "chip0002_chainId", "chip0002_getPublicKeys", "chip0002_getAssetCoins", "chip0002_getAssetBalance", "chip0002_signCoinSpends", "chip0002_signMessage", "chia_getAddress", "chia_signMessageByAddress", "chia_takeOffer"];
 /** Union of the canonical wallet method names. */
@@ -189,4 +359,144 @@ declare const SIGN_METHODS: readonly ["chia_signMessageByAddress", "chip0002_sig
 /** Default Chia chain id (CAIP-2). Mainnet — there is no testnet flow. */
 declare const DEFAULT_CHAIN = "chia:mainnet";
 
-export { ChiaProvider, type ConnectOptions, DEFAULT_CHAIN, INJECTED_TOPIC, InjectedChiaProvider, InjectedTransport, SIGN_METHODS, SignResult, WALLET_METHODS, WalletBackend, type WalletConnectMetadata, type WalletConnectOptions, WalletConnectTransport, type WalletMethod, WalletSession, type WalletTransport, connectWallet, getInjectedProvider, isInjectedAvailable, isTransientPublishError };
+/**
+ * The stable error-code catalogue. Each value is an UPPER_SNAKE symbolic string that callers may
+ * branch on. Frozen so it can't be mutated at runtime; the README documents each meaning.
+ */
+declare const DIG_SDK_ERROR_CODES: Readonly<{
+    /** WalletConnect was requested/needed but no `walletConnect` options were supplied. */
+    readonly WC_OPTIONS_REQUIRED: "WC_OPTIONS_REQUIRED";
+    /** `mode: "injected"` (or the injected leg of `auto`) found no usable `window.chia`. */
+    readonly NO_INJECTED_WALLET: "NO_INJECTED_WALLET";
+    /** The optional `@walletconnect/sign-client` peer dependency is not installed/usable. */
+    readonly WC_DEPENDENCY_MISSING: "WC_DEPENDENCY_MISSING";
+    /** The active wallet session/transport does not grant the requested method. */
+    readonly METHOD_NOT_SUPPORTED: "METHOD_NOT_SUPPORTED";
+    /** A wallet RPC timed out (e.g. Sage did not respond within the per-request timeout). */
+    readonly WALLET_TIMEOUT: "WALLET_TIMEOUT";
+    /** The wallet returned no public keys / no key to sign with. */
+    readonly WALLET_NO_KEYS: "WALLET_NO_KEYS";
+    /** A content read needs a confirmed on-chain root and none was supplied/derivable. */
+    readonly ROOT_REQUIRED: "ROOT_REQUIRED";
+    /** The resource did not decrypt+authenticate under this URN (wrong key/salt, or a decoy). */
+    readonly DECRYPT_FAILED: "DECRYPT_FAILED";
+    /** The dig RPC could not be reached (network/transport failure). */
+    readonly RPC_TRANSPORT: "RPC_TRANSPORT";
+    /** The dig RPC responded with an HTTP error or a JSON-RPC `error` object. */
+    readonly RPC_ERROR: "RPC_ERROR";
+    /** The dig RPC returned a malformed / inconsistent payload (e.g. chunk-length mismatch). */
+    readonly RPC_MALFORMED_RESPONSE: "RPC_MALFORMED_RESPONSE";
+    /** The vendored read-crypto wasm failed its SRI integrity check — fail closed. */
+    readonly WASM_INTEGRITY: "WASM_INTEGRITY";
+    /** The read-crypto wasm could not be loaded (fetch/resolve failure). */
+    readonly WASM_LOAD_FAILED: "WASM_LOAD_FAILED";
+    /** The canonical chip35 wasm builder for this operation is unavailable (never hand-rolled). */
+    readonly SPEND_BUILDER_UNAVAILABLE: "SPEND_BUILDER_UNAVAILABLE";
+    /** No secure random source was available to generate a payment nonce. */
+    readonly NO_SECURE_RANDOM: "NO_SECURE_RANDOM";
+    /** The `digstore` binary could not be spawned (not installed / not on PATH). */
+    readonly DIGSTORE_NOT_FOUND: "DIGSTORE_NOT_FOUND";
+    /** `digstore deploy` exited non-zero. */
+    readonly DEPLOY_FAILED: "DEPLOY_FAILED";
+    /** `digstore deploy --json` output could not be parsed into a capsule result. */
+    readonly DEPLOY_OUTPUT_UNPARSEABLE: "DEPLOY_OUTPUT_UNPARSEABLE";
+    /** An argument was malformed (e.g. a non-hex string, a bad URN, mutually-exclusive options). */
+    readonly INVALID_ARGUMENT: "INVALID_ARGUMENT";
+}>;
+/** The union of every stable SDK error code. Branch on `err.code` against these. */
+type DigSdkErrorCode = (typeof DIG_SDK_ERROR_CODES)[keyof typeof DIG_SDK_ERROR_CODES];
+/** Structured, code-specific context attached to a {@link DigSdkError}. All fields optional. */
+interface DigSdkErrorContext {
+    /** The dig RPC method involved (RPC_* errors). */
+    rpcMethod?: string;
+    /** The HTTP status returned (RPC_ERROR on a non-2xx). */
+    httpStatus?: number;
+    /** The JSON-RPC error code returned by the server (RPC_ERROR). */
+    rpcCode?: number;
+    /** The `digstore` process exit code (DEPLOY_FAILED). */
+    exitCode?: number | null;
+    /** The wallet method that was unsupported (METHOD_NOT_SUPPORTED). */
+    method?: string;
+    /** The connection mode in play (provider errors). */
+    mode?: string;
+    /** The offending value (INVALID_ARGUMENT — e.g. the bad hex / URN). */
+    value?: string;
+    /** The expected vs actual SRI digest (WASM_INTEGRITY). */
+    expected?: string;
+    actual?: string;
+    /** Any further structured detail; kept open so codes can carry extra fields. */
+    [key: string]: unknown;
+}
+declare class DigSdkError extends Error {
+    /** The stable machine code (UPPER_SNAKE). Branch on this, not the message. */
+    readonly code: DigSdkErrorCode;
+    /** Structured, code-specific context (rpcMethod, httpStatus, exitCode, …). */
+    readonly context: DigSdkErrorContext;
+    constructor(code: DigSdkErrorCode, message: string, context?: DigSdkErrorContext, options?: {
+        cause?: unknown;
+    });
+    /** A JSON-friendly view of the error: `{ code, message, context }`. */
+    toJSON(): {
+        code: DigSdkErrorCode;
+        message: string;
+        context: DigSdkErrorContext;
+    };
+}
+/**
+ * True iff `e` is a {@link DigSdkError} (optionally with a specific `code`). Uses a non-enumerable
+ * BRAND rather than `instanceof` so it recognizes coded errors thrown from any of the SDK's
+ * separately-bundled entry points (the main entry and `/adapters` inline distinct class identities).
+ */
+declare function isDigSdkError(e: unknown, code?: DigSdkErrorCode): e is DigSdkError;
+
+/** The SDK's semver version, from package.json (injected at build time). */
+declare const SDK_VERSION: string;
+/** The machine-readable description of one SDK module. */
+interface ModuleDescriptor {
+    /** The module's public name (the class/helper a consumer imports). */
+    readonly name: string;
+    /** One-line summary of what it does. */
+    readonly summary: string;
+    /** The import path it's reachable from (the package subpath). */
+    readonly entry: string;
+}
+/** The full machine-readable description of the SDK surface — what `capabilities()` returns. */
+interface SdkCapabilities {
+    /** Always `"@dignetwork/dig-sdk"`. */
+    readonly name: string;
+    /** The SDK semver (= {@link SDK_VERSION}). */
+    readonly version: string;
+    /** The modules the SDK exposes (ChiaProvider, DigClient, Paywall, spend builders, adapters). */
+    readonly modules: readonly ModuleDescriptor[];
+    /** The canonical CHIP-0002 wallet method surface both transports negotiate. */
+    readonly walletMethods: readonly string[];
+    /** The message-signing methods, in preference order. */
+    readonly signMethods: readonly string[];
+    /** The wallet transports the SDK can connect through. */
+    readonly transports: readonly ("injected" | "walletconnect")[];
+    /** The CAIP-2 chains supported (mainnet only — there is no testnet flow). */
+    readonly chains: readonly string[];
+    /** The default dig RPC endpoint `DigClient` reads from. */
+    readonly defaultRpc: string;
+    /** The SRI digest of the vendored read-crypto wasm (fail-closed on mismatch). */
+    readonly readCryptoWasmSha256: string;
+    /** The stable error-code catalogue (UPPER_SNAKE) consumers can branch on. */
+    readonly errorCodes: readonly DigSdkErrorCode[];
+}
+/**
+ * Describe the SDK's surface as machine-readable data: version, modules, methods, transports,
+ * chains, the default RPC, the read-crypto wasm digest, and the error-code catalogue. An agent can
+ * call this to introspect the SDK without reading source.
+ *
+ * @example
+ * import { capabilities } from "@dignetwork/dig-sdk";
+ * const cap = capabilities();
+ * cap.version;        // "0.2.0"
+ * cap.walletMethods;  // ["chip0002_connect", …]
+ * cap.errorCodes;     // ["WC_OPTIONS_REQUIRED", …]
+ */
+declare function capabilities(): SdkCapabilities;
+/** Alias for {@link capabilities} — the conventional `describe()` introspection name. */
+declare const describe: typeof capabilities;
+
+export { ChiaProvider, type ConnectOptions, DEFAULT_CHAIN, DIG_SDK_ERROR_CODES, DigSdkError, type DigSdkErrorCode, type DigSdkErrorContext, INJECTED_TOPIC, InjectedChiaProvider, InjectedTransport, type ModuleDescriptor, type MonetizationSpends, type PaymentAssetSpec, type PaymentResult, Paywall, type PaywallOptions, type ProveAccessArgs, type RequestPaymentArgs, SDK_VERSION, SIGN_METHODS, type SdkCapabilities, SignResult, type VerifyReceiptArgs, WALLET_METHODS, WalletBackend, type WalletConnectMetadata, type WalletConnectOptions, WalletConnectTransport, type WalletMethod, WalletSession, type WalletTransport, capabilities, connectWallet, describe, getInjectedProvider, isDigSdkError, isInjectedAvailable, isTransientPublishError };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { W as WalletBackend, a as WalletSession, S as SignResult, I as InjectedChiaProvider } from './dig-client-entry-BIzuZ7Rs.js';
-export { D as DEFAULT_RPC, b as DIG_CLIENT_WASM_SHA256, c as DigClient, d as DigClientOptions, e as DigClientWasm, P as ParsedUrn, R as ReadOptions, f as ReadResult, U as UrnKeys, g as WasmConfig, h as configureWasm, i as isUrn, l as loadDigClientWasm, p as parseUrn, r as reconstructUrn, j as reconstructUrnWithRoot } from './dig-client-entry-BIzuZ7Rs.js';
+import { W as WalletBackend, a as WalletSession, S as SignResult, I as InjectedChiaProvider } from './dig-client-entry-ChYxUvBn.js';
+export { C as CollectionItem, b as CollectionItemMetadata, c as CollectionItemsPage, d as CollectionMeta, D as DEFAULT_RPC, e as DIG_CLIENT_WASM_SHA256, f as DigClient, g as DigClientOptions, h as DigClientWasm, P as ParsedUrn, R as ReadOptions, i as ReadResult, U as UrnKeys, j as WasmConfig, k as configureWasm, l as isUrn, m as loadDigClientWasm, p as parseUrn, r as reconstructUrn, n as reconstructUrnWithRoot } from './dig-client-entry-ChYxUvBn.js';
 
 /** A wallet transport: connect, then `request` CHIP-0002 methods through it. */
 interface WalletTransport {
@@ -175,6 +175,176 @@ declare class InjectedTransport implements WalletTransport {
 /** True iff `err` looks like a transient relay-publish failure (request never reached the wallet). */
 declare function isTransientPublishError(err: unknown): boolean;
 
+/** A payment asset: XCH, or a CAT identified by its tail hash (e.g. $DIG). */
+type PaymentAssetSpec = {
+    xch: true;
+    assetId?: undefined;
+} | {
+    xch?: false;
+    assetId: string;
+};
+/**
+ * The subset of `@dignetwork/chip35-dl-coin-wasm` the Paywall drives. The full wasm module satisfies
+ * this shape, so `import("@dignetwork/chip35-dl-coin-wasm")` (or the SDK's "./spend" re-export) can
+ * be passed directly. Declared as a structural type so the SDK does not statically import the
+ * (bundler-only) wasm and tests can inject a spy.
+ */
+interface MonetizationSpends {
+    /** wasm-bindgen init. Called once before building spends (a no-op if the runtime needs none). */
+    init?: () => unknown;
+    /** SHA-256-derive a 32-byte unlock nonce from request bytes. */
+    paymentNonce?: (requestBytes: Uint8Array) => Uint8Array;
+    /** Build the coin spends for an XCH payment. Returns `{ coinSpends, receipt }`. */
+    buildPayment?: (buyerSyntheticKey: Uint8Array, selectedCoins: unknown, ownerPuzzleHash: Uint8Array, amount: bigint, nonce: Uint8Array, fee: bigint) => {
+        coinSpends: unknown;
+        receipt: unknown;
+    };
+    /** Build the coin spends for a CAT (incl. DIG) payment. Returns `{ coinSpends, receipt }`. */
+    buildCatPayment?: (buyerSyntheticKey: Uint8Array, selectedCats: unknown, ownerPuzzleHash: Uint8Array, amount: bigint, nonce: Uint8Array) => {
+        coinSpends: unknown;
+        receipt: unknown;
+    };
+    /** Verify an observed payment unlocks the paywall. Returns `{ ok, error? }`. */
+    verifyPaymentReceipt?: (observed: unknown, ownerPuzzleHash: Uint8Array, minAmount: bigint, requiredAsset: unknown, requireNonce?: Uint8Array | null) => {
+        ok: boolean;
+        error?: string;
+    };
+    /** Prove NFT ownership (optionally gating on a launcher id). Returns `{ ok, proof?, error? }`. */
+    proveNftOwnership?: (parentSpend: unknown, claimedOwnerPuzzleHash: Uint8Array, requiredNft?: Uint8Array | null) => {
+        ok: boolean;
+        proof?: unknown;
+        error?: string;
+    };
+    /** Prove collection/creator membership for an owner. Returns `{ ok, proof?, error? }`. */
+    proveCollectionMembership?: (parentSpend: unknown, claimedOwnerPuzzleHash: Uint8Array, requiredDid: Uint8Array) => {
+        ok: boolean;
+        proof?: unknown;
+        error?: string;
+    };
+}
+/** Options for constructing a `Paywall`. */
+interface PaywallOptions {
+    /**
+     * The canonical chip35 monetization spends. Defaults to a lazy
+     * `import("@dignetwork/chip35-dl-coin-wasm")` (and calls its `init()`), so a bundled dapp needs to
+     * pass nothing. Inject a builder for non-bundler runtimes or tests.
+     */
+    spends?: MonetizationSpends;
+}
+/** Arguments for `Paywall.requestPayment`. */
+interface RequestPaymentArgs {
+    /** Amount to pay, in mojos (XCH) or base units (CAT). Number or bigint. */
+    amount: number | bigint;
+    /** The dapp owner's puzzle hash to pay (hex, with or without `0x`). */
+    owner: string;
+    /** Pay in this CAT (tail hash hex). Omit for XCH. */
+    assetId?: string;
+    /**
+     * A free-form unlock identifier (e.g. `dappId|resource|user`). When given without an explicit
+     * `nonce`, the Paywall derives the 32-byte nonce from it via the wasm `paymentNonce` (deterministic
+     * convenience). Ignored when `nonce` is supplied.
+     */
+    memo?: string;
+    /** An explicit 32-byte unlock nonce (hex). Overrides `memo`. Random 32 bytes are used if neither. */
+    nonce?: string;
+    /** Network fee in mojos (XCH payments only; CAT rings net to zero). Defaults to 0. */
+    fee?: number | bigint;
+    /** Cap on the number of buyer coins to source from the wallet. */
+    coinLimit?: number;
+}
+/** The result of a successful `requestPayment`: the wallet signature + the wasm receipt + spends. */
+interface PaymentResult {
+    /** The aggregated BLS signature the wallet returned for the coin spends. */
+    signature: string;
+    /** The `PaymentReceipt` the wasm produced — persist it; `verifyReceipt` later checks the chain. */
+    receipt: unknown;
+    /** The exact coin spends the wasm built and the wallet signed. */
+    coinSpends: unknown;
+    /** The 32-byte unlock nonce embedded in the payment (hex). */
+    nonce: string;
+}
+/** Arguments for `Paywall.verifyReceipt`. */
+interface VerifyReceiptArgs {
+    /** The `ObservedPayment` the dapp filled in after reading the owner's coin from the chain. */
+    observed: unknown;
+    /** The owner puzzle hash that must have been paid (hex). */
+    owner: string;
+    /** The minimum amount that must have been paid (mojos / base units). */
+    minAmount: number | bigint;
+    /** The required asset. Defaults to XCH; pass `{ assetId }` to require a CAT. */
+    asset?: PaymentAssetSpec;
+    /** Require this exact 32-byte nonce (hex) to be present in the payment. */
+    nonce?: string;
+}
+/** Arguments for `Paywall.proveAccess` — gate on NFT ownership XOR collection membership. */
+interface ProveAccessArgs {
+    /** The coin spend that created the NFT's current coin (the wasm `CoinSpend` shape). */
+    parentSpend: unknown;
+    /** The puzzle hash claiming ownership (hex). */
+    owner: string;
+    /** Gate on this specific NFT launcher id (hex). Mutually exclusive with `collection`. */
+    nft?: string;
+    /** Gate on membership of this collection/creator DID (hex). Mutually exclusive with `nft`. */
+    collection?: string;
+}
+/**
+ * High-level pay-to-unlock helper. Construct it from a connected `ChiaProvider`; it builds payment
+ * spends via the canonical chip35 wasm and pushes them to the wallet for signing.
+ *
+ * @example
+ * const provider = await ChiaProvider.connect({ mode: "auto", walletConnect });
+ * const paywall = new Paywall(provider); // chip35 wasm loaded lazily under a bundler
+ * // Charge 0.25 XCH to unlock a resource:
+ * const { receipt } = await paywall.requestPayment({
+ *   amount: 250_000_000_000n,
+ *   owner: dappOwnerPuzzleHashHex,
+ *   memo: `unlock:${resourceId}:${userId}`,
+ * });
+ * // Later, gate access by re-checking the receipt against the chain:
+ * const { ok } = await paywall.verifyReceipt({ observed, owner: dappOwnerPuzzleHashHex, minAmount: 250_000_000_000n });
+ */
+declare class Paywall {
+    private readonly provider;
+    private readonly injectedSpends?;
+    private spendsReady?;
+    constructor(provider: ChiaProvider, options?: PaywallOptions);
+    /**
+     * Resolve the canonical monetization spends (injected, or lazily imported + `init()`ed). Memoized.
+     * This is the ONLY source of coin-spend construction in the Paywall — there is no fallback that
+     * hand-rolls a spend.
+     */
+    private spends;
+    /** The wallet's first synthetic public key, as bytes (the buyer key the spends are built against). */
+    private buyerKey;
+    /** Resolve the 32-byte unlock nonce: explicit hex, else derived from `memo`, else random. */
+    private resolveNonce;
+    /**
+     * Charge the buyer (the connected wallet) `amount` to pay the dapp `owner`, then push the
+     * wasm-built coin spends to the wallet for signing. Returns the wallet signature + the receipt.
+     * Builds via the canonical wasm `buildPayment` (XCH) or `buildCatPayment` (CAT) — never hand-rolled.
+     */
+    requestPayment(args: RequestPaymentArgs): Promise<PaymentResult>;
+    /**
+     * Verify an observed on-chain payment unlocks the paywall (pay-to-unlock). Delegates to the wasm
+     * `verifyPaymentReceipt`; returns its `{ ok, error? }` verdict. `ok:true` grants access.
+     */
+    verifyReceipt(args: VerifyReceiptArgs): Promise<{
+        ok: boolean;
+        error?: string;
+    }>;
+    /**
+     * Prove the `owner` holds access: gate on a specific NFT (`nft` launcher id) via the wasm
+     * `proveNftOwnership`, or on collection/creator membership (`collection` DID) via
+     * `proveCollectionMembership`. Returns `{ ok, proof?, error? }`. The caller still confirms the
+     * proof's coin is unspent on-chain for liveness.
+     */
+    proveAccess(args: ProveAccessArgs): Promise<{
+        ok: boolean;
+        proof?: unknown;
+        error?: string;
+    }>;
+}
+
 /** The canonical CHIP-0002 / chia method names the SDK negotiates with the wallet. */
 declare const WALLET_METHODS: readonly ["chip0002_connect", "chip0002_chainId", "chip0002_getPublicKeys", "chip0002_getAssetCoins", "chip0002_getAssetBalance", "chip0002_signCoinSpends", "chip0002_signMessage", "chia_getAddress", "chia_signMessageByAddress", "chia_takeOffer"];
 /** Union of the canonical wallet method names. */
@@ -189,4 +359,144 @@ declare const SIGN_METHODS: readonly ["chia_signMessageByAddress", "chip0002_sig
 /** Default Chia chain id (CAIP-2). Mainnet — there is no testnet flow. */
 declare const DEFAULT_CHAIN = "chia:mainnet";
 
-export { ChiaProvider, type ConnectOptions, DEFAULT_CHAIN, INJECTED_TOPIC, InjectedChiaProvider, InjectedTransport, SIGN_METHODS, SignResult, WALLET_METHODS, WalletBackend, type WalletConnectMetadata, type WalletConnectOptions, WalletConnectTransport, type WalletMethod, WalletSession, type WalletTransport, connectWallet, getInjectedProvider, isInjectedAvailable, isTransientPublishError };
+/**
+ * The stable error-code catalogue. Each value is an UPPER_SNAKE symbolic string that callers may
+ * branch on. Frozen so it can't be mutated at runtime; the README documents each meaning.
+ */
+declare const DIG_SDK_ERROR_CODES: Readonly<{
+    /** WalletConnect was requested/needed but no `walletConnect` options were supplied. */
+    readonly WC_OPTIONS_REQUIRED: "WC_OPTIONS_REQUIRED";
+    /** `mode: "injected"` (or the injected leg of `auto`) found no usable `window.chia`. */
+    readonly NO_INJECTED_WALLET: "NO_INJECTED_WALLET";
+    /** The optional `@walletconnect/sign-client` peer dependency is not installed/usable. */
+    readonly WC_DEPENDENCY_MISSING: "WC_DEPENDENCY_MISSING";
+    /** The active wallet session/transport does not grant the requested method. */
+    readonly METHOD_NOT_SUPPORTED: "METHOD_NOT_SUPPORTED";
+    /** A wallet RPC timed out (e.g. Sage did not respond within the per-request timeout). */
+    readonly WALLET_TIMEOUT: "WALLET_TIMEOUT";
+    /** The wallet returned no public keys / no key to sign with. */
+    readonly WALLET_NO_KEYS: "WALLET_NO_KEYS";
+    /** A content read needs a confirmed on-chain root and none was supplied/derivable. */
+    readonly ROOT_REQUIRED: "ROOT_REQUIRED";
+    /** The resource did not decrypt+authenticate under this URN (wrong key/salt, or a decoy). */
+    readonly DECRYPT_FAILED: "DECRYPT_FAILED";
+    /** The dig RPC could not be reached (network/transport failure). */
+    readonly RPC_TRANSPORT: "RPC_TRANSPORT";
+    /** The dig RPC responded with an HTTP error or a JSON-RPC `error` object. */
+    readonly RPC_ERROR: "RPC_ERROR";
+    /** The dig RPC returned a malformed / inconsistent payload (e.g. chunk-length mismatch). */
+    readonly RPC_MALFORMED_RESPONSE: "RPC_MALFORMED_RESPONSE";
+    /** The vendored read-crypto wasm failed its SRI integrity check — fail closed. */
+    readonly WASM_INTEGRITY: "WASM_INTEGRITY";
+    /** The read-crypto wasm could not be loaded (fetch/resolve failure). */
+    readonly WASM_LOAD_FAILED: "WASM_LOAD_FAILED";
+    /** The canonical chip35 wasm builder for this operation is unavailable (never hand-rolled). */
+    readonly SPEND_BUILDER_UNAVAILABLE: "SPEND_BUILDER_UNAVAILABLE";
+    /** No secure random source was available to generate a payment nonce. */
+    readonly NO_SECURE_RANDOM: "NO_SECURE_RANDOM";
+    /** The `digstore` binary could not be spawned (not installed / not on PATH). */
+    readonly DIGSTORE_NOT_FOUND: "DIGSTORE_NOT_FOUND";
+    /** `digstore deploy` exited non-zero. */
+    readonly DEPLOY_FAILED: "DEPLOY_FAILED";
+    /** `digstore deploy --json` output could not be parsed into a capsule result. */
+    readonly DEPLOY_OUTPUT_UNPARSEABLE: "DEPLOY_OUTPUT_UNPARSEABLE";
+    /** An argument was malformed (e.g. a non-hex string, a bad URN, mutually-exclusive options). */
+    readonly INVALID_ARGUMENT: "INVALID_ARGUMENT";
+}>;
+/** The union of every stable SDK error code. Branch on `err.code` against these. */
+type DigSdkErrorCode = (typeof DIG_SDK_ERROR_CODES)[keyof typeof DIG_SDK_ERROR_CODES];
+/** Structured, code-specific context attached to a {@link DigSdkError}. All fields optional. */
+interface DigSdkErrorContext {
+    /** The dig RPC method involved (RPC_* errors). */
+    rpcMethod?: string;
+    /** The HTTP status returned (RPC_ERROR on a non-2xx). */
+    httpStatus?: number;
+    /** The JSON-RPC error code returned by the server (RPC_ERROR). */
+    rpcCode?: number;
+    /** The `digstore` process exit code (DEPLOY_FAILED). */
+    exitCode?: number | null;
+    /** The wallet method that was unsupported (METHOD_NOT_SUPPORTED). */
+    method?: string;
+    /** The connection mode in play (provider errors). */
+    mode?: string;
+    /** The offending value (INVALID_ARGUMENT — e.g. the bad hex / URN). */
+    value?: string;
+    /** The expected vs actual SRI digest (WASM_INTEGRITY). */
+    expected?: string;
+    actual?: string;
+    /** Any further structured detail; kept open so codes can carry extra fields. */
+    [key: string]: unknown;
+}
+declare class DigSdkError extends Error {
+    /** The stable machine code (UPPER_SNAKE). Branch on this, not the message. */
+    readonly code: DigSdkErrorCode;
+    /** Structured, code-specific context (rpcMethod, httpStatus, exitCode, …). */
+    readonly context: DigSdkErrorContext;
+    constructor(code: DigSdkErrorCode, message: string, context?: DigSdkErrorContext, options?: {
+        cause?: unknown;
+    });
+    /** A JSON-friendly view of the error: `{ code, message, context }`. */
+    toJSON(): {
+        code: DigSdkErrorCode;
+        message: string;
+        context: DigSdkErrorContext;
+    };
+}
+/**
+ * True iff `e` is a {@link DigSdkError} (optionally with a specific `code`). Uses a non-enumerable
+ * BRAND rather than `instanceof` so it recognizes coded errors thrown from any of the SDK's
+ * separately-bundled entry points (the main entry and `/adapters` inline distinct class identities).
+ */
+declare function isDigSdkError(e: unknown, code?: DigSdkErrorCode): e is DigSdkError;
+
+/** The SDK's semver version, from package.json (injected at build time). */
+declare const SDK_VERSION: string;
+/** The machine-readable description of one SDK module. */
+interface ModuleDescriptor {
+    /** The module's public name (the class/helper a consumer imports). */
+    readonly name: string;
+    /** One-line summary of what it does. */
+    readonly summary: string;
+    /** The import path it's reachable from (the package subpath). */
+    readonly entry: string;
+}
+/** The full machine-readable description of the SDK surface — what `capabilities()` returns. */
+interface SdkCapabilities {
+    /** Always `"@dignetwork/dig-sdk"`. */
+    readonly name: string;
+    /** The SDK semver (= {@link SDK_VERSION}). */
+    readonly version: string;
+    /** The modules the SDK exposes (ChiaProvider, DigClient, Paywall, spend builders, adapters). */
+    readonly modules: readonly ModuleDescriptor[];
+    /** The canonical CHIP-0002 wallet method surface both transports negotiate. */
+    readonly walletMethods: readonly string[];
+    /** The message-signing methods, in preference order. */
+    readonly signMethods: readonly string[];
+    /** The wallet transports the SDK can connect through. */
+    readonly transports: readonly ("injected" | "walletconnect")[];
+    /** The CAIP-2 chains supported (mainnet only — there is no testnet flow). */
+    readonly chains: readonly string[];
+    /** The default dig RPC endpoint `DigClient` reads from. */
+    readonly defaultRpc: string;
+    /** The SRI digest of the vendored read-crypto wasm (fail-closed on mismatch). */
+    readonly readCryptoWasmSha256: string;
+    /** The stable error-code catalogue (UPPER_SNAKE) consumers can branch on. */
+    readonly errorCodes: readonly DigSdkErrorCode[];
+}
+/**
+ * Describe the SDK's surface as machine-readable data: version, modules, methods, transports,
+ * chains, the default RPC, the read-crypto wasm digest, and the error-code catalogue. An agent can
+ * call this to introspect the SDK without reading source.
+ *
+ * @example
+ * import { capabilities } from "@dignetwork/dig-sdk";
+ * const cap = capabilities();
+ * cap.version;        // "0.2.0"
+ * cap.walletMethods;  // ["chip0002_connect", …]
+ * cap.errorCodes;     // ["WC_OPTIONS_REQUIRED", …]
+ */
+declare function capabilities(): SdkCapabilities;
+/** Alias for {@link capabilities} — the conventional `describe()` introspection name. */
+declare const describe: typeof capabilities;
+
+export { ChiaProvider, type ConnectOptions, DEFAULT_CHAIN, DIG_SDK_ERROR_CODES, DigSdkError, type DigSdkErrorCode, type DigSdkErrorContext, INJECTED_TOPIC, InjectedChiaProvider, InjectedTransport, type ModuleDescriptor, type MonetizationSpends, type PaymentAssetSpec, type PaymentResult, Paywall, type PaywallOptions, type ProveAccessArgs, type RequestPaymentArgs, SDK_VERSION, SIGN_METHODS, type SdkCapabilities, SignResult, type VerifyReceiptArgs, WALLET_METHODS, WalletBackend, type WalletConnectMetadata, type WalletConnectOptions, WalletConnectTransport, type WalletMethod, WalletSession, type WalletTransport, capabilities, connectWallet, describe, getInjectedProvider, isDigSdkError, isInjectedAvailable, isTransientPublishError };