@dexterai/vault 0.4.1 → 0.5.0

package/dist/factoring/index.d.cts

@@ -0,0 +1,79 @@
+import { Connection, PublicKey, TransactionInstruction } from '@solana/web3.js';
+export { getRpc, kitInstructionsToWeb3 } from '../kit/index.cjs';
+
+/**
+ * Factoring split math — pure, no chain dependencies.
+ *
+ * A LockedClaim of `claimAmount` is settled by its holder (the financier).
+ * Factoring routes most of that to the SELLER (instant cash now) and keeps a
+ * `financierSpread` for the financier — payment-certainty pricing, NOT interest
+ * (short claims earn ~nothing on APR; the spread is a clearing/liquidity fee).
+ *
+ * INVARIANT: sellerReceives + financierSpread === claimAmount, exactly. The two
+ * inner SignV2 transfers source from the swig-wallet ATA and together cannot
+ * exceed what the claim reserved, so they must sum to the claim amount.
+ *
+ * The SDK does NOT decide the spread — the caller (operator policy, e.g.
+ * dexter-api) supplies it. This keeps the SDK a neutral mechanism.
+ */
+interface FactoringSplitParams {
+    /** The full LockedClaim amount, atomic units (USDC = 6 decimals). */
+    claimAmount: bigint;
+    /** The financier's spread, atomic units. 0 ≤ spread ≤ claimAmount. */
+    financierSpread: bigint;
+}
+interface FactoringSplit {
+    /** What the seller receives now (claimAmount - financierSpread). */
+    sellerReceives: bigint;
+    /** The financier's spread, echoed back for the transfer builder. */
+    financierSpread: bigint;
+}
+declare function computeFactoringSplit(p: FactoringSplitParams): FactoringSplit;
+
+/**
+ * Instant-payout (factoring) — full atomic transaction assembly.
+ *
+ *   [0] vault::settle_locked_voucher  (financier = holder; validates + mutates)
+ *   [1] swig::SignV2(TransferChecked × {1 or 2})  (sourced from swig_wallet_ata)
+ *         - sellerReceives  → sellerAta
+ *         - financierSpread → financierAta  (omitted when spread === 0)
+ *
+ * The default `assembleSignV2` wires the real @swig-wallet/kit + @solana-program/token
+ * path (mirrors dexter-api buildFinalizeWithdrawExtra). It's injectable so the
+ * composition is unit-testable without live swig state.
+ */
+
+interface InstantTransfer {
+    destinationAta: PublicKey;
+    amount: bigint;
+}
+interface AssembleSignV2Args {
+    connection: Connection;
+    swigAddress: PublicKey;
+    feePayer: PublicKey;
+    /** The single preceding instruction Swig ProgramExec authenticates against. */
+    settleIx: TransactionInstruction;
+    transfers: InstantTransfer[];
+}
+type AssembleSignV2 = (args: AssembleSignV2Args) => Promise<TransactionInstruction[]>;
+interface InstantPayoutParams {
+    connection: Connection;
+    swigAddress: PublicKey;
+    claimPda: PublicKey;
+    vaultPda: PublicKey;
+    /** The current claim holder collecting — the financier. Signs settle. */
+    financier: PublicKey;
+    dexterAuthority: PublicKey;
+    claimAmount: bigint;
+    /** Operator-supplied spread. 0 ≤ spread ≤ claimAmount. */
+    financierSpread: bigint;
+    sellerAta: PublicKey;
+    financierAta: PublicKey;
+    /** Pays ATA rent / tx fees in the SignV2 build. */
+    feePayer: PublicKey;
+    /** Injectable for unit tests; defaults to the real swig-kit assembler. */
+    assembleSignV2?: AssembleSignV2;
+}
+declare function buildInstantPayoutInstructions(p: InstantPayoutParams): Promise<TransactionInstruction[]>;
+
+export { type AssembleSignV2, type AssembleSignV2Args, type FactoringSplit, type FactoringSplitParams, type InstantPayoutParams, type InstantTransfer, buildInstantPayoutInstructions, computeFactoringSplit };

