@chainpayhq/sdk 0.0.0-stage → 0.1.0

package/dist/delivery.d.ts

@@ -0,0 +1,66 @@
+import type { Address, PaymentReceipt } from "./types.js";
+export declare const DELIVERY_STATEMENT = "chainpay.response-served";
+export declare const DELIVERY_VERSION = 1;
+export declare const DELIVERY_CLUSTER = "devnet";
+/**
+ * Exact UTF-8 body for the cross-language content-hash fixture.
+ * Includes non-ASCII and whitespace that must hash as transmitted bytes.
+ */
+export declare const DELIVERY_HASH_FIXTURE_UTF8 = "ChainPay served body: caf\u00E9\n\t ";
+/** SHA-256 lowercase hex of {@link DELIVERY_HASH_FIXTURE_UTF8}. */
+export declare const DELIVERY_HASH_FIXTURE_SHA256 = "8e60b641218418bde0cde3b190a028e846ccebed8dc804901b8e6f87b9072eee";
+/** Test-only seller seed (32 bytes of 0x07). Not a live merchant key. */
+export declare const DELIVERY_FIXTURE_SELLER_SEED: Uint8Array<ArrayBuffer>;
+export declare const DELIVERY_FIXTURE_RECEIPT_ADDRESS = "2KW2XRd9kwqet15Aha2oK3tYvd3nWbTFH1MBiRAv1BE1";
+export declare const DELIVERY_FIXTURE_SELLER_ADDRESS = "GmaDrppBC7P5ARKV8g3djiwP89vz1jLK23V2GBjuAEGB";
+/** Exact canonical JSON bytes for cross-language signature fixtures. */
+export declare const DELIVERY_CANONICAL_FIXTURE_JSON = "{\"version\":1,\"statement\":\"chainpay.response-served\",\"cluster\":\"devnet\",\"programId\":\"3H9TV1EPR2BAQgVmcMqpufiZKPXbAMnjHp13LA9Lndv4\",\"receiptAddress\":\"2KW2XRd9kwqet15Aha2oK3tYvd3nWbTFH1MBiRAv1BE1\",\"seller\":\"GmaDrppBC7P5ARKV8g3djiwP89vz1jLK23V2GBjuAEGB\",\"contentHash\":\"8e60b641218418bde0cde3b190a028e846ccebed8dc804901b8e6f87b9072eee\",\"servedAt\":\"2026-09-15T04:16:00.000Z\"}";
+/** Deterministic Ed25519 signature over {@link DELIVERY_CANONICAL_FIXTURE_JSON}. */
+export declare const DELIVERY_CANONICAL_FIXTURE_SIGNATURE = "K+hQlY/7U7cbhE2229fk/C2g5MHUahSrhBZz4F3SUxTqyVvLgfV0gZkPosZKdFZzIXbawLS3xJQ3XsrtYXqIDg==";
+export type DeliveryAttestationPayload = {
+    version: 1;
+    statement: typeof DELIVERY_STATEMENT;
+    cluster: typeof DELIVERY_CLUSTER;
+    programId: Address;
+    receiptAddress: Address;
+    seller: Address;
+    contentHash: string;
+    servedAt: string;
+};
+export type SignedDeliveryAttestation = {
+    payload: DeliveryAttestationPayload;
+    signature: string;
+};
+export type TrustedSellerMapping = {
+    cluster: typeof DELIVERY_CLUSTER;
+    programId: Address;
+    /** Seller signing public keys. These are identities, not ATA addresses. */
+    sellers: readonly Address[];
+    recipientTokenAccount?: Address;
+};
+export type DeliveryVerification = {
+    valid: boolean;
+    payload?: DeliveryAttestationPayload;
+    reason?: string;
+    code?: string;
+};
+export type VerifyDeliveryOptions = {
+    trustedSellers?: TrustedSellerMapping;
+    receipt?: Pick<PaymentReceipt, "address" | "recipientTokenAccount">;
+    programId?: Address;
+    now?: Date;
+    maxFutureSkewMs?: number;
+};
+export declare function bytesToCanonicalBase64(bytes: Uint8Array): string;
+export declare function canonicalBase64ToBytes(value: string): Uint8Array;
+export declare function sha256HexBytes(bytes: Uint8Array): Promise<string>;
+/**
+ * Reject unsupported version and unknown fields before any
+ * canonical JSON is produced. This ordering is load-bearing.
+ */
+export declare function parseDeliveryPayload(value: unknown): DeliveryAttestationPayload;
+export declare function parseDeliveryEnvelope(value: unknown): SignedDeliveryAttestation;
+export declare function canonicalDeliveryPayload(payload: DeliveryAttestationPayload): string;
+export declare function signDeliveryAttestation(payload: unknown, secretKey: Uint8Array): Promise<SignedDeliveryAttestation>;
+export declare function verifyDeliveryAttestation(envelope: unknown, options?: VerifyDeliveryOptions): Promise<DeliveryVerification>;
+export declare function defaultTrustedSellerMapping(sellers: readonly Address[], programId?: Address): TrustedSellerMapping;

