@chainpayhq/sdk 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ChainPay contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,43 @@
-# Temporary Holding Version
+# ChainPay SDK
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+TypeScript tools for reading mandates and receipts and building Solana payment
+transactions. Wallets and approved signer providers sign outside the SDK.
+
+**Start with [a read-only SDK example](https://github.com/stawuah/chainpay-mcp-sdk/blob/master/docs/guides/use-the-sdk.md).**
+
+Install the public package:
+
+```bash
+npm install @chainpayhq/sdk
+```
+
+The package targets ChainPay on Solana Devnet. It prepares transactions and
+reads protocol state; signing and submission require your wallet or approved
+provider.
+
+## Develop from this repository
+
+From the repository root:
+
+```bash
+npm ci --include=dev --ignore-scripts
+npm --prefix sdk run build
+npm --prefix sdk run test
+```
+
+- [Integration guide](https://github.com/stawuah/chainpay-mcp-sdk/blob/master/docs/guides/use-the-sdk.md): first read, signing boundary, token support, and transaction codecs.
+- [Public exports](https://github.com/stawuah/chainpay-mcp-sdk/blob/master/sdk/src/index.ts), [client methods](https://github.com/stawuah/chainpay-mcp-sdk/blob/master/sdk/src/client.ts), and [types](https://github.com/stawuah/chainpay-mcp-sdk/blob/master/sdk/src/types.ts): implementation reference.
+- [Payment-agent guide](https://github.com/stawuah/chainpay-mcp-sdk/blob/master/docs/guides/connect-an-agent.md): MCP integration and caller authorization.
+- [Documentation index](https://github.com/stawuah/chainpay-mcp-sdk/blob/master/docs/README.md).
+
+## Preparing wallet token accounts
+
+`prepareAssociatedTokenAccount({ owner, mint, payer })` checks that the mint is
+enabled in the on-chain asset registry, validates its token program, and checks
+the owner's canonical associated token account. It returns `status: "ready"`
+when the account exists or an unsigned, single-instruction transaction when it
+is missing. The caller must show that transaction to the wallet for approval.
+
+`prepareRegisteredAssetTokenAccounts(owner)` performs the same inspection for
+every enabled registry asset. Disabled assets are excluded. Neither method
+submits a transaction, funds an account, or grants a spending permission.

package/dist/accounts.d.ts

@@ -0,0 +1,23 @@
+import type { Address, Mandate, PaymentReceipt, ReceiptPolicySnapshot, SupportedAsset, TokenProgram } from "./types.js";
+export declare function decodeProtocolConfig(data: Uint8Array | Buffer, configAddress?: Address): {
+    address: string | undefined;
+    authority: string;
+    supportedMints: string[];
+    bump: number;
+};
+export declare function decodeSupportedAsset(data: Uint8Array | Buffer, assetAddress: Address): SupportedAsset;
+export declare function decodeMandate(data: Uint8Array | Buffer, mandateAddress: Address, currentSlot?: bigint, tokenProgram?: TokenProgram): Mandate;
+/**
+ * Read the policy tail of a v2 receipt. An original 282-byte receipt, or a v2
+ * receipt whose version byte is 0, has no snapshot: return null rather than
+ * reading zeroes as limits.
+ */
+export declare function decodeReceiptPolicySnapshot(data: Uint8Array | Buffer): ReceiptPolicySnapshot | null;
+export declare function decodePaymentReceipt(data: Uint8Array | Buffer, receiptAddress: Address, transactionSignature?: string): PaymentReceipt;
+/**
+ * Decode the current mandate account only. Independent of paginated
+ * creation history and source token metadata. Public receipt cards may
+ * attach these fields as optional enrichment; a decode failure must not
+ * invent limits or invalidate a settled payment.
+ */
+export declare function decodeCurrentMandateFields(data: Uint8Array | Buffer, mandateAddress: Address, currentSlot?: bigint): Mandate;

package/dist/accounts.js

@@ -0,0 +1,148 @@
+import { PublicKey } from "@solana/web3.js";
+import { ACCOUNT_DISCRIMINATORS, MANDATE_ACCOUNT_LENGTH, RECEIPT_ACCOUNT_LENGTH, RECEIPT_ACCOUNT_LENGTH_V2, RECEIPT_STATUS_SETTLED, } from "./constants.js";
+import { address, assertDiscriminator, isMandateNonce, readBytes32, readPublicKey, readU8, readU64, } from "./encoding.js";
+const ACCOUNT_DISCRIMINATOR_LENGTH = 8;
+const DEFAULT_ADDRESS = PublicKey.default.toBase58();
+function accountBytes(data) {
+    return data instanceof Uint8Array ? data : new Uint8Array(data);
+}
+function requireLength(data, length, accountName) {
+    if (data.length < length)
+        throw new Error(`${accountName} account data is truncated`);
+}
+function mandateStatus(paused, revoked, expiresAtSlot, currentSlot) {
+    if (revoked)
+        return "revoked";
+    if (paused)
+        return "paused";
+    if (currentSlot !== undefined && expiresAtSlot <= currentSlot)
+        return "expired";
+    return "active";
+}
+export function decodeProtocolConfig(data, configAddress) {
+    const bytes = accountBytes(data);
+    assertDiscriminator(bytes, ACCOUNT_DISCRIMINATORS.protocolConfig, "ProtocolConfig");
+    requireLength(bytes, 137, "ProtocolConfig");
+    const supportedMints = [
+        readPublicKey(bytes, 40),
+        readPublicKey(bytes, 72),
+        readPublicKey(bytes, 104),
+    ].filter((mint) => mint !== DEFAULT_ADDRESS);
+    return {
+        address: configAddress ? address(configAddress) : undefined,
+        authority: readPublicKey(bytes, ACCOUNT_DISCRIMINATOR_LENGTH),
+        supportedMints,
+        bump: readU8(bytes, 136),
+    };
+}
+export function decodeSupportedAsset(data, assetAddress) {
+    const bytes = accountBytes(data);
+    assertDiscriminator(bytes, ACCOUNT_DISCRIMINATORS.supportedAsset, "SupportedAsset");
+    requireLength(bytes, 106, "SupportedAsset");
+    return {
+        address: address(assetAddress),
+        authority: readPublicKey(bytes, 8),
+        mint: readPublicKey(bytes, 40),
+        tokenProgram: readPublicKey(bytes, 72),
+        enabled: readU8(bytes, 104) !== 0,
+        bump: readU8(bytes, 105),
+    };
+}
+export function decodeMandate(data, mandateAddress, currentSlot, tokenProgram) {
+    const bytes = accountBytes(data);
+    assertDiscriminator(bytes, ACCOUNT_DISCRIMINATORS.paymentMandate, "PaymentMandate");
+    requireLength(bytes, MANDATE_ACCOUNT_LENGTH, "PaymentMandate");
+    const expiresAtSlot = readU64(bytes, 200);
+    const maxPaymentCount = readU64(bytes, 208);
+    const cooldownSlots = readU64(bytes, 216);
+    const lastPaymentSlot = readU64(bytes, 224);
+    const paused = readU8(bytes, 232) !== 0;
+    const revoked = readU8(bytes, 233) !== 0;
+    const legacyAllowedRecipient = readPublicKey(bytes, 136);
+    const mandateNonce = isMandateNonce(legacyAllowedRecipient) ? legacyAllowedRecipient : undefined;
+    return {
+        address: address(mandateAddress),
+        owner: readPublicKey(bytes, 8),
+        approvedAgent: readPublicKey(bytes, 40),
+        sourceTokenAccount: readPublicKey(bytes, 72),
+        allowedMint: readPublicKey(bytes, 104),
+        legacyAllowedRecipient: mandateNonce || legacyAllowedRecipient === DEFAULT_ADDRESS ? undefined : legacyAllowedRecipient,
+        maxPerPayment: readU64(bytes, 168),
+        totalLimit: readU64(bytes, 176),
+        amountSpent: readU64(bytes, 184),
+        paymentCount: readU64(bytes, 192),
+        expiresAtSlot,
+        maxPaymentCount,
+        cooldownSlots,
+        lastPaymentSlot,
+        paused,
+        revoked,
+        status: mandateStatus(paused, revoked, expiresAtSlot, currentSlot),
+        tokenProgram,
+        mandateNonce,
+    };
+}
+function paymentStatus(onChainStatus) {
+    return onChainStatus === RECEIPT_STATUS_SETTLED ? "confirmed" : "failed";
+}
+/** Offset of `snapshot_version`, the first byte after the original receipt. */
+const RECEIPT_SNAPSHOT_VERSION_OFFSET = RECEIPT_ACCOUNT_LENGTH;
+/**
+ * Read the policy tail of a v2 receipt. An original 282-byte receipt, or a v2
+ * receipt whose version byte is 0, has no snapshot: return null rather than
+ * reading zeroes as limits.
+ */
+export function decodeReceiptPolicySnapshot(data) {
+    const bytes = accountBytes(data);
+    if (bytes.length < RECEIPT_ACCOUNT_LENGTH_V2)
+        return null;
+    const version = readU8(bytes, RECEIPT_SNAPSHOT_VERSION_OFFSET);
+    if (version === 0)
+        return null;
+    return {
+        version,
+        maxPerPayment: readU64(bytes, 283),
+        totalLimit: readU64(bytes, 291),
+        amountSpentAfter: readU64(bytes, 299),
+        paymentCountAfter: readU64(bytes, 307),
+        maxPaymentCount: readU64(bytes, 315),
+        expiresAtSlot: readU64(bytes, 323),
+        cooldownSlots: readU64(bytes, 331),
+    };
+}
+export function decodePaymentReceipt(data, receiptAddress, transactionSignature) {
+    const bytes = accountBytes(data);
+    assertDiscriminator(bytes, ACCOUNT_DISCRIMINATORS.paymentReceipt, "PaymentReceipt");
+    requireLength(bytes, RECEIPT_ACCOUNT_LENGTH, "PaymentReceipt");
+    const onChainStatus = readU8(bytes, 280);
+    return {
+        address: address(receiptAddress),
+        mandate: readPublicKey(bytes, 8),
+        invoiceHash: readBytes32(bytes, 40, "invoiceHash"),
+        paymentId: readBytes32(bytes, 72, "paymentId"),
+        mint: readPublicKey(bytes, 104),
+        sourceTokenAccount: readPublicKey(bytes, 136),
+        recipientTokenAccount: readPublicKey(bytes, 168),
+        recipient: readPublicKey(bytes, 168),
+        amount: readU64(bytes, 200),
+        agent: readPublicKey(bytes, 208),
+        executedAtSlot: readU64(bytes, 240),
+        // Replay lock supplied at settle. Not seller delivery and not the
+        // Solana transaction signature.
+        signatureReference: readBytes32(bytes, 248, "signatureReference"),
+        status: paymentStatus(onChainStatus),
+        onChainStatus,
+        bump: readU8(bytes, 281),
+        transactionSignature,
+        policySnapshot: decodeReceiptPolicySnapshot(bytes),
+    };
+}
+/**
+ * Decode the current mandate account only. Independent of paginated
+ * creation history and source token metadata. Public receipt cards may
+ * attach these fields as optional enrichment; a decode failure must not
+ * invent limits or invalidate a settled payment.
+ */
+export function decodeCurrentMandateFields(data, mandateAddress, currentSlot) {
+    return decodeMandate(data, mandateAddress, currentSlot);
+}

package/dist/cards/accounts.d.ts

@@ -0,0 +1,156 @@
+import type { Address } from "../types.js";
+export type CardBindingStatus = "active" | "closing" | "closed";
+export type CardFreezeReason = "none" | "owner" | "authorizer_safety" | "recovery" | "expiry";
+export type CardRecoveryState = "normal" | "recovery_frozen" | "restored_pending_reconcile";
+export type OnChainReservationState = number;
+/** On-chain ReservationState bytes as card_policy defines them (0 is never written). */
+export declare const RESERVATION_STATES: {
+    readonly 1: "reserved";
+    readonly 2: "partially_captured";
+    readonly 3: "captured";
+    readonly 4: "reversed";
+    readonly 5: "expired";
+};
+export type ReservationStateName = (typeof RESERVATION_STATES)[keyof typeof RESERVATION_STATES];
+export declare function reservationStateName(state: number): ReservationStateName | undefined;
+export type IntentState = "open" | "consumed" | "expired" | "cancelled";
+export type DisputeState = "none" | "open" | "won" | "lost" | "withdrawn";
+export declare function currencyBytes(currency: string): Uint8Array;
+export type CardBinding = {
+    version: number;
+    owner: Address;
+    cardId: Uint8Array;
+    issuer: number;
+    issuerCardRefHash: Uint8Array;
+    policy: Address;
+    period: Address;
+    commitment: Address;
+    status: CardBindingStatus;
+    createdAt: bigint;
+    bump: number;
+};
+export declare const CARD_BINDING_LENGTH: number;
+export declare function decodeCardBinding(data: Uint8Array | Buffer): CardBinding;
+export declare function encodeCardBinding(value: CardBinding): Uint8Array;
+export type CardPolicyMember = {
+    pubkey: Address;
+    flags: number;
+};
+export type CardPolicy = {
+    binding: Address;
+    owner: Address;
+    /** Zero address until the first `set_policy`; every authorization fails until then. */
+    authorizer: Address;
+    policyVersion: number;
+    budgetCents: bigint;
+    maxPurchaseCents: bigint;
+    /** 0 = no count limit. */
+    maxPurchasesPerPeriod: number;
+    periodSeconds: number;
+    currency: string;
+    merchantIdHashes: Uint8Array[];
+    mccs: number[];
+    /** 0 = no expiry. Unix seconds on the PER clock. */
+    expiresAt: bigint;
+    recurringAllowed: boolean;
+    feeBps: number;
+    frozen: boolean;
+    freezeReason: CardFreezeReason;
+    recoveryState: CardRecoveryState;
+    statementOutstandingCents: bigint;
+    exceptionsOpen: number;
+    members: CardPolicyMember[];
+    ledgerHead: Uint8Array;
+    ledgerSeq: bigint;
+    commitSeq: bigint;
+    bump: number;
+    /**
+     * Program-appended tail (not in contracts.md §1.2): last reconciliation
+     * digest and the ring of used repayment digests. Present only when the
+     * account is long enough; encoders never write it.
+     */
+    tail?: {
+        reconDigest: Uint8Array;
+        repaymentDigests: Uint8Array[];
+    };
+};
+export declare const CARD_POLICY_LENGTH: number;
+export declare function decodeCardPolicy(data: Uint8Array | Buffer): CardPolicy;
+export declare function encodeCardPolicy(value: CardPolicy): Uint8Array;
+export type CardPeriod = {
+    policy: Address;
+    /** 0 before the first set_policy; 1.. thereafter. */
+    periodIndex: number;
+    periodStart: bigint;
+    periodEnd: bigint;
+    capturedCents: bigint;
+    reservedCents: bigint;
+    refundedCents: bigint;
+    purchasesCount: number;
+    exceptionCents: bigint;
+    bump: number;
+};
+export declare const CARD_PERIOD_LENGTH: number;
+export declare function decodeCardPeriod(data: Uint8Array | Buffer): CardPeriod;
+export declare function encodeCardPeriod(value: CardPeriod): Uint8Array;
+/** Reservation.flags bits (contracts.md §1.2). */
+export declare const RESERVATION_FLAGS: {
+    readonly lateCapture: number;
+    readonly overCapture: number;
+    readonly singleMessage: number;
+    readonly recurring: number;
+};
+export type Reservation = {
+    policy: Address;
+    authIdHash: Uint8Array;
+    intent: Address;
+    periodIndex: number;
+    amountReservedCents: bigint;
+    capturedCents: bigint;
+    reversedCents: bigint;
+    refundedCents: bigint;
+    /** On-chain ReservationState byte (§4.1). Off-chain states (pending, ambiguous) never appear here. */
+    state: OnChainReservationState;
+    disputeState: DisputeState;
+    flags: number;
+    createdAt: bigint;
+    holdExpiresAt: bigint;
+    bump: number;
+    /** Program-appended capture-id ring (replay guard for `capture`). Present only when the account is long enough. */
+    captureIdHashes?: Uint8Array[];
+    /** Program-appended: the checkout intent's max; `adjust_reservation` never grows the hold past it. */
+    maxAmountCents?: bigint;
+};
+export declare const RESERVATION_LENGTH: number;
+export declare function decodeReservation(data: Uint8Array | Buffer): Reservation;
+export declare function encodeReservation(value: Reservation): Uint8Array;
+export type CheckoutIntent = {
+    policy: Address;
+    intentId: Uint8Array;
+    agent: Address;
+    merchantIdHash: Uint8Array;
+    /** 0 = any allowed MCC. */
+    mcc: number;
+    maxAmountCents: bigint;
+    currency: string;
+    policyVersion: number;
+    expiresAt: bigint;
+    state: IntentState;
+    reservation: Address;
+    bump: number;
+};
+export declare const CHECKOUT_INTENT_LENGTH: number;
+export declare function decodeCheckoutIntent(data: Uint8Array | Buffer): CheckoutIntent;
+export declare function encodeCheckoutIntent(value: CheckoutIntent): Uint8Array;
+export type CardCommitment = {
+    binding: Address;
+    seq: bigint;
+    root: Uint8Array;
+    policyVersion: number;
+    periodIndex: number;
+    writtenSlot: bigint;
+    bump: number;
+};
+export declare const CARD_COMMITMENT_LENGTH: number;
+export declare function decodeCardCommitment(data: Uint8Array | Buffer): CardCommitment;
+export declare function encodeCardCommitment(value: CardCommitment): Uint8Array;