package/dist/factoring/index.d.ts

@@ -0,0 +1,79 @@
+import { Connection, PublicKey, TransactionInstruction } from '@solana/web3.js';
+export { getRpc, kitInstructionsToWeb3 } from '../kit/index.js';
+
+/**
+ * Factoring split math — pure, no chain dependencies.
+ *
+ * A LockedClaim of `claimAmount` is settled by its holder (the financier).
+ * Factoring routes most of that to the SELLER (instant cash now) and keeps a
+ * `financierSpread` for the financier — payment-certainty pricing, NOT interest
+ * (short claims earn ~nothing on APR; the spread is a clearing/liquidity fee).
+ *
+ * INVARIANT: sellerReceives + financierSpread === claimAmount, exactly. The two
+ * inner SignV2 transfers source from the swig-wallet ATA and together cannot
+ * exceed what the claim reserved, so they must sum to the claim amount.
+ *
+ * The SDK does NOT decide the spread — the caller (operator policy, e.g.
+ * dexter-api) supplies it. This keeps the SDK a neutral mechanism.
+ */
+interface FactoringSplitParams {
+    /** The full LockedClaim amount, atomic units (USDC = 6 decimals). */
+    claimAmount: bigint;
+    /** The financier's spread, atomic units. 0 ≤ spread ≤ claimAmount. */
+    financierSpread: bigint;
+}
+interface FactoringSplit {
+    /** What the seller receives now (claimAmount - financierSpread). */
+    sellerReceives: bigint;
+    /** The financier's spread, echoed back for the transfer builder. */
+    financierSpread: bigint;
+}
+declare function computeFactoringSplit(p: FactoringSplitParams): FactoringSplit;
+
+/**
+ * Instant-payout (factoring) — full atomic transaction assembly.
+ *
+ *   [0] vault::settle_locked_voucher  (financier = holder; validates + mutates)
+ *   [1] swig::SignV2(TransferChecked × {1 or 2})  (sourced from swig_wallet_ata)
+ *         - sellerReceives  → sellerAta
+ *         - financierSpread → financierAta  (omitted when spread === 0)
+ *
+ * The default `assembleSignV2` wires the real @swig-wallet/kit + @solana-program/token
+ * path (mirrors dexter-api buildFinalizeWithdrawExtra). It's injectable so the
+ * composition is unit-testable without live swig state.
+ */
+
+interface InstantTransfer {
+    destinationAta: PublicKey;
+    amount: bigint;
+}
+interface AssembleSignV2Args {
+    connection: Connection;
+    swigAddress: PublicKey;
+    feePayer: PublicKey;
+    /** The single preceding instruction Swig ProgramExec authenticates against. */
+    settleIx: TransactionInstruction;
+    transfers: InstantTransfer[];
+}
+type AssembleSignV2 = (args: AssembleSignV2Args) => Promise<TransactionInstruction[]>;
+interface InstantPayoutParams {
+    connection: Connection;
+    swigAddress: PublicKey;
+    claimPda: PublicKey;
+    vaultPda: PublicKey;
+    /** The current claim holder collecting — the financier. Signs settle. */
+    financier: PublicKey;
+    dexterAuthority: PublicKey;
+    claimAmount: bigint;
+    /** Operator-supplied spread. 0 ≤ spread ≤ claimAmount. */
+    financierSpread: bigint;
+    sellerAta: PublicKey;
+    financierAta: PublicKey;
+    /** Pays ATA rent / tx fees in the SignV2 build. */
+    feePayer: PublicKey;
+    /** Injectable for unit tests; defaults to the real swig-kit assembler. */
+    assembleSignV2?: AssembleSignV2;
+}
+declare function buildInstantPayoutInstructions(p: InstantPayoutParams): Promise<TransactionInstruction[]>;
+
+export { type AssembleSignV2, type AssembleSignV2Args, type FactoringSplit, type FactoringSplitParams, type InstantPayoutParams, type InstantTransfer, buildInstantPayoutInstructions, computeFactoringSplit };

