@x1id/resolve 0.22.0 → 0.43.0

package/dist/shield.d.ts

@@ -0,0 +1,373 @@
+/**
+ * Shield: confidential zXNT / zUSDC.X on X1 (docs/specs/shield-confidential-tokens.md).
+ *
+ * What this module gives an integrator, with no dependencies and no proofs:
+ *
+ * - the Shield addresses, derived exactly like `programs/x1-shield`:
+ *   z-mint `["z-mint", backing]`, `ShieldMint` `["shield-mint", z_mint]`, the
+ *   reserve (the ShieldMint PDA's associated token account of the backing
+ *   mint) and a holder's Shield account (their Token-2022 ATA of the z-mint);
+ * - the `shield` / `unshield` instruction builders (`buildShieldIx`,
+ *   `buildUnshieldIx`);
+ * - decoders for a `ShieldMint` record and a Token-2022 account's
+ *   `ConfidentialTransferAccount` extension, plus the "ready to receive
+ *   privately" rule (spec §7);
+ * - {@link resolveShieldRecipient}: `@name` → the address to pay under the
+ *   one payment rule (verified X1 record, else the current authority), its
+ *   Shield account and whether it is ready, honouring the `x1.shield = off`
+ *   opt-out text record and refusing reserved (treasury-held) names;
+ * - payment receipts (`x1receipt1…`): a strict bech32m codec, and
+ *   {@link verifyShieldReceipt}, which finds the payment's proof data on chain
+ *   and hands it to a commitment checker.
+ *
+ * Proof generation and the elliptic-curve check of a receipt stay in the
+ * separate `shield-proofs` WASM (spec §7: "so the SDK stays light"); this
+ * module takes that check as a function (`checkCommitments`), e.g.
+ * `(r, kind, data) => wasm.verifyReceiptAgainstProof(r, kind, data)`.
+ *
+ * PDAs come through an injected {@link PdaFinder}, like every other builder in
+ * this package: it never hand-rolls the ed25519 on-curve check.
+ */
+import { type RpcFn } from "./accounts.js";
+import type { AddressLike, BuiltInstruction } from "./delegate.js";
+import type { PdaFinder } from "./namespacePricing.js";
+import { type PaymentBasis } from "./payment.js";
+import type { WasmResolver } from "./wasm.js";
+/** `programs/x1-shield` as deployed on X1 TESTNET (S1). Mainnet is not
+ *  deployed yet (owner gate S5); a mainnet deploy may use its own id, so
+ *  integrators should take the id from their network config. */
+export declare const SHIELD_PROGRAM_ID_TESTNET = "7Kqs3Nu82F1NCoUgnKEBUyW2uiftRXQjc7vJ3D2Zdzxo";
+export declare const TOKEN_2022_PROGRAM_ID = "TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb";
+/** Classic SPL Token (p-token on X1) — the wrapped-native mint's program. */
+export declare const SPL_TOKEN_PROGRAM_ID = "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA";
+export declare const ASSOCIATED_TOKEN_PROGRAM_ID = "ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL";
+export declare const ZK_ELGAMAL_PROOF_PROGRAM_ID = "ZkE1Gama1Proof11111111111111111111111111111";
+/** Wrapped-native mint: the backing of zXNT. */
+export declare const NATIVE_MINT = "So11111111111111111111111111111111111111112";
+/** USDC.X on X1 mainnet: the backing of zUSDC.X there (spec §3). */
+export declare const USDCX_MINT_MAINNET = "B69chRzqzDCmdB5WYB8NRu5Yv5ZA95ABiZcdzCgGm9Tq";
+export declare const Z_MINT_SEED = "z-mint";
+export declare const SHIELD_MINT_SEED = "shield-mint";
+/** `sha256("global:shield")[0..8]`. */
+export declare const SHIELD_DISCRIMINATOR: Uint8Array;
+/** `sha256("global:unshield")[0..8]`. */
+export declare const UNSHIELD_DISCRIMINATOR: Uint8Array;
+/** `sha256("account:ShieldMint")[0..8]`. */
+export declare const SHIELD_MINT_ACCOUNT_DISCRIMINATOR: Uint8Array;
+/** Token-2022 caps one confidential Deposit at 2^48 − 1 base units, so one
+ *  `shield` above that reverts (x1-shield FBL-0008): split it. */
+export declare const MAX_SHIELD_AMOUNT: bigint;
+/** The X1ID text record a name sets to `off` to opt out of being offered for
+ *  private payments (spec §7). */
+export declare const SHIELD_OPT_OUT_TEXT_KEY = "x1.shield";
+declare function b64ToBytes(s: string): Uint8Array;
+/** The canonical z-mint of `backingMint`: `["z-mint", backing]`. */
+export declare function deriveZMint(find: PdaFinder, programId: AddressLike, backingMint: AddressLike): Promise<string>;
+/** A z-mint's `ShieldMint` record (its mint authority and the reserve's
+ *  owner): `["shield-mint", z_mint]`. */
+export declare function deriveShieldMint(find: PdaFinder, programId: AddressLike, zMint: AddressLike): Promise<string>;
+/** Associated token account of `owner` for `mint` under `tokenProgram`. */
+export declare function deriveAssociatedTokenAccount(find: PdaFinder, owner: AddressLike, mint: AddressLike, tokenProgram: AddressLike): Promise<string>;
+/** A holder's Shield account for `zMint`: their Token-2022 ATA of it. */
+export declare function deriveShieldAccount(find: PdaFinder, owner: AddressLike, zMint: AddressLike): Promise<string>;
+export interface ShieldTokenAccounts {
+    readonly zMint: string;
+    readonly shieldMint: string;
+    /** The ShieldMint PDA's ATA of the backing mint: the 1:1 reserve. */
+    readonly reserve: string;
+}
+export interface ShieldHolderAccounts extends ShieldTokenAccounts {
+    /** The holder's Shield account (Token-2022 ATA of the z-mint). */
+    readonly zAccount: string;
+    /** The holder's backing-token ATA (wrapped-native for zXNT): the source
+     *  of a shield and the destination of an unshield. */
+    readonly backingAccount: string;
+}
+/**
+ * Derive every Shield address for `backingMint`, and for `owner` when given.
+ * `backingTokenProgram` is the backing mint's OWNER program (classic SPL Token
+ * for wrapped-native, Token-2022 for USDC.X); read it from chain for any other
+ * mint — x1-shield re-derives it and refuses a mismatch.
+ */
+export declare function deriveShieldAccounts(find: PdaFinder, p: {
+    programId: AddressLike;
+    backingMint: AddressLike;
+    backingTokenProgram: AddressLike;
+}): Promise<ShieldTokenAccounts>;
+export declare function deriveShieldAccounts(find: PdaFinder, p: {
+    programId: AddressLike;
+    backingMint: AddressLike;
+    backingTokenProgram: AddressLike;
+    owner: AddressLike;
+}): Promise<ShieldHolderAccounts>;
+export interface ShieldIxParams {
+    readonly programId: AddressLike;
+    /** The holder: signs, owns `zAccount` and `backingAccount`. */
+    readonly owner: AddressLike;
+    readonly shieldMint: AddressLike;
+    readonly zMint: AddressLike;
+    readonly backingMint: AddressLike;
+    /** shield: the backing SOURCE; unshield: the backing DESTINATION (owned by
+     *  `owner` — the program refuses anything else). */
+    readonly backingAccount: AddressLike;
+    readonly reserve: AddressLike;
+    readonly zAccount: AddressLike;
+    readonly backingTokenProgram: AddressLike;
+    /** Base units of the backing token. */
+    readonly amount: bigint;
+}
+/**
+ * `shield(amount)`: move backing into the reserve, mint exactly what arrived
+ * to the owner's Shield account and deposit it into its confidential PENDING
+ * balance. The owner's Shield account must already be configured for
+ * confidential balances. For zXNT, `backingAccount` is the owner's
+ * wrapped-native ATA, funded in the same transaction (create idempotent →
+ * system transfer → SyncNative → shield → CloseAccount; see
+ * programs/x1-shield/src/lib.rs "Client sequences").
+ */
+export declare function buildShieldIx(p: ShieldIxParams): BuiltInstruction;
+/**
+ * `unshield(amount)`: burn `amount` from the owner's PUBLIC z-balance (put
+ * there by a Token-2022 confidential Withdraw earlier in the same
+ * transaction), verify the burn, release exactly that backing to
+ * `backingAccount`. Note the account order differs from `shield`.
+ */
+export declare function buildUnshieldIx(p: ShieldIxParams): BuiltInstruction;
+/** Decoded `ShieldMint` record. */
+export interface ShieldMintState {
+    readonly zMint: string;
+    readonly backingMint: string;
+    readonly reserve: string;
+    readonly backingTokenProgram: string;
+    readonly decimals: number;
+    /** Minted by shield minus burned by unshield (informational; the truth is
+     *  z-mint supply vs reserve amount). */
+    readonly shieldedSupply: bigint;
+}
+/** `disc(8) z_mint(32) backing_mint(32) reserve(32) backing_token_program(32)
+ *  decimals(1) shielded_supply(8) bump(1) z_mint_bump(1)`. Null when the bytes
+ *  are not a ShieldMint. */
+export declare function parseShieldMint(data: Uint8Array): ShieldMintState | null;
+/** `ExtensionType::ConfidentialTransferAccount`. */
+export declare const EXT_CONFIDENTIAL_TRANSFER_ACCOUNT = 5;
+/** The `ConfidentialTransferAccount` extension: every encrypted balance. */
+export interface ConfidentialAccountState {
+    readonly approved: boolean;
+    /** The account's ElGamal public key — what a payer encrypts to, and what a
+     *  wallet's key derivation must reproduce (epoch lookup). */
+    readonly elgamalPubkey: Uint8Array;
+    readonly pendingLo: Uint8Array;
+    readonly pendingHi: Uint8Array;
+    /** Available balance ElGamal ciphertext (64 B). */
+    readonly available: Uint8Array;
+    /** Owner-decryptable AES ciphertext of the available balance (36 B). */
+    readonly decryptable: Uint8Array;
+    readonly allowConfidentialCredits: boolean;
+    readonly allowNonConfidentialCredits: boolean;
+    /** Credits since the last ApplyPendingBalance — the expected counter an
+     *  apply must name. */
+    readonly pendingCreditCounter: bigint;
+    readonly maxPendingCreditCounter: bigint;
+}
+export interface DecodedTokenAccount {
+    readonly mint: string;
+    readonly owner: string;
+    /** Public (non-confidential) balance. */
+    readonly amount: bigint;
+    readonly ct: ConfidentialAccountState | null;
+}
+/** Decode a Token-2022 token account and its confidential extension. Null
+ *  when the bytes are not a token account. Pure. */
+export declare function decodeConfidentialTokenAccount(data: Uint8Array): DecodedTokenAccount | null;
+export type ShieldReadiness = {
+    readonly kind: "ready";
+    readonly elgamalPubkey: Uint8Array;
+}
+/** No account at the derived Shield address yet. */
+ | {
+    readonly kind: "no-account";
+}
+/** The account exists but isn't set up for confidential balances. */
+ | {
+    readonly kind: "not-configured";
+}
+/** Configured, but not approved or refusing confidential credits. */
+ | {
+    readonly kind: "not-accepting";
+}
+/** The bytes at the derived address aren't this owner's account of this
+ *  z-mint (or aren't a Token-2022 account at all). */
+ | {
+    readonly kind: "mismatch";
+}
+/** The name's owner opted out (`x1.shield = off`). */
+ | {
+    readonly kind: "opted-out";
+};
+/** True for the opt-out text record's value (`off`, any case/whitespace). */
+export declare function isShieldOptOut(value: string | null | undefined): boolean;
+/**
+ * Judge readiness to receive privately (spec §7) from the account at the
+ * derived Shield address: `account` is `{ data, owner }` as read from chain
+ * (null = no account). Pure.
+ */
+export declare function shieldReadiness(account: {
+    readonly data: Uint8Array;
+    readonly owner: string;
+} | null, expected: {
+    readonly owner: string;
+    readonly zMint: string;
+}, optedOut?: boolean): ShieldReadiness;
+export interface ShieldRecipientConfig {
+    /** X1 RPC endpoint. */
+    readonly rpcUrl: string;
+    /** Account derivation + handle normalization (see {@link WasmResolver}). */
+    readonly wasm: WasmResolver;
+    /** `find_program_address` for the Shield-account (ATA) and config PDAs. */
+    readonly find: PdaFinder;
+    /** @handle registry program id (default: the canonical deployment). */
+    readonly handleProgramId: string;
+    /** The registry's `Config.treasury`. Omit to read it from chain. A name
+     *  whose payment target is the treasury is a reserved name. */
+    readonly treasury?: string;
+    readonly fetchImpl?: typeof fetch;
+}
+export interface ShieldRecipient {
+    /** Canonical handle (no `@`). */
+    readonly name: string;
+    /** The registry `Handle` account (e.g. to check its lease). */
+    readonly handleAccount: string;
+    /** The wallet a private payment is for (the one payment rule, W16). */
+    readonly address: string;
+    /** Why `address`: a verified X1 record, or the current authority. Show it. */
+    readonly basis: PaymentBasis;
+    /** That wallet's Shield account for the z-mint. */
+    readonly zAccount: string;
+    /** True iff `zAccount` exists with confidential balances configured,
+     *  approved and accepting confidential credits, AND the name has not opted
+     *  out. Pay privately only when true. */
+    readonly ataReady: boolean;
+    readonly readiness: ShieldReadiness;
+    /** The recipient's ElGamal key (what a payment encrypts to) when ready. */
+    readonly elgamalPubkey: Uint8Array | null;
+}
+/**
+ * Resolve an @name for a private payment in `zMint` (spec §7):
+ *
+ * 1. the name's payment address under the one rule (`paymentAddressFor`): a
+ *    live VERIFIED X1 record, else the current authority (`Handle.owner`, or
+ *    the pNFT holder of a tokenized name);
+ * 2. a reserved name (its payment target is the registry treasury) is
+ *    REFUSED — `ResolveError("reserved")`;
+ * 3. the recipient's Shield account (their Token-2022 ATA of `zMint`) is read
+ *    from chain: `ataReady` iff it is configured for confidential balances;
+ * 4. a live `x1.shield = off` text record makes the name not ready
+ *    (`readiness.kind === "opted-out"`), however its account looks.
+ *
+ * No X1ID record is needed to receive privately; readiness is chain state.
+ */
+export declare function resolveShieldRecipient(name: string, zMint: AddressLike, config: ShieldRecipientConfig): Promise<ShieldRecipient>;
+/** bech32m-encode `bytes` under `hrp` (no 90-char limit: receipts are long). */
+export declare function bech32mEncode(hrp: string, bytes: Uint8Array): string;
+/** Strict bech32m decode: right checksum constant (not BIP-173 bech32), no
+ *  mixed case, the expected `hrp`. Null on any failure. */
+export declare function bech32mDecode(s: string, hrp: string): Uint8Array | null;
+export declare const SHIELD_RECEIPT_HRP = "x1receipt";
+/** A decoded `x1receipt1…`: `version 1 ‖ tx signature 64 ‖ mint 32 ‖ amount
+ *  u64 LE ‖ opening lo 32 ‖ opening hi 32` (crates/shield-proofs receipt.rs). */
+export interface ShieldReceipt {
+    /** The payment transaction id (base58). */
+    readonly txSignature: string;
+    /** The z-mint paid in (base58). */
+    readonly mint: string;
+    /** Base units. */
+    readonly amount: bigint;
+    /** Pedersen openings of the amount's lo/hi commitments. They prove only
+     *  this payment's amount; they reveal nothing else about either account. */
+    readonly openingLo: Uint8Array;
+    readonly openingHi: Uint8Array;
+}
+export declare function encodeShieldReceipt(r: ShieldReceipt): string;
+/** Decode a receipt string. Null when it isn't a valid v1 receipt. */
+export declare function decodeShieldReceipt(s: string): ShieldReceipt | null;
+/**
+ * Pull a receipt out of what someone pasted or scanned: the bare string,
+ * with whitespace or line breaks, or a `…/receipt?r=…` link. Returns the
+ * normalized lowercase receipt only when it decodes; null otherwise.
+ */
+export declare function extractShieldReceipt(input: string): string | null;
+/** `ProofType` of the two proofs that carry a transfer's amount commitments. */
+export declare const PROOF_TYPE_BATCHED_GROUPED_3_HANDLES_VALIDITY = 12;
+export declare const PROOF_TYPE_BATCHED_RANGE_U128 = 7;
+/** One confidential payment, as found on chain. */
+export interface ShieldPayment {
+    readonly txSignature: string;
+    readonly slot: number;
+    readonly blockTime: number | null;
+    readonly zMint: string;
+    /** The paying wallet (the Transfer's signer). */
+    readonly sender: string;
+    readonly sourceAccount: string;
+    readonly destinationAccount: string;
+    /** The amount's Pedersen commitments (lo, hi) as the Transfer instruction
+     *  itself carries them: the first 32 bytes of its auditor ciphertexts,
+     *  which Token-2022 requires to equal the consumed validity proof's. */
+    readonly amountCommitmentLo: Uint8Array;
+    readonly amountCommitmentHi: Uint8Array;
+    /** `BatchedGroupedCiphertext3HandlesValidityProofData` (carries the amount
+     *  ciphertexts and the source/destination ElGamal keys), only when one was
+     *  found whose commitments equal the Transfer's own; null otherwise. */
+    readonly validityProof: Uint8Array | null;
+}
+/**
+ * Find a confidential payment and the proof data its amount lives in. The
+ * Transfer's accounts are decoded from its proof-offset bytes (an inline
+ * proof in the same transaction, or a context-state account plus the
+ * Instructions sysvar). For a context account the proof bytes come from the
+ * staging transaction that verified the 3-handle validity proof into it
+ * (crates/shield-proofs README, "S-2"), which depends on the RPC node still
+ * holding that transaction. Either way a proof is used only when its
+ * commitments equal the ones in the Transfer instruction, which Token-2022
+ * checked against the proof it consumed. Null when `txSignature` isn't a
+ * successful Token-2022 confidential transfer.
+ */
+export declare function findShieldPayment(rpc: RpcFn, txSignature: string): Promise<ShieldPayment | null>;
+/**
+ * The amount ciphertexts of a payment as seen by one party (`"source"` or
+ * `"destination"`): 64-byte ElGamal ciphertexts `commitment ‖ that party's
+ * handle` for the amount's lo (16-bit) and hi (32-bit) parts. Decrypt with
+ * the party's keys as `lo + hi·2^16` (shield-proofs `decryptPending(lo, hi)`
+ * does exactly that). Also returns the party's ElGamal key from the proof so
+ * a caller can check it is theirs. Null on malformed data.
+ */
+export declare function paymentAmountCiphertexts(validityProof: Uint8Array, party: "source" | "destination"): {
+    readonly lo: Uint8Array;
+    readonly hi: Uint8Array;
+    readonly elgamalPubkey: Uint8Array;
+} | null;
+export type ShieldReceiptVerdict = {
+    readonly ok: true;
+    readonly amount: bigint;
+    readonly zMint: string;
+    readonly txSignature: string;
+    readonly blockTime: number | null;
+    readonly sender: string;
+    readonly recipientAccount: string;
+} | {
+    readonly ok: false;
+    readonly reason: "malformed" | "not-found" | "not-a-payment" | "wrong-token" | "no-proof-history" | "mismatch";
+};
+/**
+ * Verify a receipt against the chain: decode it, find the payment
+ * ({@link findShieldPayment}), check the z-mint, and ask `checkCommitments`
+ * (the shield-proofs WASM's `verifyReceiptAgainstProof`) whether the
+ * receipt's amount and openings reproduce the commitments in the payment's
+ * own validity proof: the one whose commitments equal the Transfer
+ * instruction's (Sentinel FBL-0009). Anyone can run it; it needs no keys.
+ */
+export declare function verifyShieldReceipt(receipt: string, opts: {
+    readonly rpc: RpcFn;
+    readonly checkCommitments: (receipt: string, proofType: number, proofData: Uint8Array) => boolean | Promise<boolean>;
+}): Promise<ShieldReceiptVerdict>;
+/** Re-exported for callers that want to read account bytes the same way. */
+export { b64ToBytes as shieldBase64ToBytes };