@dexterai/vault 0.4.2 → 0.5.0

package/dist/tab/index.d.cts

@@ -0,0 +1,145 @@
+import { PublicKey, TransactionInstruction, Connection } from '@solana/web3.js';
+import { Ed25519Signer } from '../signers/types.cjs';
+import { VaultStateFull } from '../types.cjs';
+
+/**
+ * openTab — composes the settle_voucher(increment) leg that raises the tab's
+ * outstanding and arms it. Returns instructions; does NOT send.
+ *
+ * Note: buildSettleVoucherInstruction needs only { vaultPda, dexterAuthority,
+ * amount, increment } — there is no swigAddress param, so we don't accept one
+ * (no lying/unused params).
+ */
+
+interface OpenTabParams {
+    vaultPda: PublicKey;
+    amount: bigint;
+    dexterAuthority: PublicKey;
+}
+declare function openTab(p: OpenTabParams): Promise<TransactionInstruction[]>;
+
+/** A single SignV2 transfer leg (destination + amount). */
+interface TabTransfer {
+    destinationAta: PublicKey;
+    amount: bigint;
+}
+
+/**
+ * The injectable Swig SignV2 assembler for ./tab verbs. Default wires the real
+ * @swig-wallet/kit; tests inject a fake. Mirrors factoring/instantPayout.ts.
+ * The vault instruction (settle_tab_voucher / draw_credit / etc.) is passed as
+ * `vaultIx` and becomes the SignV2 preInstruction.
+ */
+
+interface AssembleSignV2Args {
+    connection: Connection;
+    swigAddress: PublicKey;
+    feePayer: PublicKey;
+    /** The single preceding instruction Swig ProgramExec authenticates against. */
+    vaultIx: TransactionInstruction;
+    transfers: TabTransfer[];
+}
+type AssembleSignV2 = (args: AssembleSignV2Args) => Promise<TransactionInstruction[]>;
+/** Real SignV2 assembler — mirrors factoring/instantPayout.ts defaultAssembleSignV2. */
+declare const defaultAssembleSignV2: AssembleSignV2;
+
+/**
+ * settleTab — the central ./tab verb. Composes the atomic 3-instruction tab
+ * settle: [Ed25519 precompile over the voucher] + [settle_tab_voucher] +
+ * [Swig SignV2 transfer of the delta]. The delta (cumulative - priorSpent) is
+ * computed from a FRESH on-chain read done INSIDE this verb. On-chain
+ * settle_tab_voucher re-validates monotonicity, so a stale read fails safe.
+ * Returns instructions; does NOT send. Promoted from dexter-facilitator tabSettle.ts.
+ */
+
+interface SettleTabParams {
+    connection: Connection;
+    vaultPda: PublicKey;
+    swigAddress: PublicKey;
+    channelId: Uint8Array;
+    cumulativeAmount: bigint;
+    sequenceNumber: number;
+    sessionSigner: Ed25519Signer;
+    sellerAta: PublicKey;
+    feePayer: PublicKey;
+    /** Must equal the vault's recorded dexter_authority; the settle_tab_voucher signer. */
+    dexterAuthority: PublicKey;
+    assembleSignV2?: AssembleSignV2;
+    readPriorSpent?: (connection: Connection, vaultPda: PublicKey) => Promise<bigint>;
+}
+declare function settleTab(p: SettleTabParams): Promise<TransactionInstruction[]>;
+
+/**
+ * readTabMeter — READ-ONLY tab reporter. Reports remaining headroom under the
+ * session cap; NEVER refuses. The on-chain cap guard is authoritative; a
+ * client-side refuser would invite a stale-cache TOCTOU bug.
+ */
+
+interface TabMeter {
+    spent: bigint;
+    maxAmount: bigint;
+    remaining: bigint;
+}
+declare function readTabMeter(connection: Connection, vaultPda: PublicKey, read?: (c: Connection, v: PublicKey) => Promise<VaultStateFull>): Promise<TabMeter>;
+
+/**
+ * Credit verbs — the tab that can spend PAST the balance. Each wraps a proven,
+ * mainnet-tested credit instruction with the SignV2 transfer, same shape as
+ * settleTab. WHOSE-SWIG: draw = FINANCIER funds → seller; repay + seize = USER
+ * funds → financier. Returns instructions; does NOT send.
+ */
+
+interface DrawCreditParams {
+    connection: Connection;
+    userVaultPda: PublicKey;
+    financierSwig: PublicKey;
+    amount: bigint;
+    recoveryWindowSeconds: bigint;
+    dexterAuthority: PublicKey;
+    sellerAta: PublicKey;
+    feePayer: PublicKey;
+    assembleSignV2?: AssembleSignV2;
+}
+/**
+ * The borrow. draw_credit moves funds FINANCIER → seller, so the SignV2 transfer
+ * spends the FINANCIER swig. buildDrawCreditInstruction derives the financier's
+ * swig_wallet_address PDA off-chain and passes it as an account; the on-chain
+ * program validates it.
+ */
+declare function drawCredit(p: DrawCreditParams): Promise<TransactionInstruction[]>;
+interface RepayCreditParams {
+    connection: Connection;
+    userVaultPda: PublicKey;
+    userSwig: PublicKey;
+    amount: bigint;
+    dexterAuthority: PublicKey;
+    financierAta: PublicKey;
+    feePayer: PublicKey;
+    assembleSignV2?: AssembleSignV2;
+}
+/**
+ * The paydown. repay_credit moves funds USER → financier, so the SignV2 transfer
+ * spends the USER swig. buildRepayCreditInstruction takes the user swig as
+ * `swigAddress`, derives its swig_wallet_address PDA off-chain and passes it as
+ * an account; the on-chain program validates it.
+ */
+declare function repayCredit(p: RepayCreditParams): Promise<TransactionInstruction[]>;
+interface SeizeCollateralParams {
+    connection: Connection;
+    userVaultPda: PublicKey;
+    userSwig: PublicKey;
+    dexterAuthority: PublicKey;
+    financierAta: PublicKey;
+    feePayer: PublicKey;
+    seizeAmount: bigint;
+    assembleSignV2?: AssembleSignV2;
+}
+/**
+ * The deadline liquidation. seize_collateral moves the borrowed slice USER →
+ * financier, so the SignV2 transfer spends the USER swig. The on-chain
+ * SeizeCollateralArgs is empty (the contract zeroes vault.borrowed); seizeAmount
+ * is used ONLY for the SignV2 transfer leg — the snapshot of what's owed.
+ */
+declare function seizeCollateral(p: SeizeCollateralParams): Promise<TransactionInstruction[]>;
+
+export { type AssembleSignV2, type AssembleSignV2Args, type DrawCreditParams, type OpenTabParams, type RepayCreditParams, type SeizeCollateralParams, type SettleTabParams, type TabMeter, type TabTransfer, defaultAssembleSignV2, drawCredit, openTab, readTabMeter, repayCredit, seizeCollateral, settleTab };