package/dist/factoring/index.js

@@ -0,0 +1,220 @@
+// src/factoring/split.ts
+function computeFactoringSplit(p) {
+  if (p.claimAmount <= 0n) {
+    throw new Error(`factoring: claim amount must be positive, got ${p.claimAmount}`);
+  }
+  if (p.financierSpread < 0n) {
+    throw new Error(`factoring: spread must not be negative, got ${p.financierSpread}`);
+  }
+  if (p.financierSpread > p.claimAmount) {
+    throw new Error(`factoring: spread exceeds claim (${p.financierSpread} > ${p.claimAmount})`);
+  }
+  return {
+    sellerReceives: p.claimAmount - p.financierSpread,
+    financierSpread: p.financierSpread
+  };
+}
+
+// src/factoring/instantPayout.ts
+import { PublicKey as PublicKey5 } from "@solana/web3.js";
+import { fetchSwig, getSignInstructions, getSwigWalletAddress } from "@swig-wallet/kit";
+import { address as kitAddress } from "@solana/kit";
+import { getTransferCheckedInstruction } from "@solana-program/token";
+import { getAssociatedTokenAddressSync } from "@solana/spl-token";
+
+// src/instructions/lockedClaim.ts
+import { PublicKey as PublicKey3, SystemProgram, TransactionInstruction as TransactionInstruction2 } from "@solana/web3.js";
+
+// src/constants/index.ts
+import { PublicKey } from "@solana/web3.js";
+var DEXTER_VAULT_PROGRAM_ID = new PublicKey(
+  "Hg3wRaydFtJhYrdvYrKECacpJYDsC9Px7yKmpncj2fhc"
+);
+var SWIG_PROGRAM_ID = new PublicKey(
+  "swigypWHEksbC64pWKwah1WTeh9JXwx8H1rJHLdbQMB"
+);
+var SECP256R1_PROGRAM_ID = new PublicKey(
+  "Secp256r1SigVerify1111111111111111111111111"
+);
+var ED25519_PROGRAM_ID = new PublicKey(
+  "Ed25519SigVerify111111111111111111111111111"
+);
+var INSTRUCTIONS_SYSVAR_ID = new PublicKey(
+  "Sysvar1nstructions1111111111111111111111111"
+);
+var USDC_MAINNET = "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v";
+var VAULT_SEED_PREFIX = Buffer.from("vault");
+var LOCKED_CLAIM_SEED = Buffer.from("locked-claim");
+var DISCRIMINATORS = Object.freeze({
+  initialize_vault: Uint8Array.from([48, 191, 163, 44, 71, 129, 63, 164]),
+  set_swig: Uint8Array.from([253, 229, 89, 206, 192, 118, 137, 165]),
+  settle_voucher: Uint8Array.from([144, 176, 128, 220, 156, 79, 41, 54]),
+  request_withdrawal: Uint8Array.from([251, 85, 121, 205, 56, 201, 12, 177]),
+  finalize_withdrawal: Uint8Array.from([178, 87, 206, 68, 201, 186, 164, 232]),
+  force_release: Uint8Array.from([122, 190, 243, 252, 54, 202, 208, 234]),
+  rotate_passkey: Uint8Array.from([28, 134, 49, 89, 196, 34, 58, 174]),
+  rotate_dexter_authority: Uint8Array.from([145, 60, 4, 119, 180, 205, 236, 134]),
+  prove_passkey: Uint8Array.from([35, 175, 41, 143, 201, 118, 49, 184]),
+  settle_tab_voucher: Uint8Array.from([173, 22, 98, 31, 110, 129, 59, 161]),
+  register_session_key: Uint8Array.from([69, 94, 60, 44, 49, 199, 183, 233]),
+  revoke_session_key: Uint8Array.from([81, 192, 32, 110, 104, 116, 144, 151]),
+  lock_voucher: Uint8Array.from([91, 138, 5, 227, 119, 239, 48, 254]),
+  settle_locked_voucher: Uint8Array.from([44, 80, 216, 43, 247, 253, 101, 45]),
+  transfer_lock_ownership: Uint8Array.from([193, 13, 131, 134, 95, 25, 229, 157]),
+  recover_abandoned_lock: Uint8Array.from([169, 213, 107, 64, 229, 49, 43, 234]),
+  open_standby: Uint8Array.from([234, 184, 232, 135, 246, 191, 90, 250]),
+  draw_credit: Uint8Array.from([20, 84, 47, 211, 78, 117, 195, 210]),
+  repay_credit: Uint8Array.from([38, 113, 240, 182, 109, 179, 154, 245]),
+  seize_collateral: Uint8Array.from([40, 250, 7, 243, 168, 184, 116, 154]),
+  migrate_v4_to_v5: Uint8Array.from([226, 105, 140, 184, 101, 39, 235, 116])
+});
+var OTS_SESSION_REGISTER_V1_DOMAIN = (() => {
+  const buf = new Uint8Array(32);
+  buf.set(new TextEncoder().encode("OTS_SESSION_REGISTER_V1"), 0);
+  return buf;
+})();
+var OTS_SESSION_REGISTER_V2_DOMAIN = (() => {
+  const buf = new Uint8Array(32);
+  buf.set(new TextEncoder().encode("OTS_SESSION_REGISTER_V2"), 0);
+  return buf;
+})();
+var OTS_SESSION_REVOKE_V1_DOMAIN = (() => {
+  const buf = new Uint8Array(32);
+  buf.set(new TextEncoder().encode("OTS_SESSION_REVOKE_V1"), 0);
+  return buf;
+})();
+
+// src/instructions/withdraw.ts
+import {
+  PublicKey as PublicKey2,
+  TransactionInstruction,
+  SYSVAR_INSTRUCTIONS_PUBKEY
+} from "@solana/web3.js";
+function deriveSwigWalletAddress(swigAddress) {
+  const [pda] = PublicKey2.findProgramAddressSync(
+    [Buffer.from("swig-wallet-address"), swigAddress.toBuffer()],
+    SWIG_PROGRAM_ID
+  );
+  return pda;
+}
+
+// src/instructions/lockedClaim.ts
+function buildSettleLockedVoucherInstruction(p) {
+  const data = Buffer.from(DISCRIMINATORS.settle_locked_voucher);
+  const swigWalletAddress = deriveSwigWalletAddress(p.swigAddress);
+  return new TransactionInstruction2({
+    programId: DEXTER_VAULT_PROGRAM_ID,
+    keys: [
+      { pubkey: p.swigAddress, isSigner: false, isWritable: false },
+      { pubkey: swigWalletAddress, isSigner: false, isWritable: false },
+      { pubkey: p.claimPda, isSigner: false, isWritable: true },
+      { pubkey: p.vaultPda, isSigner: false, isWritable: true },
+      { pubkey: p.holder, isSigner: true, isWritable: false },
+      { pubkey: p.dexterAuthority, isSigner: true, isWritable: false }
+    ],
+    data
+  });
+}
+
+// src/kit/index.ts
+import { PublicKey as PublicKey4, TransactionInstruction as TransactionInstruction3 } from "@solana/web3.js";
+import { createSolanaRpc } from "@solana/kit";
+function kitInstructionsToWeb3(kitInstructions) {
+  return kitInstructions.map((ix) => {
+    const accounts = (ix.accounts ?? []).map((acc) => {
+      const role = acc.role;
+      const hasBooleanShape = typeof acc.signer === "boolean" || typeof acc.writable === "boolean";
+      let isSigner = false;
+      let isWritable = false;
+      if (hasBooleanShape) {
+        isSigner = Boolean(acc.signer);
+        isWritable = Boolean(acc.writable);
+      } else if (typeof role === "number") {
+        isSigner = role >= 2;
+        isWritable = role % 2 === 1;
+      } else if (typeof role === "string") {
+        const r = role.toLowerCase();
+        isSigner = r.endsWith("signer");
+        isWritable = r.startsWith("writable");
+      }
+      const addressSource = acc.address ?? acc.publicKey;
+      const pubkey = addressSource instanceof PublicKey4 ? addressSource : typeof addressSource === "string" ? new PublicKey4(addressSource) : new PublicKey4(String(addressSource));
+      return { pubkey, isSigner, isWritable };
+    });
+    return new TransactionInstruction3({
+      programId: new PublicKey4(ix.programAddress ?? ix.programId),
+      keys: accounts,
+      data: Buffer.from(ix.data ?? [])
+    });
+  });
+}
+function getRpc(connection) {
+  const endpoint = connection._rpcEndpoint ?? connection.rpcEndpoint;
+  if (!endpoint) throw new Error("kit: cannot extract RPC endpoint from connection");
+  return createSolanaRpc(endpoint);
+}
+
+// src/factoring/instantPayout.ts
+var VAULT_PROGRAM_EXEC_ROLE_ID = 1;
+var USDC_DECIMALS = 6;
+async function buildInstantPayoutInstructions(p) {
+  const split = computeFactoringSplit({
+    claimAmount: p.claimAmount,
+    financierSpread: p.financierSpread
+  });
+  const settleIx = buildSettleLockedVoucherInstruction({
+    swigAddress: p.swigAddress,
+    claimPda: p.claimPda,
+    vaultPda: p.vaultPda,
+    holder: p.financier,
+    dexterAuthority: p.dexterAuthority
+  });
+  const transfers = [
+    { destinationAta: p.sellerAta, amount: split.sellerReceives }
+  ];
+  if (split.financierSpread > 0n) {
+    transfers.push({ destinationAta: p.financierAta, amount: split.financierSpread });
+  }
+  const assemble = p.assembleSignV2 ?? defaultAssembleSignV2;
+  const signV2Ixs = await assemble({
+    connection: p.connection,
+    swigAddress: p.swigAddress,
+    feePayer: p.feePayer,
+    settleIx,
+    transfers
+  });
+  return [settleIx, ...signV2Ixs];
+}
+var defaultAssembleSignV2 = async (a) => {
+  const rpc = getRpc(a.connection);
+  const swig = await fetchSwig(rpc, kitAddress(a.swigAddress.toBase58()));
+  if (!swig) throw new Error(`factoring: swig not found on-chain: ${a.swigAddress.toBase58()}`);
+  const swigWalletKitAddr = await getSwigWalletAddress(swig);
+  const swigWalletPda = new PublicKey5(String(swigWalletKitAddr));
+  const usdcMint = new PublicKey5(USDC_MAINNET);
+  const sourceAta = getAssociatedTokenAddressSync(usdcMint, swigWalletPda, true);
+  const transferIxs = a.transfers.map(
+    (t) => getTransferCheckedInstruction({
+      source: kitAddress(sourceAta.toBase58()),
+      mint: kitAddress(usdcMint.toBase58()),
+      destination: kitAddress(t.destinationAta.toBase58()),
+      authority: swigWalletKitAddr,
+      amount: t.amount,
+      decimals: USDC_DECIMALS
+    })
+  );
+  const signIx = await getSignInstructions(
+    swig,
+    VAULT_PROGRAM_EXEC_ROLE_ID,
+    transferIxs,
+    false,
+    { payer: kitAddress(a.feePayer.toBase58()), preInstructions: [a.settleIx] }
+  );
+  return kitInstructionsToWeb3(signIx);
+};
+export {
+  buildInstantPayoutInstructions,
+  computeFactoringSplit,
+  getRpc,
+  kitInstructionsToWeb3
+};