@brainai/satp-client 2.0.3 → 2.0.4

package/src/v3-pda.js

@@ -6,15 +6,33 @@ const crypto = require('crypto');
 // ═══════════════════════════════════════════════════
 
 const V3_DEVNET_PROGRAM_IDS = {
+  IDENTITY: new PublicKey('7qmfg4CgiXVDZGBeUkSkMsacKjCRty2xEAugPK4nfvZQ'),
+  REVIEWS: new PublicKey('3yVFrWCpBnQdWNqmiCG9EpoZq7WYeQ421Gx5sUh41Kwk'),
+  REPUTATION: new PublicKey('CtmZ1fHaypt3R6wbeiGawiRnjzRK9T8jsECk9mET9AK9'),
+  ATTESTATIONS: new PublicKey('55aS2y5Lhe427iW4cgo2nmZPrxwH3F7BWkw6MnoEm4zw'),
+  VALIDATION: new PublicKey('DLB76DzAFY8KNuvnP79BZW3cehGreEQTeGDvFCNd2Ekj'),
+  ESCROW: new PublicKey('B1Se8SPx7GLUisa4LYeXY1tDZy5TviJrsV2yMLgqUXmg'),
+};
+
+// Mainnet registry source: Anchor.toml [programs.mainnet], checked by
+// scripts/verify-v3-program-sources.mjs and the D1 authority packet.
+// docs/mainnet-authority-decision-packet-6c8a5545.md remains the owner-gating
+// packet for deploy/key/publish actions. Keep V3 separate from legacy V2
+// MAINNET_PROGRAM_IDS in constants.js; do not fall back to V2 program IDs.
+const V3_MAINNET_PROGRAM_IDS = {
   IDENTITY: new PublicKey('GTppU4E44BqXTQgbqMZ68ozFzhP1TLty3EGnzzjtNZfG'),
   REVIEWS: new PublicKey('r9XX4frcqxxAZ6Au9V5PA3EAxs1zoNckqLLmoSRcNr4'),
   REPUTATION: new PublicKey('2Lz7KzMvKdrGeAuS8WPHu7jK2yScrnKVgacpYVEuDjkJ'),
   ATTESTATIONS: new PublicKey('6Xd1dAQJPvQRJ4Ntr6LtPTjDjPUZ8nfnmYLZaZ2DtrdD'),
   VALIDATION: new PublicKey('6rYRiCYidJYV7QvKrzKGgNu4oMh6BAvynked69R7xMbV'),
-  ESCROW: new PublicKey('B1Se8SPx7GLUisa4LYeXY1tDZy5TviJrsV2yMLgqUXmg'),
+  ESCROW: new PublicKey('HXCUWKR2NvRcZ7rNAJHwPcH6QAAWaLR4bRFbfyuDND6C'),
 };
+const SPL_TOKEN_PROGRAM_ID = new PublicKey('TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA');
+const ASSOCIATED_TOKEN_PROGRAM_ID = new PublicKey('ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL');
 
-const V3_MAINNET_PROGRAM_IDS = null;
+const V3_DEVNET_TOKEN_MINTS = {
+  USDC: new PublicKey('4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU'),
+};
 
 // ═══════════════════════════════════════════════════
 //  V3 PDA Seeds — must match on-chain programs
@@ -41,10 +59,7 @@ function getV3ProgramIds(network = 'devnet') {
   if (network !== 'devnet' && network !== 'mainnet') {
     throw new Error('Invalid network: expected devnet or mainnet');
   }
-  if (network === 'mainnet') {
-    throw new Error('SATP V3 mainnet program IDs are not configured; use devnet or provide an approved mainnet decision packet before enabling mainnet');
-  }
-  return V3_DEVNET_PROGRAM_IDS;
+  return network === 'mainnet' ? V3_MAINNET_PROGRAM_IDS : V3_DEVNET_PROGRAM_IDS;
 }
 
 // ═══════════════════════════════════════════════════
@@ -256,10 +271,44 @@ function getV3EscrowPDA(client, descriptionHash, nonce, network = 'devnet') {
   );
 }
 