package/dist/delivery.js

@@ -0,0 +1,232 @@
+import { PublicKey } from "@solana/web3.js";
+import { address } from "./encoding.js";
+import { DEFAULT_PROGRAM_ID } from "./constants.js";
+export const DELIVERY_STATEMENT = "chainpay.response-served";
+export const DELIVERY_VERSION = 1;
+export const DELIVERY_CLUSTER = "devnet";
+const PAYLOAD_KEYS = [
+    "version",
+    "statement",
+    "cluster",
+    "programId",
+    "receiptAddress",
+    "seller",
+    "contentHash",
+    "servedAt",
+];
+const ENVELOPE_KEYS = ["payload", "signature"];
+const CONTENT_HASH_PATTERN = /^[0-9a-f]{64}$/;
+const CANONICAL_UTC_ISO = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/;
+const CANONICAL_BASE64 = /^[A-Za-z0-9+/]+={0,2}$/;
+const ED25519_PKCS8_PREFIX = Uint8Array.from([
+    0x30, 0x2e, 0x02, 0x01, 0x00, 0x30, 0x05, 0x06, 0x03, 0x2b, 0x65, 0x70, 0x04, 0x22, 0x04, 0x20,
+]);
+/**
+ * Exact UTF-8 body for the cross-language content-hash fixture.
+ * Includes non-ASCII and whitespace that must hash as transmitted bytes.
+ */
+export const DELIVERY_HASH_FIXTURE_UTF8 = "ChainPay served body: café\n\t ";
+/** SHA-256 lowercase hex of {@link DELIVERY_HASH_FIXTURE_UTF8}. */
+export const DELIVERY_HASH_FIXTURE_SHA256 = "8e60b641218418bde0cde3b190a028e846ccebed8dc804901b8e6f87b9072eee";
+/** Test-only seller seed (32 bytes of 0x07). Not a live merchant key. */
+export const DELIVERY_FIXTURE_SELLER_SEED = Uint8Array.from({ length: 32 }, () => 7);
+export const DELIVERY_FIXTURE_RECEIPT_ADDRESS = "2KW2XRd9kwqet15Aha2oK3tYvd3nWbTFH1MBiRAv1BE1";
+export const DELIVERY_FIXTURE_SELLER_ADDRESS = "GmaDrppBC7P5ARKV8g3djiwP89vz1jLK23V2GBjuAEGB";
+/** Exact canonical JSON bytes for cross-language signature fixtures. */
+export const DELIVERY_CANONICAL_FIXTURE_JSON = '{"version":1,"statement":"chainpay.response-served","cluster":"devnet","programId":"3H9TV1EPR2BAQgVmcMqpufiZKPXbAMnjHp13LA9Lndv4","receiptAddress":"2KW2XRd9kwqet15Aha2oK3tYvd3nWbTFH1MBiRAv1BE1","seller":"GmaDrppBC7P5ARKV8g3djiwP89vz1jLK23V2GBjuAEGB","contentHash":"8e60b641218418bde0cde3b190a028e846ccebed8dc804901b8e6f87b9072eee","servedAt":"2026-09-15T04:16:00.000Z"}';
+/** Deterministic Ed25519 signature over {@link DELIVERY_CANONICAL_FIXTURE_JSON}. */
+export const DELIVERY_CANONICAL_FIXTURE_SIGNATURE = "K+hQlY/7U7cbhE2229fk/C2g5MHUahSrhBZz4F3SUxTqyVvLgfV0gZkPosZKdFZzIXbawLS3xJQ3XsrtYXqIDg==";
+function isPlainObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function unknownKeys(value, allowed) {
+    return Object.keys(value).filter((key) => !allowed.includes(key));
+}
+function validationError(reason, code, payload) {
+    return { valid: false, reason, code, ...(payload ? { payload } : {}) };
+}
+function isCanonicalUtcIso(value) {
+    if (!CANONICAL_UTC_ISO.test(value))
+        return false;
+    const parsed = Date.parse(value);
+    if (!Number.isFinite(parsed))
+        return false;
+    return new Date(parsed).toISOString() === value;
+}
+function ed25519Seed(secretKey) {
+    if (secretKey.length === 32)
+        return new Uint8Array(secretKey);
+    if (secretKey.length === 64)
+        return new Uint8Array(secretKey.subarray(0, 32));
+    throw new Error("Ed25519 secret key must be 32 or 64 bytes");
+}
+function pkcs8FromSeed(seed) {
+    const pkcs8 = new Uint8Array(ED25519_PKCS8_PREFIX.length + 32);
+    pkcs8.set(ED25519_PKCS8_PREFIX);
+    pkcs8.set(seed, ED25519_PKCS8_PREFIX.length);
+    return pkcs8.buffer.slice(pkcs8.byteOffset, pkcs8.byteOffset + pkcs8.byteLength);
+}
+export function bytesToCanonicalBase64(bytes) {
+    let binary = "";
+    for (const byte of bytes)
+        binary += String.fromCharCode(byte);
+    return btoa(binary);
+}
+export function canonicalBase64ToBytes(value) {
+    if (!CANONICAL_BASE64.test(value) || value.length % 4 !== 0) {
+        throw new Error("Delivery signature must be canonical base64");
+    }
+    const binary = atob(value);
+    return Uint8Array.from(binary, (character) => character.charCodeAt(0));
+}
+export async function sha256HexBytes(bytes) {
+    const digest = await globalThis.crypto.subtle.digest("SHA-256", bytes.slice().buffer);
+    return Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+/**
+ * Reject unsupported version and unknown fields before any
+ * canonical JSON is produced. This ordering is load-bearing.
+ */
+export function parseDeliveryPayload(value) {
+    if (!isPlainObject(value)) {
+        throw new Error("Delivery payload must be an object");
+    }
+    if (!Object.prototype.hasOwnProperty.call(value, "version") || value.version !== DELIVERY_VERSION) {
+        throw new Error("Unsupported delivery attestation version");
+    }
+    const extra = unknownKeys(value, PAYLOAD_KEYS);
+    if (extra.length > 0) {
+        throw new Error(`Unknown delivery attestation field: ${extra[0]}`);
+    }
+    if (value.statement !== DELIVERY_STATEMENT) {
+        throw new Error("Unsupported delivery statement");
+    }
+    if (value.cluster !== DELIVERY_CLUSTER) {
+        throw new Error("Unsupported delivery cluster");
+    }
+    if (typeof value.contentHash !== "string" || !CONTENT_HASH_PATTERN.test(value.contentHash)) {
+        throw new Error("contentHash must be 64-char lowercase SHA-256 hex");
+    }
+    if (typeof value.servedAt !== "string" || !isCanonicalUtcIso(value.servedAt)) {
+        throw new Error("servedAt must be a canonical UTC ISO-8601 timestamp");
+    }
+    if (typeof value.programId !== "string" || typeof value.receiptAddress !== "string" || typeof value.seller !== "string") {
+        throw new Error("programId, receiptAddress, and seller must be Solana addresses");
+    }
+    return {
+        version: 1,
+        statement: DELIVERY_STATEMENT,
+        cluster: DELIVERY_CLUSTER,
+        programId: address(value.programId),
+        receiptAddress: address(value.receiptAddress),
+        seller: address(value.seller),
+        contentHash: value.contentHash,
+        servedAt: value.servedAt,
+    };
+}
+export function parseDeliveryEnvelope(value) {
+    if (!isPlainObject(value)) {
+        throw new Error("Delivery attestation must be an object");
+    }
+    const extra = unknownKeys(value, ENVELOPE_KEYS);
+    if (extra.length > 0) {
+        throw new Error(`Unknown delivery envelope field: ${extra[0]}`);
+    }
+    if (typeof value.signature !== "string") {
+        throw new Error("Delivery signature is required");
+    }
+    return {
+        payload: parseDeliveryPayload(value.payload),
+        signature: value.signature,
+    };
+}
+export function canonicalDeliveryPayload(payload) {
+    const parsed = parseDeliveryPayload(payload);
+    return JSON.stringify({
+        version: 1,
+        statement: DELIVERY_STATEMENT,
+        cluster: DELIVERY_CLUSTER,
+        programId: parsed.programId,
+        receiptAddress: parsed.receiptAddress,
+        seller: parsed.seller,
+        contentHash: parsed.contentHash,
+        servedAt: parsed.servedAt,
+    });
+}
+export async function signDeliveryAttestation(payload, secretKey) {
+    const parsed = parseDeliveryPayload(payload);
+    const message = new TextEncoder().encode(canonicalDeliveryPayload(parsed));
+    const key = await globalThis.crypto.subtle.importKey("pkcs8", pkcs8FromSeed(ed25519Seed(secretKey)), { name: "Ed25519" }, false, ["sign"]);
+    const signature = new Uint8Array(await globalThis.crypto.subtle.sign("Ed25519", key, message.slice().buffer));
+    return { payload: parsed, signature: bytesToCanonicalBase64(signature) };
+}
+function trustedSellerAllows(payload, mapping) {
+    if (mapping.cluster !== payload.cluster)
+        return "Delivery cluster is not trusted";
+    if (address(mapping.programId) !== payload.programId)
+        return "Delivery programId is not trusted";
+    const allowed = new Set(mapping.sellers.map((seller) => address(seller)));
+    if (!allowed.has(payload.seller))
+        return "Unknown delivery seller";
+    return undefined;
+}
+export async function verifyDeliveryAttestation(envelope, options = {}) {
+    let parsed;
+    try {
+        parsed = parseDeliveryEnvelope(envelope);
+    }
+    catch (error) {
+        return validationError(error instanceof Error ? error.message : String(error), "invalid_payload");
+    }
+    try {
+        // Fail closed on identity. Without a trusted-seller mapping the only thing
+        // left to check is that the payload is signed by the key the payload itself
+        // names, which any anonymous poster can satisfy with a throwaway keypair.
+        // Every caller in this repo already passes a mapping; this stops the next
+        // one from accidentally accepting a self-signed statement.
+        if (!options.trustedSellers) {
+            return validationError("A trusted seller mapping is required to verify a delivery attestation.", "unknown_seller", parsed.payload);
+        }
+        {
+            const trustError = trustedSellerAllows(parsed.payload, options.trustedSellers);
+            if (trustError)
+                return validationError(trustError, "unknown_seller", parsed.payload);
+            if (options.trustedSellers.recipientTokenAccount
+                && options.receipt
+                && address(options.trustedSellers.recipientTokenAccount) !== address(options.receipt.recipientTokenAccount)) {
+                return validationError("Trusted seller does not match receipt recipient", "recipient_mismatch", parsed.payload);
+            }
+        }
+        if (options.programId && address(options.programId) !== parsed.payload.programId) {
+            return validationError("Delivery programId does not match expected program", "program_mismatch", parsed.payload);
+        }
+        if (options.receipt && address(options.receipt.address) !== parsed.payload.receiptAddress) {
+            return validationError("Delivery receiptAddress does not match the receipt", "receipt_mismatch", parsed.payload);
+        }
+        const now = options.now ?? new Date();
+        const servedAt = Date.parse(parsed.payload.servedAt);
+        const maxFutureSkewMs = options.maxFutureSkewMs ?? 5 * 60_000;
+        if (servedAt - now.getTime() > maxFutureSkewMs) {
+            return validationError("Delivery servedAt is unreasonably far in the future", "invalid_timestamp", parsed.payload);
+        }
+        const signature = canonicalBase64ToBytes(parsed.signature);
+        if (signature.length !== 64)
+            return validationError("Ed25519 signature must be 64 bytes", "invalid_signature", parsed.payload);
+        const key = await globalThis.crypto.subtle.importKey("raw", new PublicKey(parsed.payload.seller).toBytes().slice().buffer, { name: "Ed25519" }, false, ["verify"]);
+        const message = new TextEncoder().encode(canonicalDeliveryPayload(parsed.payload));
+        const validSignature = await globalThis.crypto.subtle.verify("Ed25519", key, signature.slice().buffer, message.slice().buffer);
+        if (!validSignature)
+            return validationError("Delivery signature is invalid", "invalid_signature", parsed.payload);
+        return { valid: true, payload: parsed.payload };
+    }
+    catch (error) {
+        return validationError(error instanceof Error ? error.message : String(error), "invalid_payload", parsed.payload);
+    }
+}
+export function defaultTrustedSellerMapping(sellers, programId = DEFAULT_PROGRAM_ID) {
+    return {
+        cluster: DELIVERY_CLUSTER,
+        programId: address(programId),
+        sellers: sellers.map((seller) => address(seller)),
+    };
+}

package/dist/encoding.d.ts

@@ -0,0 +1,51 @@
+import { PublicKey } from "@solana/web3.js";
+import type { AccountMeta, Address, ChainPayInstruction, TokenProgram } from "./types.js";
+export declare function publicKey(value: Address): PublicKey;
+export declare function address(value: Address): Address;
+export declare function bytes32(value: Uint8Array, name: string): Uint8Array;
+export declare function writeU64(value: bigint, name: string): Uint8Array;
+export declare function readU64(data: Uint8Array, offset: number): bigint;
+export declare function readU8(data: Uint8Array, offset: number): number;
+export declare function readBytes32(data: Uint8Array, offset: number, name: string): Uint8Array;
+export declare function assertDiscriminator(data: Uint8Array, discriminator: Uint8Array, accountName: string): void;
+export declare function readPublicKey(data: Uint8Array, offset: number): Address;
+export declare function isMandateNonce(value: Address): boolean;
+export declare function concat(...parts: Uint8Array[]): Uint8Array;
+export declare function meta(value: Address, isWritable?: boolean, isSigner?: boolean): AccountMeta;
+export declare function tokenProgramAddress(tokenProgram: TokenProgram): Address;
+export declare function tokenProgramFromAddress(value: Address): TokenProgram | undefined;
+export declare function instruction(name: string, programId: Address, keys: AccountMeta[], data: Uint8Array): ChainPayInstruction;
+export declare function encodeCreateMandate(params: {
+    approvedAgent: Address;
+    sourceTokenAccount: Address;
+    allowedMint: Address;
+    maxPerPayment: bigint;
+    totalLimit: bigint;
+    expiresAtSlot: bigint;
+    maxPaymentCount: bigint;
+    cooldownSlots: bigint;
+    mandateNonce: Address;
+}): Uint8Array;
+export declare function encodeInitializeConfig(supportedMints: readonly Address[]): Uint8Array;
+export declare function encodeRegisterAsset(mint: Address): Uint8Array;
+export declare function encodeSetAssetStatus(enabled: boolean): Uint8Array;
+export declare function encodeUpdateMandate(params: {
+    approvedAgent: Address;
+    maxPerPayment: bigint;
+    totalLimit: bigint;
+    expiresAtSlot: bigint;
+    maxPaymentCount: bigint;
+    cooldownSlots: bigint;
+    paused: boolean;
+}): Uint8Array;
+export declare function encodePayment(params: {
+    invoiceHash: Uint8Array;
+    paymentId: Uint8Array;
+    signatureReference: Uint8Array;
+    amount: bigint;
+}): Uint8Array;
+export declare function encodePauseMandate(): Uint8Array;
+export declare function encodeRevokeMandate(): Uint8Array;
+export declare function encodeApproveChecked(amount: bigint, decimals: number): Uint8Array;
+export declare function encodeRevokeDelegate(): Uint8Array;
+export declare function systemProgramMeta(): AccountMeta;

package/dist/encoding.js

@@ -0,0 +1,128 @@
+import { PublicKey } from "@solana/web3.js";
+import { DISCRIMINATORS, MANDATE_NONCE_PREFIX, SYSTEM_PROGRAM_ID } from "./constants.js";
+export function publicKey(value) {
+    try {
+        return new PublicKey(value);
+    }
+    catch {
+        throw new Error(`Invalid Solana address: ${value}`);
+    }
+}
+export function address(value) {
+    return publicKey(value).toBase58();
+}
+export function bytes32(value, name) {
+    if (value.length !== 32)
+        throw new Error(`${name} must be exactly 32 bytes`);
+    return new Uint8Array(value);
+}
+export function writeU64(value, name) {
+    if (value < 0n || value > 18446744073709551615n) {
+        throw new Error(`${name} must fit in an unsigned 64-bit integer`);
+    }
+    const bytes = new Uint8Array(8);
+    new DataView(bytes.buffer).setBigUint64(0, value, true);
+    return bytes;
+}
+export function readU64(data, offset) {
+    if (offset + 8 > data.length)
+        throw new Error("Account data ended while reading u64");
+    return new DataView(data.buffer, data.byteOffset + offset, 8).getBigUint64(0, true);
+}
+export function readU8(data, offset) {
+    if (offset >= data.length)
+        throw new Error("Account data ended while reading u8");
+    return data[offset];
+}
+export function readBytes32(data, offset, name) {
+    if (offset + 32 > data.length) {
+        throw new Error(`Account data ended while reading ${name}`);
+    }
+    return new Uint8Array(data.slice(offset, offset + 32));
+}
+export function assertDiscriminator(data, discriminator, accountName) {
+    if (data.length < discriminator.length) {
+        throw new Error(`${accountName} account data is truncated`);
+    }
+    for (let index = 0; index < discriminator.length; index += 1) {
+        if (data[index] !== discriminator[index]) {
+            throw new Error(`Invalid ${accountName} account discriminator`);
+        }
+    }
+}
+export function readPublicKey(data, offset) {
+    if (offset + 32 > data.length)
+        throw new Error("Account data ended while reading public key");
+    return new PublicKey(data.slice(offset, offset + 32)).toBase58();
+}
+export function isMandateNonce(value) {
+    const bytes = publicKey(value).toBytes();
+    return MANDATE_NONCE_PREFIX.every((byte, index) => bytes[index] === byte);
+}
+export function concat(...parts) {
+    const result = new Uint8Array(parts.reduce((total, part) => total + part.length, 0));
+    let offset = 0;
+    for (const part of parts) {
+        result.set(part, offset);
+        offset += part.length;
+    }
+    return result;
+}
+export function meta(value, isWritable = false, isSigner = false) {
+    return { address: address(value), isWritable, isSigner };
+}
+export function tokenProgramAddress(tokenProgram) {
+    return tokenProgram === "token-2022"
+        ? "TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb"
+        : "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA";
+}
+export function tokenProgramFromAddress(value) {
+    const normalized = address(value);
+    if (normalized === tokenProgramAddress("spl-token"))
+        return "spl-token";
+    if (normalized === tokenProgramAddress("token-2022"))
+        return "token-2022";
+    return undefined;
+}
+export function instruction(name, programId, keys, data) {
+    return { name, programId: address(programId), keys, data: new Uint8Array(data) };
+}
+export function encodeCreateMandate(params) {
+    return concat(DISCRIMINATORS.createMandate, publicKey(params.approvedAgent).toBytes(), publicKey(params.sourceTokenAccount).toBytes(), publicKey(params.allowedMint).toBytes(), writeU64(params.maxPerPayment, "maxPerPayment"), writeU64(params.totalLimit, "totalLimit"), writeU64(params.expiresAtSlot, "expiresAtSlot"), writeU64(params.maxPaymentCount, "maxPaymentCount"), writeU64(params.cooldownSlots, "cooldownSlots"), publicKey(params.mandateNonce).toBytes());
+}
+export function encodeInitializeConfig(supportedMints) {
+    if (supportedMints.length !== 3) {
+        throw new Error("initialize_config requires exactly three mint slots");
+    }
+    return concat(DISCRIMINATORS.initializeConfig, ...supportedMints.map((mint) => publicKey(mint).toBytes()));
+}
+export function encodeRegisterAsset(mint) {
+    return concat(DISCRIMINATORS.registerAsset, publicKey(mint).toBytes());
+}
+export function encodeSetAssetStatus(enabled) {
+    return concat(DISCRIMINATORS.setAssetStatus, Uint8Array.of(enabled ? 1 : 0));
+}
+export function encodeUpdateMandate(params) {
+    return concat(DISCRIMINATORS.updateMandate, publicKey(params.approvedAgent).toBytes(), writeU64(params.maxPerPayment, "maxPerPayment"), writeU64(params.totalLimit, "totalLimit"), writeU64(params.expiresAtSlot, "expiresAtSlot"), writeU64(params.maxPaymentCount, "maxPaymentCount"), writeU64(params.cooldownSlots, "cooldownSlots"), Uint8Array.of(params.paused ? 1 : 0));
+}
+export function encodePayment(params) {
+    return concat(DISCRIMINATORS.executePayment, bytes32(params.invoiceHash, "invoiceHash"), bytes32(params.paymentId, "paymentId"), bytes32(params.signatureReference, "signatureReference"), writeU64(params.amount, "amount"));
+}
+export function encodePauseMandate() {
+    return new Uint8Array(DISCRIMINATORS.pauseMandate);
+}
+export function encodeRevokeMandate() {
+    return new Uint8Array(DISCRIMINATORS.revokeMandate);
+}
+export function encodeApproveChecked(amount, decimals) {
+    if (!Number.isInteger(decimals) || decimals < 0 || decimals > 255) {
+        throw new Error("Token decimals must be between 0 and 255");
+    }
+    return concat(DISCRIMINATORS.approveChecked, writeU64(amount, "delegateAmount"), Uint8Array.of(decimals));
+}
+export function encodeRevokeDelegate() {
+    return new Uint8Array(DISCRIMINATORS.revokeDelegate);
+}
+export function systemProgramMeta() {
+    return meta(SYSTEM_PROGRAM_ID);
+}

package/dist/index.d.ts

@@ -0,0 +1,27 @@
+export * from "./accounts.js";
+export * from "./client.js";
+export * from "./constants.js";
+export * from "./crossmint-adapt.js";
+export * from "./crossmint-order.js";
+export * from "./delivery.js";
+export * from "./encoding.js";
+export * from "./known-assets.js";
+export * from "./mandate.js";
+export * from "./ops-snapshot.js";
+export * from "./payment.js";
+export * from "./payment-request.js";
+export * from "./mandate-request.js";
+export * from "./pda.js";
+export * from "./receipt.js";
+export * from "./receipt-export.js";
+export * from "./solana.js";
+export * from "./token.js";
+export * from "./token-capabilities.js";
+export * from "./types.js";
+export * from "./x402.js";
+export * from "./x402-challenge.js";
+export * from "./x402-adapt.js";
+export * from "./cards/index.js";
+export { decodeSupportedTransaction } from "./transaction-reader.js";
+export { DEFAULT_TRANSACTION_VERSION, V1_COMPUTE_UNIT_LIMIT, V1_LOADED_ACCOUNTS_DATA_SIZE_LIMIT, compileV1TransactionBytes, systemTransferInstruction, } from "./transaction-v1.js";
+export type { ProductionTransactionVersion, V1CompileOptions } from "./transaction-v1.js";

package/dist/index.js

@@ -0,0 +1,26 @@
+export * from "./accounts.js";
+export * from "./client.js";
+export * from "./constants.js";
+export * from "./crossmint-adapt.js";
+export * from "./crossmint-order.js";
+export * from "./delivery.js";
+export * from "./encoding.js";
+export * from "./known-assets.js";
+export * from "./mandate.js";
+export * from "./ops-snapshot.js";
+export * from "./payment.js";
+export * from "./payment-request.js";
+export * from "./mandate-request.js";
+export * from "./pda.js";
+export * from "./receipt.js";
+export * from "./receipt-export.js";
+export * from "./solana.js";
+export * from "./token.js";
+export * from "./token-capabilities.js";
+export * from "./types.js";
+export * from "./x402.js";
+export * from "./x402-challenge.js";
+export * from "./x402-adapt.js";
+export * from "./cards/index.js";
+export { decodeSupportedTransaction } from "./transaction-reader.js";
+export { DEFAULT_TRANSACTION_VERSION, V1_COMPUTE_UNIT_LIMIT, V1_LOADED_ACCOUNTS_DATA_SIZE_LIMIT, compileV1TransactionBytes, systemTransferInstruction, } from "./transaction-v1.js";

package/dist/known-assets.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The mints ChainPay can name, and the order it shows them in.
+ *
+ * Naming a mint here is presentation only. Whether an asset can be paid at all
+ * is decided on chain by the registry account the protocol authority creates,
+ * and a mint absent from this table still works — it is labelled by its address
+ * instead. The two must be kept apart: adding a row here does not enable a
+ * token, and enabling a token on chain does not require a row here.
+ *
+ * Devnet and mainnet mints for one asset share a label, so the dashboard reads
+ * the same on either cluster without the caller knowing which it is on.
+ */
+export type KnownAsset = {
+    label: string;
+    /** Lower sorts first, so the assets an owner expects lead the list. */
+    order: number;
+    /** Every mint that is this asset, across clusters. */
+    mints: readonly string[];
+};
+export declare const KNOWN_ASSETS: readonly KnownAsset[];
+export declare function knownAsset(mint: string): KnownAsset | undefined;
+/** The order an unnamed mint sorts at: after everything this table names. */
+export declare const UNKNOWN_ASSET_ORDER: number;
+export declare function assetOrder(mint: string): number;
+/**
+ * The symbol to print beside an amount in this mint. Unknown mints fall back
+ * to the neutral word rather than a guessed ticker, because a wrong symbol
+ * beside an amount misidentifies the money.
+ */
+export declare function assetLabel(mint: string, fallback?: string): string;

package/dist/known-assets.js

@@ -0,0 +1,49 @@
+export const KNOWN_ASSETS = [
+    {
+        label: "USDC",
+        order: 0,
+        mints: [
+            "4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU", // devnet
+            "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", // mainnet
+        ],
+    },
+    {
+        label: "PYUSD",
+        order: 1,
+        mints: [
+            "CXk2AMBfi3TwaEL2468s6zP8xq9NxTXjp9gjMgzeUynM", // devnet, Token-2022
+            "2b1kV6DkPAnxd5ixfnxCpjxmKwqjjaYmCZfHsFu24GXo", // mainnet, Token-2022
+        ],
+    },
+    {
+        label: "EURC",
+        order: 2,
+        mints: [
+            "HzwqbKZw8HxMN6bF2yFZNrht3c2iXXzpKcFu7uBEDKtr", // devnet
+        ],
+    },
+    {
+        label: "USDG",
+        order: 3,
+        mints: [
+            "4F6PM96JJxngmHnZLBh9n58RH4aTVNWvDs2nuwrT5BP7", // devnet, Token-2022
+        ],
+    },
+];
+const byMint = new Map(KNOWN_ASSETS.flatMap((asset) => asset.mints.map((mint) => [mint, asset])));
+export function knownAsset(mint) {
+    return byMint.get(mint);
+}
+/** The order an unnamed mint sorts at: after everything this table names. */
+export const UNKNOWN_ASSET_ORDER = KNOWN_ASSETS.length;
+export function assetOrder(mint) {
+    return byMint.get(mint)?.order ?? UNKNOWN_ASSET_ORDER;
+}
+/**
+ * The symbol to print beside an amount in this mint. Unknown mints fall back
+ * to the neutral word rather than a guessed ticker, because a wrong symbol
+ * beside an amount misidentifies the money.
+ */
+export function assetLabel(mint, fallback = "tokens") {
+    return byMint.get(mint)?.label ?? fallback;
+}