@invisi-labs/primitives 0.0.0-stage → 1.2.1

package/dist/index.d.cts

@@ -0,0 +1,511 @@
+import { ReceivingAddress } from './address.cjs';
+export { DecodedAddress, ReceivingKeyLookup, decodeAddress } from './address.cjs';
+import { N as NoteBytes, a as NoteDecryptionContext, C as CreditStateDecryptionContext } from './encryption-P2HJ89FQ.cjs';
+export { b as CreditStateEncryptionContext, c as NoteEncryptionContext, d as decryptCreditState, e as decryptPrivateTransferNote, f as encryptCreditState, g as encryptPrivateTransferNote } from './encryption-P2HJ89FQ.cjs';
+import { a as CreditState, b as CreditPolicy, c as CreditUsage, N as Note, P as ProtocolContext, C as CreditDeliveryState, d as CreditDataV1, F as FundsDataV1 } from './types-CEAuh35C.cjs';
+export { e as CreditStateRecovery, M as MAX_MEMO_BYTES, f as Memo, R as ReceivingKeys, g as decodeMemoText, h as encodeMemo } from './types-CEAuh35C.cjs';
+export { computeNoteCommitment, computeNoteIdentity, computeNoteNullifier } from './note.cjs';
+export { CREDIT_POLICY_FIELDS, CREDIT_USAGE_FIELDS, CreditUpdateChanges, applyCreditDrawUsage, computeCreditCommitment, computeCreditNullifier, computeCreditRecoveryPad, computeCreditSharedKeyHash, creditPeriods, deriveCreditState, deriveCreditStateNonce, deriveCreditUpdate, normalizeCreditDeliveryState, normalizeCreditPolicy, normalizeCreditState, normalizeCreditUsage, recoverCreditState } from './credit.cjs';
+import { TypedDataField, TypedDataDomain, BytesLike } from 'ethers';
+
+/** Compressed secp256k1 viewing key (33 bytes), independent of spending authority. */
+declare function viewingPublicKey(key: NoteBytes): Uint8Array;
+
+/** Current protocol Poseidon2 domain tags. */
+declare const D_IDENT = 2n;
+declare const D_NOTE = 3n;
+declare const D_NULL = 4n;
+declare const D_CREDIT = 5n;
+declare const D_CNULL = 6n;
+declare const D_CREDIT_KEY_HASH = 7n;
+declare const D_CREDIT_RECOVERY = 9n;
+declare const D_CREDIT_STATE_NONCE = 10n;
+declare const TREE_DEPTH = 16;
+
+/** Barretenberg's length-separated rate-three BN254 Poseidon2 sponge. */
+declare function poseidonHash(inputs: bigint[]): Promise<`0x${string}`>;
+
+/** BN254 scalar field modulus. */
+declare const FIELD_MODULUS = 21888242871839275222246405745257275088548364400416034343698204186575808495617n;
+/** Uniform canonical BN254 nonce, sampled using browser/Node Web Crypto. */
+declare function generateNonce(): bigint;
+/** Independent shared Credit secret. Never derive it from a note/master secret. */
+declare function generateCreditSharedKey(): bigint;
+
+/** A Credit commitment opening excludes encrypted memos and the shared recovery/nullifier secret. */
+interface CreditOpening extends Omit<CreditState, "creditSharedKey" | "memo" | keyof CreditPolicy | keyof CreditUsage>, CreditPolicy, CreditUsage {
+    creditSharedKeyHash: `0x${string}`;
+}
+/** Independently authenticated output data. Core verification alone does not establish inclusion. */
+interface DisclosureOutput {
+    chainId: bigint;
+    protocolAddress: bigint;
+    tokenAddress: bigint;
+    outputCommitment: `0x${string}`;
+    role: "funds" | "owner" | "spender";
+    ciphertext?: NoteBytes | undefined;
+}
+/** Sensitive transport material: obtain it only through the explicit export() operation. */
+interface DisclosureExport {
+    version: 1;
+    kind: "note" | "credit";
+    method: "opening" | "payload-key";
+    context: {
+        chainId: string;
+        protocolAddress: string;
+        tokenAddress: string;
+        outputCommitment: `0x${string}`;
+    };
+    data: Record<string, string>;
+}
+type DisclosureResult = {
+    kind: "note";
+    note: Readonly<Note>;
+} | {
+    kind: "credit";
+    note: Readonly<CreditOpening & {
+        payload?: Uint8Array;
+    }>;
+};
+/** Scoped disclosure material. Default JSON/inspection is redacted; export() is deliberately sensitive. */
+declare class Disclosure {
+    #private;
+    private constructor();
+    static fromNote(value: Note): Promise<Disclosure>;
+    static fromCredit(value: CreditState): Promise<Disclosure>;
+    /** Low-level factory; normally use wallet.getViewer().discloseNote(). */
+    static fromEncryptedNote(key: NoteBytes, envelope: NoteBytes, value: NoteDecryptionContext): Promise<Disclosure>;
+    /** Exposes the full selected Credit envelope, including its shared key and receiving snapshots. */
+    static fromEncryptedCredit(key: NoteBytes, envelope: NoteBytes, value: CreditStateDecryptionContext): Promise<Disclosure>;
+    private static fromEnvelope;
+    /** Parse untrusted JSON material; verification against an independent output is still required. */
+    static fromExport(value: unknown): Promise<Disclosure>;
+    getScope(): {
+        version: 1;
+        kind: "credit" | "note";
+        method: "opening" | "payload-key";
+        permitsOwnerSweep: boolean;
+        revealsNoteConsumption: boolean;
+        revealsCreditSharedKey: boolean;
+        revealsReceivingKeys: boolean;
+        revealsMemo: boolean;
+        revealsPayload: boolean;
+    };
+    /** Explicitly export sensitive, JSON-compatible material for a chosen recipient. */
+    export(): DisclosureExport;
+    verify(value: DisclosureOutput): Promise<DisclosureResult>;
+    toJSON(): {
+        version: 1;
+        kind: "credit" | "note";
+        method: "opening" | "payload-key";
+        permitsOwnerSweep: boolean;
+        revealsNoteConsumption: boolean;
+        revealsCreditSharedKey: boolean;
+        revealsReceivingKeys: boolean;
+        revealsMemo: boolean;
+        revealsPayload: boolean;
+        capability: string;
+    };
+}
+
+/** A requested permission was not explicitly supplied to this component. */
+declare class MissingCapabilityError extends Error {
+    readonly capability: string;
+    readonly code = "MISSING_CAPABILITY";
+    constructor(capability: string);
+}
+
+/** Derive the canonical 32-byte Decaf377 clue key from a nonzero FMD scalar. */
+declare function deriveClueKey(detectionKey: Uint8Array): Uint8Array;
+/** Reject malformed, noncanonical, or identity clue keys. */
+declare function validateClueKey(clueKey: Uint8Array): void;
+/** Create a fixed 24-bit clue using a fresh WebCrypto random seed. */
+declare function createClue(clueKey: Uint8Array): Uint8Array;
+/**
+ * Deterministic interoperability/backend entry point. Seed must be independently
+ * generated with a CSPRNG for every production clue; never reuse a fixed seed.
+ */
+declare function createClueFromSeed(clueKey: Uint8Array, seed32: Uint8Array): Uint8Array;
+
+type WalletBytes = Uint8Array | `0x${string}`;
+declare const OPERATIONS: {
+    readonly transact: "Transact";
+    readonly "create-credit": "CreateCredit";
+    readonly "credit-draw": "CreditDraw";
+    readonly "update-credit": "UpdateCredit";
+};
+type WalletOperation = keyof typeof OPERATIONS;
+interface WalletAuthorizationRequest {
+    context: ProtocolContext;
+    operation: WalletOperation;
+    capacity: number;
+    /** Complete, canonically padded operation words before the two digest limbs. */
+    words: readonly bigint[];
+}
+declare const WALLET_AUTHORIZATION_TYPES: {
+    readonly WalletAuthorization: readonly [{
+        readonly name: "operation";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "statementHash";
+        readonly type: "bytes32";
+    }];
+};
+/** Standard EVM owner address from a validated secp256k1 public key. */
+declare function computeOwnerAddress(publicKey: WalletBytes): Promise<`0x${string}`>;
+/** EIP712 data for private circuit authorization, independent of EVM funding signatures. */
+declare function walletAuthorizationTypedData(request: WalletAuthorizationRequest): {
+    domain: {
+        name: string;
+        version: string;
+        chainId: bigint;
+        verifyingContract: `0x${string}`;
+    };
+    types: {
+        readonly WalletAuthorization: readonly [{
+            readonly name: "operation";
+            readonly type: "bytes32";
+        }, {
+            readonly name: "statementHash";
+            readonly type: "bytes32";
+        }];
+    };
+    primaryType: "WalletAuthorization";
+    message: {
+        operation: `0x${string}`;
+        statementHash: `0x${string}`;
+    };
+};
+declare function computeWalletAuthorizationDigest(request: WalletAuthorizationRequest): `0x${string}`;
+declare function verifyWalletAuthorization(expectedIdentity: `0x${string}`, publicKey: WalletBytes, signature: WalletBytes, request: WalletAuthorizationRequest): Promise<boolean>;
+interface WalletAuthorizationWitness {
+    public_key_x: number[];
+    public_key_y: number[];
+    signature: number[];
+}
+
+type Identity = `0x${string}`;
+declare const inspect: unique symbol;
+/** Local viewing permission, permitting note recovery and owner-only sweep, without arbitrary spending. */
+declare class ViewingCapability {
+    #private;
+    readonly ownerAddress: Identity;
+    constructor(ownerAddress: Identity, privateKey: WalletBytes, expectedPublicKey?: Uint8Array);
+    decryptNote(envelope: NoteBytes, context: Omit<NoteDecryptionContext, "ownerAddress">): Promise<Note & {
+        payload: Uint8Array;
+    }>;
+    decryptCredit(envelope: NoteBytes, context: Omit<CreditStateDecryptionContext, "ownerAddress">): Promise<CreditDeliveryState & {
+        note: CreditState & {
+            payload: Uint8Array;
+        };
+    }>;
+    getPublicKey(): Uint8Array;
+    /** Disclose this authenticated output's payload key, without exporting the wallet viewing key. */
+    discloseNote(envelope: NoteBytes, context: Omit<NoteDecryptionContext, "ownerAddress">): Promise<Disclosure>;
+    /** Exposes the entire Credit envelope; prefer Disclosure.fromCredit() for hash-only opening. */
+    discloseCredit(envelope: NoteBytes, context: Omit<CreditStateDecryptionContext, "ownerAddress">): Promise<Disclosure>;
+    /** Explicit sensitive export for delegating viewing. It grants note recovery and owner-only sweep permission. */
+    exportKey(): Uint8Array;
+    toJSON(): {
+        capability: string;
+        ownerAddress: `0x${string}`;
+    };
+    [inspect](): {
+        capability: string;
+        ownerAddress: `0x${string}`;
+    };
+}
+/** Delegated candidate detection key, without viewing or spending. */
+declare class Detector {
+    #private;
+    constructor(key: Uint8Array);
+    getClueKey(): Uint8Array;
+    /** Full detection delegation; the receiver chooses the checked prefix length. */
+    exportKey(): Uint8Array;
+    toJSON(): {
+        capability: string;
+    };
+    [inspect](): {
+        capability: string;
+    };
+}
+/** Note-derived spent-state calculation; the note opening supplies its nonce. */
+declare class NullifierCapability {
+    readonly ownerAddress: Identity;
+    private constructor();
+    static fromIdentity(ownerAddress: Identity): NullifierCapability;
+    compute(chainId: bigint, protocolAddress: bigint, commitment: Identity, nonce: bigint): Promise<Identity>;
+    toJSON(): {
+        capability: string;
+        ownerAddress: `0x${string}`;
+    };
+    [inspect](): {
+        capability: string;
+        ownerAddress: `0x${string}`;
+    };
+}
+/** Frozen local authorization. Witness access is an explicit trusted proving boundary. */
+declare class AuthorizedStatement {
+    #private;
+    readonly digest: Identity;
+    readonly ownerAddress: Identity;
+    constructor(ownerAddress: Identity, digest: Identity, witness: WalletAuthorizationWitness);
+    withWitness<T>(assemble: (witness: WalletAuthorizationWitness) => T): T;
+    toJSON(): {
+        ownerAddress: `0x${string}`;
+        digest: `0x${string}`;
+    };
+    [inspect](): {
+        ownerAddress: `0x${string}`;
+        digest: `0x${string}`;
+    };
+}
+
+/** Public identity and receiving keys. */
+declare class WalletAddress {
+    #private;
+    protected constructor(address: ReceivingAddress);
+    get ownerAddress(): `0x${string}`;
+    get viewingPublicKey(): Uint8Array;
+    get clueKey(): Uint8Array;
+    /** Complete 0i receiving address. Owner-only wallets must first resolve their receiving keys. */
+    getAddress(): string;
+    getReceivingAddress(): ReceivingAddress;
+    /** Nullifiers derive from public identity and do not grant spending authority. */
+    exportNullifier(): NullifierCapability;
+    toJSON(): {
+        ownerAddress: `0x${string}`;
+        address: string;
+    };
+}
+/** Address-only wallet. Contains no private keys or private capability methods. */
+declare class Wallet extends WalletAddress {
+    private constructor();
+    /** Parse a complete 0i address or an EVM owner address without network access. */
+    static fromAddress(address: ReceivingAddress | string): Wallet;
+}
+
+type Hex = `0x${string}`;
+type Address = `0x${string}`;
+
+/** JSON-safe EIP-712 data, directly consumable by an external signing tool. */
+interface SigningRequest {
+    domain: {
+        name?: string;
+        version?: string;
+        chainId?: string;
+        verifyingContract?: string;
+        salt?: string;
+    };
+    primaryType: string;
+    types: Record<string, TypedDataField[]>;
+    message: Record<string, unknown>;
+}
+/** Normalize through ethers; do not implement a second typed-data encoder. */
+declare function createSigningRequest(data: {
+    domain: TypedDataDomain;
+    primaryType: string;
+    types: Record<string, readonly TypedDataField[]>;
+    message: Record<string, unknown>;
+}): SigningRequest;
+
+/** Stable transport resource bound; applications do not select the SDK envelope version. */
+declare const MAX_CIPHERTEXT_BYTES = 4096;
+type DeliveryKind = "funds" | "credit";
+declare function deliveryHeader(kind: DeliveryKind): number;
+declare function decodeDeliveryHeader(header: number): {
+    kind: DeliveryKind;
+    version: number;
+};
+/** Dispatch only SDK-owned envelope implementations. Future versions are added here. */
+declare function deliveryCodec(header: number): {
+    domain: string;
+    kind: "funds";
+    version: number;
+    minimum: number;
+    maximum: number;
+    encode(note: Note): Uint8Array<ArrayBufferLike>;
+    decode(plain: Uint8Array, context: NoteDecryptionContext): {
+        chainId: bigint;
+        protocolAddress: bigint;
+        tokenAddress: bigint;
+        ownerAddress: `0x${string}`;
+        amount: bigint;
+        nonce: bigint;
+        payload: Uint8Array<ArrayBufferLike>;
+    };
+} | {
+    domain: string;
+    kind: "credit";
+    version: number;
+    minimum: number;
+    maximum: number;
+    encode(input: CreditDeliveryState): Uint8Array<ArrayBufferLike>;
+    decode(plain: Uint8Array, context: CreditStateDecryptionContext): CreditDeliveryState;
+};
+declare function validateDeliveryCiphertext(value: BytesLike, kind?: DeliveryKind): Uint8Array;
+
+/** Pure memo codec: payload version1 followed by memo bytes; no flags or address semantics. */
+declare const fundsV1: Readonly<{
+    encode(data?: FundsDataV1): Uint8Array;
+    decode(value: Uint8Array): {
+        memo?: Uint8Array;
+    };
+}>;
+/** Credit uses the same memo-only application layout, independently of its financial fields. */
+declare const creditV1: Readonly<{
+    encode(data?: CreditDataV1): Uint8Array;
+    decode(value: Uint8Array): {
+        memo?: Uint8Array;
+    };
+}>;
+
+type WalletHex = `0x${string}`;
+type WalletMethod = "wallet.public" | "wallet.detect" | "wallet.decryptNote" | "wallet.decryptCredit" | "wallet.authorize";
+interface WalletWireContext {
+    chainId: string;
+    protocolAddress: string;
+}
+interface WalletDecryptContext extends WalletWireContext {
+    tokenAddress: string;
+    outputCommitment: WalletHex;
+    role?: "owner" | "spender";
+}
+interface WalletParams {
+    "wallet.public": Record<string, never>;
+    "wallet.detect": {
+        clues: WalletHex[];
+    };
+    "wallet.decryptNote": {
+        envelope: WalletHex;
+        context: WalletDecryptContext;
+    };
+    "wallet.decryptCredit": {
+        envelope: WalletHex;
+        context: WalletDecryptContext;
+    };
+    "wallet.authorize": {
+        operation: WalletOperation;
+        capacity: number;
+        words: string[];
+        context: WalletWireContext;
+    };
+}
+interface WalletResults {
+    "wallet.public": {
+        viewingPublicKey: WalletHex;
+        spendingPublicKey: WalletHex;
+        clueKey: WalletHex;
+    };
+    "wallet.detect": {
+        matches: boolean[];
+    };
+    "wallet.decryptNote": {
+        plaintext: WalletHex;
+    };
+    "wallet.decryptCredit": {
+        plaintext: WalletHex;
+    };
+    "wallet.authorize": {
+        spendingPublicKey: WalletHex;
+        signature: WalletHex;
+        digest: WalletHex;
+    };
+}
+interface WalletAcceptedResults {
+    "wallet.public": WalletResults["wallet.public"];
+    "wallet.detect": WalletResults["wallet.detect"];
+    "wallet.decryptNote": Note & {
+        payload: Uint8Array;
+    };
+    "wallet.decryptCredit": CreditDeliveryState & {
+        note: CreditState & {
+            payload: Uint8Array;
+        };
+    };
+    "wallet.authorize": AuthorizedStatement;
+}
+type WalletRequest<M extends WalletMethod = WalletMethod> = {
+    version: 1;
+    id: string;
+    ownerAddress: WalletHex;
+    method: M;
+    params: WalletParams[M];
+};
+type WalletResponse<M extends WalletMethod = WalletMethod> = {
+    version: 1;
+    id: string;
+    ownerAddress: WalletHex;
+    method: M;
+} & ({
+    result: WalletResults[M];
+    error?: never;
+} | {
+    error: {
+        code: string;
+    };
+    result?: never;
+});
+interface PreparedWalletRequest<M extends WalletMethod = WalletMethod> {
+    readonly request: WalletRequest<M>;
+}
+declare function prepareWalletRequest<M extends WalletMethod>(wallet: Wallet, id: string, method: M, params: WalletParams[M]): PreparedWalletRequest<M>;
+/** Validate native output against the retained request before using it in business state. */
+declare function acceptWalletResponse<M extends WalletMethod>(prepared: PreparedWalletRequest<M>, response: WalletResponse<M>): Promise<WalletAcceptedResults[M]>;
+/** Native errors contain machine-readable codes only. */
+declare class NativeWalletError extends Error {
+    readonly code: string;
+    constructor(code: string);
+}
+declare const MAX_WALLET_BATCH_BYTES: number;
+declare function validateWalletBatch(requests: readonly WalletRequest[]): void;
+/** Check every envelope before returning responses in request order. */
+declare function validateWalletResponses(requests: readonly WalletRequest[], responses: readonly WalletResponse[]): WalletResponse[];
+declare function acceptWalletResponses(prepared: readonly PreparedWalletRequest[], responses: readonly WalletResponse[]): Promise<unknown[]>;
+
+declare function provenanceIntentHash(originalRequestHash: string): string;
+
+type DeliveryDecryptionResult = Uint8Array | null | {
+    status: "authentication-failed";
+};
+interface DeliveryDetectionCandidate extends NoteDecryptionContext {
+    role: "funds" | "owner" | "spender";
+    clue: `0x${string}`;
+    ciphertext: `0x${string}`;
+}
+interface DeliveryDetectionBatch {
+    ownerAddress: `0x${string}`;
+    results: readonly ("candidate" | "not-recipient" | "unresolved")[];
+}
+/** App-owned decryption. Only null means nonrecipient; operational failures must reject. */
+interface DeliveryDecryptor {
+    detect?(candidates: readonly DeliveryDetectionCandidate[]): Promise<DeliveryDetectionBatch>;
+    decryptNote(envelope: NoteBytes, context: NoteDecryptionContext): Promise<DeliveryDecryptionResult>;
+    decryptCredit(envelope: NoteBytes, context: CreditStateDecryptionContext): Promise<DeliveryDecryptionResult>;
+}
+/** Keeps App failures and invalid plaintext distinct from unrelated local scan candidates. */
+declare class DeliveryDecryptionError extends Error {
+    constructor(cause: unknown);
+}
+/** Bind untrusted App plaintext to the requested wallet, deployment, token and commitment. */
+declare function authenticatedDecryptor(wallet: Wallet, decryptor: DeliveryDecryptor): {
+    ownerAddress: `0x${string}`;
+    detectCandidates(candidates: readonly DeliveryDetectionCandidate[]): Promise<any[]>;
+    decryptNote(envelope: NoteBytes, context: Omit<NoteDecryptionContext, "ownerAddress">): Promise<{
+        chainId: bigint;
+        protocolAddress: bigint;
+        tokenAddress: bigint;
+        ownerAddress: `0x${string}`;
+        amount: bigint;
+        nonce: bigint;
+        payload: Uint8Array<ArrayBufferLike>;
+    } | null>;
+    decryptCredit(envelope: NoteBytes, context: Omit<CreditStateDecryptionContext, "ownerAddress">): Promise<CreditDeliveryState | null>;
+};
+
+/** AEAD failure is ambiguous: wrong recipient key, wrong context or damaged ciphertext. */
+declare class DeliveryAuthenticationError extends Error {
+    constructor(cause?: unknown);
+}
+
+export { type Address, AuthorizedStatement, CreditDataV1, CreditDeliveryState, type CreditOpening, CreditPolicy, CreditState, CreditStateDecryptionContext, CreditUsage, D_CNULL, D_CREDIT, D_CREDIT_KEY_HASH, D_CREDIT_RECOVERY, D_CREDIT_STATE_NONCE, D_IDENT, D_NOTE, D_NULL, DeliveryAuthenticationError, DeliveryDecryptionError, type DeliveryDecryptionResult, type DeliveryDecryptor, type DeliveryDetectionBatch, type DeliveryDetectionCandidate, type DeliveryKind, Detector, Disclosure, type DisclosureExport, type DisclosureOutput, type DisclosureResult, FIELD_MODULUS, FundsDataV1, type Hex, MAX_CIPHERTEXT_BYTES, MAX_WALLET_BATCH_BYTES, MissingCapabilityError, NativeWalletError, Note, NoteBytes, NoteDecryptionContext, NullifierCapability, type PreparedWalletRequest, ProtocolContext, ReceivingAddress, type SigningRequest, TREE_DEPTH, ViewingCapability, WALLET_AUTHORIZATION_TYPES, Wallet, type WalletAcceptedResults, type WalletAuthorizationRequest, type WalletAuthorizationWitness, type WalletBytes, type WalletDecryptContext, type WalletHex, type WalletMethod, type WalletOperation, type WalletParams, type WalletRequest, type WalletResponse, type WalletResults, type WalletWireContext, acceptWalletResponse, acceptWalletResponses, authenticatedDecryptor, computeOwnerAddress, computeWalletAuthorizationDigest, createClue, createClueFromSeed, createSigningRequest, creditV1, decodeDeliveryHeader, deliveryCodec, deliveryHeader, deriveClueKey, fundsV1, generateCreditSharedKey, generateNonce, poseidonHash, prepareWalletRequest, provenanceIntentHash, validateClueKey, validateDeliveryCiphertext, validateWalletBatch, validateWalletResponses, verifyWalletAuthorization, viewingPublicKey, walletAuthorizationTypedData };