+/**
+ * Derive the canonical associated token account address.
+ * Seeds: [owner, SPL Token program, mint]
+ * @param {PublicKey|string} owner
+ * @param {PublicKey|string} mint
+ * @returns {[PublicKey, number]}
+ */
+function getAssociatedTokenAddress(owner, mint) {
+  const ownerKey = new PublicKey(owner);
+  const mintKey = new PublicKey(mint);
+  return PublicKey.findProgramAddressSync(
+    [ownerKey.toBuffer(), SPL_TOKEN_PROGRAM_ID.toBuffer(), mintKey.toBuffer()],
+    ASSOCIATED_TOKEN_PROGRAM_ID
+  );
+}
+
+/**
+ * Derive the escrow PDA and its SPL vault ATA for a mint.
+ * @param {PublicKey|string} client
+ * @param {Buffer} descriptionHash
+ * @param {number|bigint} nonce
+ * @param {PublicKey|string} mint
+ * @param {'mainnet'|'devnet'} network
+ * @returns {{ escrowPDA: PublicKey, escrowBump: number, vaultATA: PublicKey, vaultBump: number }}
+ */
+function getV3EscrowVaultATA(client, descriptionHash, nonce, mint, network = 'devnet') {
+  const [escrowPDA, escrowBump] = getV3EscrowPDA(client, descriptionHash, nonce, network);
+  const [vaultATA, vaultBump] = getAssociatedTokenAddress(escrowPDA, mint);
+  return { escrowPDA, escrowBump, vaultATA, vaultBump };
+}
+
 module.exports = {
   // Program IDs
   V3_DEVNET_PROGRAM_IDS,
   V3_MAINNET_PROGRAM_IDS,
+  V3_DEVNET_TOKEN_MINTS,
+  SPL_TOKEN_PROGRAM_ID,
+  ASSOCIATED_TOKEN_PROGRAM_ID,
   getV3ProgramIds,
   V3_SEEDS,
 
@@ -278,4 +327,6 @@ module.exports = {
   getV3ReviewCounterPDA,
   getV3AttestationPDA,
   getV3EscrowPDA,
+  getAssociatedTokenAddress,
+  getV3EscrowVaultATA,
 };

package/src/v3-sdk.d.ts

@@ -124,16 +124,41 @@ export interface UpdateReviewFields {
 }
 
 export type EscrowStatus = 'Active' | 'WorkSubmitted' | 'Released' | 'Cancelled' | 'Disputed' | 'Resolved';
+export type EscrowCurrency = 'SOL' | 'USDC';
 
 export interface CreateEscrowOpts {
+  currency?: EscrowCurrency;
   minVerificationLevel?: number;
   requireBorn?: boolean;
   arbiter?: PublicKey | string;
+  mint?: PublicKey | string;
+  tokenDecimals?: number;
+  createVaultAta?: boolean;
 }
 
 export interface CreateEscrowResult extends TransactionResult {
   escrowPDA: PublicKey;
   descriptionHash: Buffer;
+  currency?: EscrowCurrency;
+  mint?: PublicKey;
+  clientTokenAccount?: PublicKey;
+  vaultTokenAccount?: PublicKey;
+}
+
+export interface UsdcEscrowAccountOpts {
+  currency?: 'USDC';
+  mint?: PublicKey | string;
+  tokenDecimals?: number;
+  createVaultAta?: boolean;
+  createAgentAta?: boolean;
+  createClientAta?: boolean;
+}
+
+export interface UsdcEscrowResult extends TransactionResult {
+  mint: PublicKey;
+  vaultTokenAccount: PublicKey;
+  agentTokenAccount?: PublicKey;
+  clientTokenAccount?: PublicKey;
 }
 
 export interface SubmitWorkResult extends TransactionResult {
@@ -161,6 +186,11 @@ export interface V3Escrow {
   descriptionHash: string;
   deadline: number;
   nonce: number;
+  currency: EscrowCurrency | string;
+  currencyCode: number;
+  tokenMint: string | null;
+  tokenVault: string | null;
+  tokenDecimals: number | null;
   status: EscrowStatus;
   statusCode: number;
   minVerificationLevel: number;
@@ -413,6 +443,18 @@ export class SATPV3SDK {
     opts?: CreateEscrowOpts
   ): Promise<CreateEscrowResult>;
 
+  /** Build createEscrow transaction for USDC/SPL token escrow. */
+  buildCreateUsdcEscrow(
+    client: PublicKey | string,
+    agentWallet: PublicKey | string,
+    agentId: string,
+    amount: number,
+    descriptionOrHash: string | Buffer,
+    deadline: number,
+    nonce?: number,
+    opts?: UsdcEscrowAccountOpts & Pick<CreateEscrowOpts, 'minVerificationLevel' | 'requireBorn' | 'arbiter'>
+  ): Promise<CreateEscrowResult>;
+
   /** Build submitWork transaction (agent submits work proof). */
   buildSubmitWork(
     agent: PublicKey | string,
@@ -424,23 +466,50 @@ export class SATPV3SDK {
   buildEscrowRelease(
     client: PublicKey | string,
     agent: PublicKey | string,
-    escrowPDA: PublicKey | string
+    escrowPDA: PublicKey | string,
+    opts?: UsdcEscrowAccountOpts
   ): Promise<TransactionResult>;
 
+  /** Build release transaction for USDC/SPL escrow funds. */
+  buildUsdcEscrowRelease(
+    client: PublicKey | string,
+    agent: PublicKey | string,
+    escrowPDA: PublicKey | string,
+    opts?: UsdcEscrowAccountOpts
+  ): Promise<UsdcEscrowResult>;
+
   /** Build partialRelease transaction (milestone payment). */
   buildPartialRelease(
     client: PublicKey | string,
     agent: PublicKey | string,
     escrowPDA: PublicKey | string,
-    amount: number
+    amount: number,
+    opts?: UsdcEscrowAccountOpts
   ): Promise<TransactionResult>;
 
+  /** Build partial release transaction for USDC/SPL escrow funds. */
+  buildPartialUsdcEscrowRelease(
+    client: PublicKey | string,
+    agent: PublicKey | string,
+    escrowPDA: PublicKey | string,
+    amount: number,
+    opts?: UsdcEscrowAccountOpts
+  ): Promise<UsdcEscrowResult>;
+
   /** Build cancel transaction (client cancels after deadline). */
   buildCancelEscrow(
     client: PublicKey | string,
-    escrowPDA: PublicKey | string
+    escrowPDA: PublicKey | string,
+    opts?: UsdcEscrowAccountOpts
   ): Promise<TransactionResult>;
 
+  /** Build cancel transaction for USDC/SPL escrow refund. */
+  buildUsdcCancelEscrow(
+    client: PublicKey | string,
+    escrowPDA: PublicKey | string,
+    opts?: UsdcEscrowAccountOpts
+  ): Promise<UsdcEscrowResult>;
+
   /** Build raiseDispute transaction (either client or agent). */
   buildRaiseDispute(
     signer: PublicKey | string,
@@ -455,9 +524,21 @@ export class SATPV3SDK {
     clientWallet: PublicKey | string,
     escrowPDA: PublicKey | string,
     agentAmount: number,
-    clientAmount: number
+    clientAmount: number,
+    opts?: UsdcEscrowAccountOpts
   ): Promise<TransactionResult>;
 
+  /** Build resolveDispute transaction for USDC/SPL escrow funds. */
+  buildUsdcResolveDispute(
+    arbiter: PublicKey | string,
+    agent: PublicKey | string,
+    clientWallet: PublicKey | string,
+    escrowPDA: PublicKey | string,
+    agentAmount: number,
+    clientAmount: number,
+    opts?: UsdcEscrowAccountOpts
+  ): Promise<UsdcEscrowResult>;
+
   /** Build extendDeadline transaction (client extends escrow deadline). */
   buildExtendDeadline(
     client: PublicKey | string,