package/dist/tab/index.d.ts

@@ -0,0 +1,145 @@
+import { PublicKey, TransactionInstruction, Connection } from '@solana/web3.js';
+import { Ed25519Signer } from '../signers/types.js';
+import { VaultStateFull } from '../types.js';
+
+/**
+ * openTab — composes the settle_voucher(increment) leg that raises the tab's
+ * outstanding and arms it. Returns instructions; does NOT send.
+ *
+ * Note: buildSettleVoucherInstruction needs only { vaultPda, dexterAuthority,
+ * amount, increment } — there is no swigAddress param, so we don't accept one
+ * (no lying/unused params).
+ */
+
+interface OpenTabParams {
+    vaultPda: PublicKey;
+    amount: bigint;
+    dexterAuthority: PublicKey;
+}
+declare function openTab(p: OpenTabParams): Promise<TransactionInstruction[]>;
+
+/** A single SignV2 transfer leg (destination + amount). */
+interface TabTransfer {
+    destinationAta: PublicKey;
+    amount: bigint;
+}
+
+/**
+ * The injectable Swig SignV2 assembler for ./tab verbs. Default wires the real
+ * @swig-wallet/kit; tests inject a fake. Mirrors factoring/instantPayout.ts.
+ * The vault instruction (settle_tab_voucher / draw_credit / etc.) is passed as
+ * `vaultIx` and becomes the SignV2 preInstruction.
+ */
+
+interface AssembleSignV2Args {
+    connection: Connection;
+    swigAddress: PublicKey;
+    feePayer: PublicKey;
+    /** The single preceding instruction Swig ProgramExec authenticates against. */
+    vaultIx: TransactionInstruction;
+    transfers: TabTransfer[];
+}
+type AssembleSignV2 = (args: AssembleSignV2Args) => Promise<TransactionInstruction[]>;
+/** Real SignV2 assembler — mirrors factoring/instantPayout.ts defaultAssembleSignV2. */
+declare const defaultAssembleSignV2: AssembleSignV2;
+
+/**
+ * settleTab — the central ./tab verb. Composes the atomic 3-instruction tab
+ * settle: [Ed25519 precompile over the voucher] + [settle_tab_voucher] +
+ * [Swig SignV2 transfer of the delta]. The delta (cumulative - priorSpent) is
+ * computed from a FRESH on-chain read done INSIDE this verb. On-chain
+ * settle_tab_voucher re-validates monotonicity, so a stale read fails safe.
+ * Returns instructions; does NOT send. Promoted from dexter-facilitator tabSettle.ts.
+ */
+
+interface SettleTabParams {
+    connection: Connection;
+    vaultPda: PublicKey;
+    swigAddress: PublicKey;
+    channelId: Uint8Array;
+    cumulativeAmount: bigint;
+    sequenceNumber: number;
+    sessionSigner: Ed25519Signer;
+    sellerAta: PublicKey;
+    feePayer: PublicKey;
+    /** Must equal the vault's recorded dexter_authority; the settle_tab_voucher signer. */
+    dexterAuthority: PublicKey;
+    assembleSignV2?: AssembleSignV2;
+    readPriorSpent?: (connection: Connection, vaultPda: PublicKey) => Promise<bigint>;
+}
+declare function settleTab(p: SettleTabParams): Promise<TransactionInstruction[]>;
+
+/**
+ * readTabMeter — READ-ONLY tab reporter. Reports remaining headroom under the
+ * session cap; NEVER refuses. The on-chain cap guard is authoritative; a
+ * client-side refuser would invite a stale-cache TOCTOU bug.
+ */
+
+interface TabMeter {
+    spent: bigint;
+    maxAmount: bigint;
+    remaining: bigint;
+}
+declare function readTabMeter(connection: Connection, vaultPda: PublicKey, read?: (c: Connection, v: PublicKey) => Promise<VaultStateFull>): Promise<TabMeter>;
+
+/**
+ * Credit verbs — the tab that can spend PAST the balance. Each wraps a proven,
+ * mainnet-tested credit instruction with the SignV2 transfer, same shape as
+ * settleTab. WHOSE-SWIG: draw = FINANCIER funds → seller; repay + seize = USER
+ * funds → financier. Returns instructions; does NOT send.
+ */
+
+interface DrawCreditParams {
+    connection: Connection;
+    userVaultPda: PublicKey;
+    financierSwig: PublicKey;
+    amount: bigint;
+    recoveryWindowSeconds: bigint;
+    dexterAuthority: PublicKey;
+    sellerAta: PublicKey;
+    feePayer: PublicKey;
+    assembleSignV2?: AssembleSignV2;
+}
+/**
+ * The borrow. draw_credit moves funds FINANCIER → seller, so the SignV2 transfer
+ * spends the FINANCIER swig. buildDrawCreditInstruction derives the financier's
+ * swig_wallet_address PDA off-chain and passes it as an account; the on-chain
+ * program validates it.
+ */
+declare function drawCredit(p: DrawCreditParams): Promise<TransactionInstruction[]>;
+interface RepayCreditParams {
+    connection: Connection;
+    userVaultPda: PublicKey;
+    userSwig: PublicKey;
+    amount: bigint;
+    dexterAuthority: PublicKey;
+    financierAta: PublicKey;
+    feePayer: PublicKey;
+    assembleSignV2?: AssembleSignV2;
+}
+/**
+ * The paydown. repay_credit moves funds USER → financier, so the SignV2 transfer
+ * spends the USER swig. buildRepayCreditInstruction takes the user swig as
+ * `swigAddress`, derives its swig_wallet_address PDA off-chain and passes it as
+ * an account; the on-chain program validates it.
+ */
+declare function repayCredit(p: RepayCreditParams): Promise<TransactionInstruction[]>;
+interface SeizeCollateralParams {
+    connection: Connection;
+    userVaultPda: PublicKey;
+    userSwig: PublicKey;
+    dexterAuthority: PublicKey;
+    financierAta: PublicKey;
+    feePayer: PublicKey;
+    seizeAmount: bigint;
+    assembleSignV2?: AssembleSignV2;
+}
+/**
+ * The deadline liquidation. seize_collateral moves the borrowed slice USER →
+ * financier, so the SignV2 transfer spends the USER swig. The on-chain
+ * SeizeCollateralArgs is empty (the contract zeroes vault.borrowed); seizeAmount
+ * is used ONLY for the SignV2 transfer leg — the snapshot of what's owed.
+ */
+declare function seizeCollateral(p: SeizeCollateralParams): Promise<TransactionInstruction[]>;
+
+export { type AssembleSignV2, type AssembleSignV2Args, type DrawCreditParams, type OpenTabParams, type RepayCreditParams, type SeizeCollateralParams, type SettleTabParams, type TabMeter, type TabTransfer, defaultAssembleSignV2, drawCredit, openTab, readTabMeter, repayCredit, seizeCollateral, settleTab };