@dignetwork/dig-sdk 0.0.1-alpha.99 → 0.2.0

package/dist/dig-client-entry-ChYxUvBn.d.ts

@@ -0,0 +1,372 @@
+/** The read-crypto functions the SDK uses from the dig_client WASM. */
+interface DigClientWasm {
+    /** `retrieval_key = SHA-256(canonical rootless urn)`, lowercase hex. Empty key ⇒ index.html. */
+    retrievalKey(storeIdHex: string, resourceKey: string): string;
+    /** Derive the 32-byte AES-256 content key (lowercase hex). `saltHex` for a private store. */
+    deriveKey(storeIdHex: string, resourceKey: string, saltHex?: string | null): string;
+    /**
+     * Verify `ciphertext` is included under `trustedRootHex` via the base64 merkle `proofB64`.
+     * Returns true on success, false on ANY verification failure (a decoy returns false rather than
+     * throwing). Throws only on malformed inputs.
+     */
+    verifyInclusion(ciphertext: Uint8Array, proofB64: string, trustedRootHex: string): boolean;
+    /** AES-256-GCM-SIV-open a single chunk under an explicit 32-byte `keyHex`. Throws on tag fail. */
+    decryptChunk(keyHex: string, ciphertext: Uint8Array): Uint8Array;
+    /**
+     * Full read pipeline: gate (inclusion) then decrypt (URN key, split by `chunkLens`), returning
+     * plaintext bytes. `chunkLens` may be null/empty for a single-chunk resource.
+     */
+    decryptResource(storeIdHex: string, resourceKey: string, ciphertext: Uint8Array, proofB64: string, trustedRootHex: string, saltHex?: string | null, chunkLens?: Uint32Array | null): Uint8Array;
+    /** As `decryptResource`, returning UTF-8 text. */
+    decryptResourceToText(storeIdHex: string, resourceKey: string, ciphertext: Uint8Array, proofB64: string, trustedRootHex: string, saltHex?: string | null, chunkLens?: Uint32Array | null): string;
+    /** Seal a resource's plaintext as one GCM-SIV blob under its per-URN key (the encrypt inverse). */
+    encryptResource(storeIdHex: string, resourceKey: string, plaintext: Uint8Array, saltHex?: string | null): Uint8Array;
+    /** Reconstruct the canonical rootless URN string. */
+    reconstructUrn(storeIdHex: string, resourceKey: string): string;
+    /** Reconstruct a root-pinned display URN string. */
+    reconstructUrnWithRoot(storeIdHex: string, rootHex: string, resourceKey: string): string;
+    /** Library version (matches the crate version). */
+    version(): string;
+}
+
+/** A normalized `{ publicKey, signature }` pair from a wallet sign, both as `0x`-prefixed hex. */
+interface SignResult {
+    /** The signing public key (synthetic BLS key), `0x`-prefixed hex. */
+    publicKey: string | null;
+    /** The BLS signature, `0x`-prefixed hex (or the raw wallet string). */
+    signature: string | null;
+}
+/**
+ * The minimal injected-provider contract the SDK detects on `window.chia` (the DIG Browser's
+ * in-process wallet, or a compatible CHIP-0002 extension). Mirrors the DIG Browser provider:
+ * `request({ method, params })` returns the wallet's `data`; `connect(eager)` blocks on per-origin
+ * approval; `on`/`off` are EIP-1193-style event hooks.
+ */
+interface InjectedChiaProvider {
+    /** Unspoofable marker the DIG Browser provider sets; the SDK prefers a provider that has it. */
+    isDIG?: boolean;
+    /** Some providers expose a connected flag. */
+    isConnected?: boolean;
+    /** One CHIP-0002 RPC. Bare names auto-prefix to `chip0002_`; `chia_*` passes through. */
+    request(args: {
+        method: string;
+        params?: unknown;
+    }): Promise<unknown>;
+    /** Ask the wallet to approve this origin. Blocks until approved/rejected. */
+    connect?(eager?: boolean): Promise<unknown>;
+    on?(event: string, fn: (data: unknown) => void): void;
+    off?(event: string, fn: (data: unknown) => void): void;
+}
+declare global {
+    var chia: InjectedChiaProvider | undefined;
+    interface Window {
+        chia?: InjectedChiaProvider;
+    }
+}
+/** Which wallet transport is backing a `ChiaProvider`. */
+type WalletBackend = "injected" | "walletconnect";
+/** A connected wallet session, returned by `ChiaProvider.connect()`. */
+interface WalletSession {
+    /** The transport backing this session. */
+    backend: WalletBackend;
+    /** The CAIP-2 chain id (e.g. "chia:mainnet"). */
+    chain: string;
+    /**
+     * The session topic. For WalletConnect this is the real relay topic; for the injected backend
+     * it is a stable sentinel ("injected") — callers do not need to inspect it.
+     */
+    topic: string;
+    /** The wallet's receive address, when known at connect time. */
+    address?: string | null;
+}
+/** Options for `DigClient.read*` calls — chiefly which dig RPC endpoint to use. */
+interface ReadOptions {
+    /** dig RPC endpoint. Defaults to the public `https://rpc.dig.net`. */
+    rpc?: string;
+}
+/** The result of reading a resource by URN. */
+interface ReadResult {
+    /** Store identity (64-hex). */
+    storeId: string;
+    /** The on-chain generation root the content was verified against (or null if none supplied). */
+    root: string | null;
+    /** The resource path within the store. */
+    resourceKey: string;
+    /** Private-store salt used (or null). */
+    salt: string | null;
+    /**
+     * The resource bytes. When `decrypted` is true these are the authenticated plaintext; when
+     * false they are the RAW served ciphertext (a decoy / wrong-key / wrong-salt response is just
+     * opaque bytes — the model is oblivious, so this is never a "not found" verdict).
+     */
+    bytes: Uint8Array;
+    /** Advisory: did the served bytes' inclusion proof verify against `root`? */
+    verified: boolean;
+    /** Did the bytes decrypt+authenticate under this URN's derived key? */
+    decrypted: boolean;
+}
+/**
+ * The on-chain CHIP-0007 metadata of a collection item, as returned by the dig RPC. Hashes are
+ * lowercase-hex 32-byte digests (or `null` when absent); URIs are the dig:// / https locations the
+ * bytes are served from. Mirrors the on-chain `NftMetadata` (the dig RPC decodes it from the NFT's
+ * metadata pointer). All fields optional/nullable so a non-standard metadata updater still parses.
+ */
+interface CollectionItemMetadata {
+    /** 1-based edition number within the series. */
+    edition_number?: number;
+    /** Total editions in the series. */
+    edition_total?: number;
+    /** Primary media URIs (dig:// first, https fallback by convention). */
+    data_uris?: string[];
+    /** `sha256(media_bytes)`, lowercase hex, or null. */
+    data_hash?: string | null;
+    /** CHIP-0007 metadata-JSON URIs. */
+    metadata_uris?: string[];
+    /** `sha256(metadata_json_bytes)`, lowercase hex, or null. */
+    metadata_hash?: string | null;
+    /** License document URIs. */
+    license_uris?: string[];
+    /** `sha256(license_bytes)`, lowercase hex, or null. */
+    license_hash?: string | null;
+}
+/**
+ * One NFT in a collection, resolved to its CURRENT on-chain state by `DigClient.listCollectionItems`
+ * (owner-independent: the reported owner is live, walked forward through the singleton lineage, not
+ * the mint-time owner). All hashes/ids are lowercase hex.
+ */
+interface CollectionItem {
+    /** The NFT's stable launcher id (its `nft1…` id encodes this), lowercase hex. */
+    launcher_id: string;
+    /** The current (unspent) coin id of the NFT singleton, lowercase hex. */
+    coin_id: string;
+    /** The current assigned owner DID launcher id (lowercase hex), or null when unattributed. */
+    owner_did: string | null;
+    /** The puzzle hash royalties are paid to in offer trades, lowercase hex. */
+    royalty_puzzle_hash: string;
+    /** Royalty as hundredths of a percent (300 = 3%). */
+    royalty_basis_points: number;
+    /** The CURRENT owner (p2) puzzle hash — where the NFT lives now, lowercase hex. */
+    owner_puzzle_hash: string;
+    /** The decoded on-chain CHIP-0007 metadata, or null when it does not decode. */
+    metadata: CollectionItemMetadata | null;
+}
+/** A deterministic, paginated page of collection items, from `DigClient.listCollectionItems`. */
+interface CollectionItemsPage {
+    /** This page's items, in the requested (input launcher-id) order. */
+    items: CollectionItem[];
+    /** The offset this page started at. */
+    offset: number;
+    /** The page size requested (clamped to the server cap of 200). */
+    limit: number;
+    /** Total launcher ids in the requested collection set. */
+    total: number;
+    /** The offset of the next page, or null when this is the last page. */
+    next_offset: number | null;
+}
+/** Collection-level facts from `DigClient.getCollection` — derived from the resolved item set. */
+interface CollectionMeta {
+    /** The creator DID launcher id the items AGREE on (lowercase hex), or null when mixed/none. */
+    did: string | null;
+    /** The DID the caller declared, echoed back (lowercase hex), or null. */
+    declared_did: string | null;
+    /** How many launcher ids were requested. */
+    item_count: number;
+    /** How many of those resolved to a live on-chain NFT. */
+    resolved_count: number;
+    /** The royalty (basis points) every item agrees on, or null when mixed. */
+    royalty_basis_points: number | null;
+}
+/** The two root-independent keys a URN maps to (derived client-side, nothing sent to the network). */
+interface UrnKeys {
+    storeId: string;
+    root: string | null;
+    resourceKey: string;
+    salt: string | null;
+    /** `SHA-256(canonical rootless URN)`, lowercase hex — what the dig RPC is addressed by. */
+    retrievalKey: string;
+    /** The per-URN AES-256-GCM-SIV decryption key, lowercase hex. */
+    decryptionKey: string;
+}
+
+/** The default public dig RPC endpoint. */
+declare const DEFAULT_RPC = "https://rpc.dig.net";
+/** Options to construct a DigClient. */
+interface DigClientOptions {
+    /** dig RPC endpoint. Defaults to the public `https://rpc.dig.net`. */
+    rpc?: string;
+    /** Override `fetch` (e.g. an instrumented one). Defaults to the global `fetch`. */
+    fetch?: typeof fetch;
+}
+/**
+ * The read-crypto client. Construct once and reuse — the wasm is loaded + SRI-verified lazily on
+ * the first read and memoized process/page-wide.
+ *
+ * @example
+ * const dig = new DigClient();
+ * const { bytes, decrypted } = await dig.read({
+ *   urn: "urn:dig:chia:<storeId>/index.html",
+ *   root: "<onchain-root-hex>",
+ * });
+ * if (decrypted) console.log(new TextDecoder().decode(bytes));
+ */
+declare class DigClient {
+    private readonly rpc;
+    private readonly fetchImpl;
+    constructor(options?: DigClientOptions);
+    /** Load (and SRI-verify) the read-crypto wasm. Exposed for callers that want the raw functions. */
+    wasm(): Promise<DigClientWasm>;
+    /** `retrieval_key = SHA-256(canonical rootless URN)`, lowercase hex. */
+    retrievalKey(storeId: string, resourceKey: string): Promise<string>;
+    /** Derive the per-URN AES-256-GCM-SIV key, lowercase hex. `salt` for a private store. */
+    deriveKey(storeId: string, resourceKey: string, salt?: string | null): Promise<string>;
+    /** Verify served `ciphertext` is included under `root` via the base64 merkle `proof`. */
+    verifyInclusion(ciphertext: Uint8Array, proof: string, root: string): Promise<boolean>;
+    /** Reconstruct the canonical rootless URN whose SHA-256 is the retrieval key. */
+    reconstructUrn(storeId: string, resourceKey: string): Promise<string>;
+    /**
+     * Derive, client-side, the two root-independent keys a URN maps to (retrieval + decryption).
+     * Nothing is sent to the network — pure local derivation via the wasm.
+     */
+    deriveUrnKeys(input: {
+        urn: string;
+        salt?: string | null;
+    }): Promise<UrnKeys>;
+    /**
+     * Fetch + verify + decrypt one resource by URN. `root` is the on-chain generation root to verify
+     * against (resolved by the caller from the chain); when omitted, the root embedded in the URN is
+     * used. Returns the bytes plus advisory `verified`/`decrypted` flags. NEVER throws "not found"
+     * (presence is unknowable) — it throws only on a transport failure.
+     */
+    read(input: {
+        urn: string;
+        root?: string | null;
+        salt?: string | null;
+    }, opts?: ReadOptions): Promise<ReadResult>;
+    /** As `read`, but decoding the plaintext to a UTF-8 string when it decrypts (else throws). */
+    readText(input: {
+        urn: string;
+        root?: string | null;
+        salt?: string | null;
+    }, opts?: ReadOptions): Promise<string>;
+    /**
+     * Read by explicit (storeId, resourceKey, root, salt) rather than a URN string. The oblivious
+     * download primitive the URN read is built on.
+     */
+    readResource(input: {
+        storeId: string;
+        resourceKey: string;
+        root: string;
+        salt?: string | null;
+    }, opts?: ReadOptions): Promise<ReadResult>;
+    /**
+     * Read a collection's public, owner-independent facts (creator DID, item count, uniform royalty)
+     * from the dig RPC (`dig.getCollection`). The collection's item set is its NFT launcher ids — the
+     * authoritative, owner-independent anchor the mint produced (a DID-attributed NFT is hinted to its
+     * OWNER at mint, not to the creator DID, so launcher ids — not the DID — are the read key). Pass
+     * the optional `did` to have it echoed back and recorded as the declared creator.
+     *
+     * No wallet, no read-crypto wasm — a plain JSON-RPC read. Throws a coded {@link DigSdkError} on a
+     * transport/RPC failure (never a "not found": an empty/partly-confirmed set just resolves to fewer
+     * items).
+     *
+     * @example
+     * const meta = await dig.getCollection({ launcherIds: ["ab…", "cd…"], did: "ef…" });
+     * console.log(meta.resolved_count, meta.royalty_basis_points);
+     */
+    getCollection(input: {
+        launcherIds: string[];
+        did?: string | null;
+    }, opts?: ReadOptions): Promise<CollectionMeta>;
+    /**
+     * Read a deterministic, paginated page of a collection's items (`dig.listCollectionItems`), each
+     * resolved to its CURRENT on-chain state — current owner, royalty, and CHIP-0007 metadata — by the
+     * RPC walking the singleton lineage forward to the live tip (so the owner is never the stale
+     * mint-time owner). Items come back in the input launcher-id order. `limit` is clamped to the
+     * server cap (200); `offset` defaults to 0.
+     *
+     * Throws a coded {@link DigSdkError} on a transport/RPC failure.
+     *
+     * @example
+     * let page = await dig.listCollectionItems({ launcherIds, limit: 50 });
+     * for (const item of page.items) console.log(item.launcher_id, item.owner_puzzle_hash);
+     * // page.next_offset is null on the last page.
+     */
+    listCollectionItems(input: {
+        launcherIds: string[];
+        offset?: number;
+        limit?: number;
+    }, opts?: ReadOptions): Promise<CollectionItemsPage>;
+    private fetchCiphertext;
+    private rpcCall;
+}
+
+/** SHA-256 (lowercase hex) of vendor/dig_client_bg.wasm — the SRI digest. Fail closed on mismatch. */
+declare const DIG_CLIENT_WASM_SHA256 = "ff486be806f908a2a90780e499a04dbd34e10e3b97be0470cb9ee841a1e49e77";
+/** Optional explicit wasm inputs, for environments where auto-resolution can't find vendor/. */
+interface WasmConfig {
+    /**
+     * The wasm bytes (already loaded). When provided, SRI is still enforced unless `skipIntegrity`.
+     * Pass this in CSP-strict browsers where you fetch + verify the bytes yourself.
+     */
+    wasmBytes?: BufferSource;
+    /**
+     * URL to the wasm-bindgen glue module (vendor/dig_client.mjs) for browser dynamic import. When
+     * omitted in a browser, the loader tries to import the glue relative to this module.
+     */
+    glueUrl?: string;
+    /**
+     * URL to fetch the wasm bytes from (browser) when `wasmBytes` is not supplied. The fetched bytes
+     * are SRI-verified before init.
+     */
+    wasmUrl?: string;
+    /** Skip the SRI check. Only for tests / trusted custom builds — NOT recommended. */
+    skipIntegrity?: boolean;
+}
+/**
+ * Override how the read-crypto wasm is located/loaded. Call BEFORE the first `DigClient` read.
+ * Mainly for browsers without a bundler that resolves package files, or CSP-strict apps that fetch
+ * + verify the wasm bytes themselves and hand them in. Resets any cached instance.
+ */
+declare function configureWasm(config: WasmConfig): void;
+/**
+ * Load, SRI-verify, and instantiate the read-crypto wasm, returning its functions. Memoized — at
+ * most one init per process/page. Fails closed on an integrity mismatch.
+ */
+declare function loadDigClientWasm(): Promise<DigClientWasm>;
+
+/** The parts of a parsed DIG URN. `root`/`salt` are null when absent. */
+interface ParsedUrn {
+    /** Store identity (64-hex launcher id), lowercased. */
+    readonly storeId: string;
+    /** Generation root (64-hex), lowercased — or null for the root-independent form. */
+    readonly root: string | null;
+    /** Resource path within the store (verbatim, not lowercased). */
+    readonly resourceKey: string;
+    /** Private-store secret salt (hex), lowercased — or null for a public store. */
+    readonly salt: string | null;
+}
+/**
+ * Parse a DIG URN into its parts. Throws on a malformed URN.
+ *
+ * @example
+ * parseUrn("urn:dig:chia:" + "ab".repeat(32) + "/index.html")
+ * // → { storeId: "abab…", root: null, resourceKey: "index.html", salt: null }
+ */
+declare function parseUrn(raw: string): ParsedUrn;
+/** True iff `raw` is a syntactically valid DIG URN. Never throws. */
+declare function isUrn(raw: string): boolean;
+/**
+ * Reconstruct the canonical, root-INDEPENDENT URN string for a store + resource key:
+ * `urn:dig:chia:<store_id>/<resource_key>`. An empty resource key resolves to the default view
+ * `index.html`. This is the form whose SHA-256 is the retrieval key and whose bytes seed the AES
+ * key — matching the wasm's `reconstructUrn`.
+ */
+declare function reconstructUrn(storeId: string, resourceKey: string): string;
+/**
+ * Reconstruct a root-PINNED display URN: `urn:dig:chia:<store_id>:<root>/<resource_key>`. Useful
+ * for sharing a URN bound to a specific generation; the retrieval/AES keys still use the rootless
+ * form (`reconstructUrn`).
+ */
+declare function reconstructUrnWithRoot(storeId: string, root: string, resourceKey: string): string;
+
+export { type CollectionItem as C, DEFAULT_RPC as D, type InjectedChiaProvider as I, type ParsedUrn as P, type ReadOptions as R, type SignResult as S, type UrnKeys as U, type WalletBackend as W, type WalletSession as a, type CollectionItemMetadata as b, type CollectionItemsPage as c, type CollectionMeta as d, DIG_CLIENT_WASM_SHA256 as e, DigClient as f, type DigClientOptions as g, type DigClientWasm as h, type ReadResult as i, type WasmConfig as j, configureWasm as k, isUrn as l, loadDigClientWasm as m, reconstructUrnWithRoot as n, parseUrn as p, reconstructUrn as r };