@brainai/satp-client 2.0.0 → 2.0.1

package/src/index.js

@@ -16,6 +16,8 @@ const {
   getReviewsAuthorityPDA,
   getReviewPDA,
   getReviewAttestationPDA,
+  getEscrowPDA,
+  getReviewV3PDA,
 } = require('./pda');
 const {
   IdentityAccount, IDENTITY_SCHEMA,
@@ -287,6 +289,468 @@ class SATPSDK {
 
   // ─── Utility ───────────────────────────────────────────
 
+  // ─── Escrow ─────────────────────────────────────────────
+
+  /**
+   * Build a createEscrow transaction.
+   * @param {PublicKey|string} clientWallet - Client (payer + signer)
+   * @param {PublicKey|string} agentWallet - Agent to receive funds on release
+   * @param {number} amountLamports - Amount in lamports to escrow
+   * @param {string} description - Job description (will be SHA256-hashed for PDA seed)
+   * @param {number} deadlineUnix - Unix timestamp deadline
+   * @returns {{ transaction: Transaction, escrowPDA: PublicKey, descriptionHash: Buffer }}
+   */
+  async buildCreateEscrow(clientWallet, agentWallet, amountLamports, description, deadlineUnix) {
+    const clientKey = new PublicKey(clientWallet);
+    const agentKey = new PublicKey(agentWallet);
+    const descHash = crypto.createHash('sha256').update(description).digest();
+    const [escrowPDA] = getEscrowPDA(clientKey, descHash, this.network);
+
+    const disc = anchorDiscriminator('create_escrow');
+
+    // Serialize: agent (32) + amount (u64 LE 8) + description_hash (32) + deadline (i64 LE 8)
+    const agentBuf = agentKey.toBuffer();
+    const amountBuf = Buffer.alloc(8);
+    amountBuf.writeBigUInt64LE(BigInt(amountLamports));
+    const deadlineBuf = Buffer.alloc(8);
+    deadlineBuf.writeBigInt64LE(BigInt(deadlineUnix));
+
+    const data = Buffer.concat([disc, agentBuf, amountBuf, descHash, deadlineBuf]);
+
+    const ix = new TransactionInstruction({
+      programId: this.programIds.ESCROW,
+      keys: [
+        { pubkey: clientKey, isSigner: true, isWritable: true },
+        { pubkey: escrowPDA, isSigner: false, isWritable: true },
+        { pubkey: SystemProgram.programId, isSigner: false, isWritable: false },
+      ],
+      data,
+    });
+
+    const tx = new Transaction().add(ix);
+    tx.feePayer = clientKey;
+    tx.recentBlockhash = (await this.connection.getLatestBlockhash()).blockhash;
+
+    return { transaction: tx, escrowPDA, descriptionHash: descHash };
+  }
+
+  /**
+   * Build a release transaction (client releases funds to agent).
+   * @param {PublicKey|string} clientWallet - Client (signer)
+   * @param {PublicKey|string} agentWallet - Agent receiving funds
+   * @param {PublicKey|string} escrowPDA - Escrow account PDA
+   * @returns {{ transaction: Transaction }}
+   */
+  async buildRelease(clientWallet, agentWallet, escrowPDA) {
+    const clientKey = new PublicKey(clientWallet);
+    const agentKey = new PublicKey(agentWallet);
+    const escrowKey = new PublicKey(escrowPDA);
+
+    const disc = anchorDiscriminator('release');
+
+    const ix = new TransactionInstruction({
+      programId: this.programIds.ESCROW,
+      keys: [
+        { pubkey: escrowKey, isSigner: false, isWritable: true },
+        { pubkey: clientKey, isSigner: true, isWritable: false },
+        { pubkey: agentKey, isSigner: false, isWritable: true },
+      ],
+      data: disc,
+    });
+
+    const tx = new Transaction().add(ix);
+    tx.feePayer = clientKey;
+    tx.recentBlockhash = (await this.connection.getLatestBlockhash()).blockhash;
+
+    return { transaction: tx };
+  }
+
+  /**
+   * Build a submitWork transaction (agent submits work proof).
+   * @param {PublicKey|string} agentWallet - Agent (signer)
+   * @param {PublicKey|string} escrowPDA - Escrow account PDA
+   * @param {string} workProof - Work proof (will be SHA256-hashed)
+   * @returns {{ transaction: Transaction, workHash: Buffer }}
+   */
+  async buildSubmitWork(agentWallet, escrowPDA, workProof) {
+    const agentKey = new PublicKey(agentWallet);
+    const escrowKey = new PublicKey(escrowPDA);
+    const workHash = crypto.createHash('sha256').update(workProof).digest();
+
+    const disc = anchorDiscriminator('submit_work');
+    const data = Buffer.concat([disc, workHash]);
+
+    const ix = new TransactionInstruction({
+      programId: this.programIds.ESCROW,
+      keys: [
+        { pubkey: escrowKey, isSigner: false, isWritable: true },
+        { pubkey: agentKey, isSigner: true, isWritable: false },
+      ],
+      data,
+    });
+
+    const tx = new Transaction().add(ix);
+    tx.feePayer = agentKey;
+    tx.recentBlockhash = (await this.connection.getLatestBlockhash()).blockhash;
+
+    return { transaction: tx, workHash };
+  }
+
+  /**
+   * Build a cancel transaction (client cancels after deadline).
+   * @param {PublicKey|string} clientWallet - Client (signer)
+   * @param {PublicKey|string} escrowPDA - Escrow account PDA
+   * @returns {{ transaction: Transaction }}
+   */
+  async buildCancel(clientWallet, escrowPDA) {
+    const clientKey = new PublicKey(clientWallet);
+    const escrowKey = new PublicKey(escrowPDA);
+
+    const disc = anchorDiscriminator('cancel');
+
+    const ix = new TransactionInstruction({
+      programId: this.programIds.ESCROW,
+      keys: [
+        { pubkey: escrowKey, isSigner: false, isWritable: true },
+        { pubkey: clientKey, isSigner: true, isWritable: true },
+      ],
+      data: disc,
+    });
+
+    const tx = new Transaction().add(ix);
+    tx.feePayer = clientKey;
+    tx.recentBlockhash = (await this.connection.getLatestBlockhash()).blockhash;
+
+    return { transaction: tx };
+  }
+
+  /**
+   * Build a raiseDispute transaction (either party disputes).
+   * @param {PublicKey|string} signerWallet - Client or agent (signer)
+   * @param {PublicKey|string} escrowPDA - Escrow account PDA
+   * @returns {{ transaction: Transaction }}
+   */
+  async buildRaiseDispute(signerWallet, escrowPDA) {
+    const signerKey = new PublicKey(signerWallet);
+    const escrowKey = new PublicKey(escrowPDA);
+
+    const disc = anchorDiscriminator('raise_dispute');
+
+    const ix = new TransactionInstruction({
+      programId: this.programIds.ESCROW,
+      keys: [
+        { pubkey: escrowKey, isSigner: false, isWritable: true },
+        { pubkey: signerKey, isSigner: true, isWritable: false },
+      ],
+      data: disc,
+    });
+
+    const tx = new Transaction().add(ix);
+    tx.feePayer = signerKey;
+    tx.recentBlockhash = (await this.connection.getLatestBlockhash()).blockhash;
+
+    return { transaction: tx };
+  }
+
+  /**
+   * Build a closeEscrow transaction (returns rent to client).
+   * @param {PublicKey|string} clientWallet - Client (signer)
+   * @param {PublicKey|string} escrowPDA - Escrow account PDA
+   * @returns {{ transaction: Transaction }}
+   */
+  async buildCloseEscrow(clientWallet, escrowPDA) {
+    const clientKey = new PublicKey(clientWallet);
+    const escrowKey = new PublicKey(escrowPDA);
+
+    const disc = anchorDiscriminator('close_escrow');
+
+    const ix = new TransactionInstruction({
+      programId: this.programIds.ESCROW,
+      keys: [
+        { pubkey: escrowKey, isSigner: false, isWritable: true },
+        { pubkey: clientKey, isSigner: true, isWritable: true },
+      ],
+      data: disc,
+    });
+
+    const tx = new Transaction().add(ix);
+    tx.feePayer = clientKey;
+    tx.recentBlockhash = (await this.connection.getLatestBlockhash()).blockhash;
+
+    return { transaction: tx };
+  }
+
+  /**
+   * Build a resolveDispute transaction.
+   * Only the client (arbiter in V1) can resolve. Decides: release to agent or refund to client.
+   * @param {PublicKey|string} clientWallet - Client/arbiter (signer)
+   * @param {PublicKey|string} agentWallet - Agent account
+   * @param {PublicKey|string} escrowPDA - Escrow account PDA
+   * @param {boolean} releaseToAgent - true = release to agent, false = refund to client
+   * @returns {{ transaction: Transaction }}
+   */
+  async buildResolveDispute(clientWallet, agentWallet, escrowPDA, releaseToAgent) {
+    const clientKey = new PublicKey(clientWallet);
+    const agentKey = new PublicKey(agentWallet);
+    const escrowKey = new PublicKey(escrowPDA);
+
+    const disc = anchorDiscriminator('resolve_dispute');
+    const data = Buffer.alloc(8 + 1);
+    disc.copy(data, 0);
+    data.writeUInt8(releaseToAgent ? 1 : 0, 8);
+
+    const ix = new TransactionInstruction({
+      programId: this.programIds.ESCROW,
+      keys: [
+        { pubkey: escrowKey, isSigner: false, isWritable: true },
+        { pubkey: clientKey, isSigner: true, isWritable: false },  // arbiter
+        { pubkey: agentKey, isSigner: false, isWritable: true },   // agent
+        { pubkey: clientKey, isSigner: false, isWritable: true },  // client_wallet
+      ],
+      data,
+    });
+
+    const tx = new Transaction().add(ix);
+    tx.feePayer = clientKey;
+    tx.recentBlockhash = (await this.connection.getLatestBlockhash()).blockhash;
+
+    return { transaction: tx };
+  }
+
+  /**
+   * Fetch escrow state from on-chain account.
+   * @param {PublicKey|string} escrowPDA
+   * @returns {object|null} Escrow state or null if not found
+   */
+  async getEscrow(escrowPDA) {
+    const escrowKey = new PublicKey(escrowPDA);
+    const acct = await this.connection.getAccountInfo(escrowKey);
+    if (!acct) return null;
+
+    try {
+      // Skip 8-byte Anchor discriminator
+      const data = acct.data.slice(8);
+      const client = new PublicKey(data.slice(0, 32));
+      const agent = new PublicKey(data.slice(32, 64));
+      const amount = Number(data.readBigUInt64LE(64));
+      const descriptionHash = data.slice(72, 104);
+      const deadline = Number(data.readBigInt64LE(104));
+      const statusByte = data[112];
+      const createdAt = Number(data.readBigInt64LE(113));
+      const bump = data[121];
+
+      const statusMap = ['Active', 'Released', 'Cancelled', 'WorkSubmitted', 'Disputed'];
+      const status = statusMap[statusByte] || `Unknown(${statusByte})`;
+
+      // Optional work_hash (1 byte option flag + 32 bytes)
+      let workHash = null;
+      if (data[122] === 1) {
+        workHash = data.slice(123, 155).toString('hex');
+      }
+
+      return {
+        client: client.toBase58(),
+        agent: agent.toBase58(),
+        amount,
+        descriptionHash: descriptionHash.toString('hex'),
+        deadline,
+        status,
+        createdAt,
+        bump,
+        workHash,
+        pda: escrowKey.toBase58(),
+      };
+    } catch (e) {
+      return { pda: escrowKey.toBase58(), raw: acct.data.toString('hex'), error: e.message };
+    }
+  }
+
+  // ─── Reviews V3 (Job-Scoped) ─────────────────────────────
+
+  /**
+   * Build a submitReview transaction (Reviews V3 — job-scoped).
+   * Reviewer must be a party to the completed/resolved job (poster or accepted_agent).
+   * Requires reviewer to have a registered SATP Identity.
+   *
+   * @param {PublicKey|string} reviewerWallet - Reviewer (signer, must be job party)
+   * @param {PublicKey|string} reviewerIdentityPDA - Reviewer's SATP Identity PDA
+   * @param {PublicKey|string} jobPDA - Job/Escrow account PDA
+   * @param {object} ratings - { rating, quality, reliability, communication } (all 1-5)
+   * @param {string} commentUri - URI to off-chain comment (IPFS, Arweave, etc.)
+   * @param {Buffer|string} commentHash - 32-byte SHA256 hash of comment content
+   * @returns {{ transaction: Transaction, reviewPDA: PublicKey }}
+   */
+  async buildSubmitReview(reviewerWallet, reviewerIdentityPDA, jobPDA, ratings, commentUri, commentHash) {
+    const reviewerKey = new PublicKey(reviewerWallet);
+    const identityPDA = new PublicKey(reviewerIdentityPDA);
+    const jobKey = new PublicKey(jobPDA);
+    const [reviewPDA] = getReviewV3PDA(jobKey, reviewerKey, this.network);
+
+    const hashBuf = Buffer.isBuffer(commentHash)
+      ? commentHash
+      : crypto.createHash('sha256').update(commentHash).digest();
+
+    const disc = anchorDiscriminator('submit_review');
+    const uriBytes = Buffer.from(commentUri, 'utf8');
+
+    // Serialize: rating (u8) + quality (u8) + reliability (u8) + communication (u8)
+    //   + uri_len (u32 LE) + uri_bytes + hash (32 bytes)
+    const data = Buffer.concat([
+      disc,
+      Buffer.from([ratings.rating]),
+      Buffer.from([ratings.quality]),
+      Buffer.from([ratings.reliability]),
+      Buffer.from([ratings.communication]),
+      Buffer.from(new Uint32Array([uriBytes.length]).buffer),
+      uriBytes,
+      hashBuf,
+    ]);
+
+    // Identity program ID (hardcoded in Reviews V3 program)
+    const IDENTITY_PROGRAM = new PublicKey('EJtQh4Gyg88zXvSmFpxYkkeZsPwTsjfm4LvjmPQX1FD3');
+    // Escrow program ID
+    const ESCROW_PROGRAM = this.programIds.ESCROW;
+
+    const ix = new TransactionInstruction({
+      programId: this.programIds.REVIEWS,
+      keys: [
+        { pubkey: reviewerKey, isSigner: true, isWritable: true },
+        { pubkey: identityPDA, isSigner: false, isWritable: false },
+        { pubkey: jobKey, isSigner: false, isWritable: false },
+        { pubkey: reviewPDA, isSigner: false, isWritable: true },
+        { pubkey: IDENTITY_PROGRAM, isSigner: false, isWritable: false },
+        { pubkey: ESCROW_PROGRAM, isSigner: false, isWritable: false },
+        { pubkey: SystemProgram.programId, isSigner: false, isWritable: false },
+      ],
+      data,
+    });
+
+    const tx = new Transaction().add(ix);
+    tx.feePayer = reviewerKey;
+    tx.recentBlockhash = (await this.connection.getLatestBlockhash()).blockhash;
+
+    return { transaction: tx, reviewPDA };
+  }
+
+  /**
+   * Build a respondToReview transaction (Reviews V3).
+   * Only the reviewed party can respond, and only once.
+   *
+   * @param {PublicKey|string} responderWallet - Reviewed party (signer)
+   * @param {PublicKey|string} reviewPDA - Review account PDA
+   * @param {string} responseUri - URI to off-chain response content
+   * @param {Buffer|string} responseHash - 32-byte SHA256 hash of response content
+   * @returns {{ transaction: Transaction }}
+   */
+  async buildRespondToReview(responderWallet, reviewPDA, responseUri, responseHash) {
+    const responderKey = new PublicKey(responderWallet);
+    const reviewKey = new PublicKey(reviewPDA);
+
+    const hashBuf = Buffer.isBuffer(responseHash)
+      ? responseHash
+      : crypto.createHash('sha256').update(responseHash).digest();
+
+    const disc = anchorDiscriminator('respond_to_review');
+    const uriBytes = Buffer.from(responseUri, 'utf8');
+
+    const data = Buffer.concat([
+      disc,
+      Buffer.from(new Uint32Array([uriBytes.length]).buffer),
+      uriBytes,
+      hashBuf,
+    ]);
+
+    const ix = new TransactionInstruction({
+      programId: this.programIds.REVIEWS,
+      keys: [
+        { pubkey: responderKey, isSigner: true, isWritable: true },
+        { pubkey: reviewKey, isSigner: false, isWritable: true },
+      ],
+      data,
+    });
+
+    const tx = new Transaction().add(ix);
+    tx.feePayer = responderKey;
+    tx.recentBlockhash = (await this.connection.getLatestBlockhash()).blockhash;
+
+    return { transaction: tx };
+  }
+
+  /**
+   * Fetch a review from on-chain.
+   * @param {PublicKey|string} reviewPDA
+   * @returns {object|null} Review data or null if not found
+   */
+  async getReview(reviewPDA) {
+    const reviewKey = new PublicKey(reviewPDA);
+    const acct = await this.connection.getAccountInfo(reviewKey);
+    if (!acct) return null;
+
+    try {
+      const data = acct.data.slice(8); // skip Anchor discriminator
+      let offset = 0;
+
+      const reviewer = new PublicKey(data.slice(offset, offset + 32)); offset += 32;
+      const reviewed = new PublicKey(data.slice(offset, offset + 32)); offset += 32;
+      const jobId = Number(data.readBigUInt64LE(offset)); offset += 8;
+      const jobRef = new PublicKey(data.slice(offset, offset + 32)); offset += 32;
+      const rating = data[offset]; offset += 1;
+      const categoryQuality = data[offset]; offset += 1;
+      const categoryReliability = data[offset]; offset += 1;
+      const categoryCommunication = data[offset]; offset += 1;
+
+      // String: 4-byte length prefix + bytes
+      const uriLen = data.readUInt32LE(offset); offset += 4;
+      const commentUri = data.slice(offset, offset + uriLen).toString('utf8'); offset += uriLen;
+
+      const commentHash = data.slice(offset, offset + 32).toString('hex'); offset += 32;
+      const timestamp = Number(data.readBigInt64LE(offset)); offset += 8;
+      const hasResponse = data[offset] === 1; offset += 1;
+
+      // Response string
+      const resUriLen = data.readUInt32LE(offset); offset += 4;
+      const responseUri = data.slice(offset, offset + resUriLen).toString('utf8'); offset += resUriLen;
+
+      const responseHash = data.slice(offset, offset + 32).toString('hex'); offset += 32;
+      const responseTimestamp = Number(data.readBigInt64LE(offset)); offset += 8;
+      const bump = data[offset]; offset += 1;
+
+      return {
+        reviewer: reviewer.toBase58(),
+        reviewed: reviewed.toBase58(),
+        jobId,
+        jobRef: jobRef.toBase58(),
+        rating,
+        categoryQuality,
+        categoryReliability,
+        categoryCommunication,
+        commentUri,
+        commentHash,
+        timestamp,
+        hasResponse,
+        responseUri: hasResponse ? responseUri : null,
+        responseHash: hasResponse ? responseHash : null,
+        responseTimestamp: hasResponse ? responseTimestamp : null,
+        bump,
+        pda: reviewKey.toBase58(),
+      };
+    } catch (e) {
+      return { pda: reviewKey.toBase58(), raw: acct.data.toString('hex'), error: e.message };
+    }
+  }
+
+  /**
+   * Derive Review V3 PDA (job-scoped).
+   * @param {PublicKey|string} jobPDA
+   * @param {PublicKey|string} reviewer
+   * @returns {[PublicKey, number]} [pda, bump]
+   */
+  getReviewV3PDA(jobPDA, reviewer) {
+    return getReviewV3PDA(jobPDA, reviewer, this.network);
+  }
+
+  // ─── Utility ───────────────────────────────────────────
+
   /**
    * Derive all PDAs for a wallet without RPC calls.
    */
@@ -308,7 +772,109 @@ class SATPSDK {
   }
 }
 
+// V3 SDK — local extracted SATP v3 scaffold.
+// Do not require the legacy external v3 package here; SATP-EXTRACT-001 must be self-contained.
+const v3sdk = require('./v3-sdk');
+const v3pda = require('./v3-pda');
+const v3Borsh = require('./borsh-reader');
+const { prepareIdentityAttestationRequest } = require('./attestation-request');
+const {
+  TRUST_PACKET_SCHEMA_VERSION,
+  buildSatpTrustPacket,
+  validateSatpTrustPacket,
+} = require('./trust-packet');
+
+// Legacy V3 SDK wrapper — keeps string constructor compatibility while using
+// the local extracted SATPV3SDK implementation so offline tests and consumers
+// see the expected programIds, rpcUrl, and SDK methods.
+class SATPV3SDK extends v3sdk.SATPV3SDK {
+  constructor(opts = {}) {
+    super(opts);
+  }
+}
+
+function createSATPClient(opts = {}) {
+  if (typeof opts === 'string') {
+    return v3sdk.createSATPClient(opts);
+  }
+  return v3sdk.createSATPClient({
+    rpcUrl: opts.rpcUrl || opts.url || opts.endpoint,
+    network: opts.network,
+    commitment: opts.commitment,
+  });
+}
+
+// Legacy borsh reader — keep for any V2 code paths
+const borshReader = require('./borsh-reader');
+
+
+// Fixed genesis deserializer — matches actual on-chain struct (no isActive field)
+function _deserializeGenesisFixed(data) {
+  if (!data || data.length < 8) return null;
+  try {
+    const { PublicKey } = require('@solana/web3.js');
+    let offset = 8; // skip discriminator
+    const agentIdHashBytes = data.slice(offset, offset + 32); offset += 32;
+    const readString = () => {
+      const len = data.readUInt32LE(offset); offset += 4;
+      const str = data.slice(offset, offset + len).toString('utf8'); offset += len;
+      return str;
+    };
+    const readVecString = () => {
+      const count = data.readUInt32LE(offset); offset += 4;
+      const arr = [];
+      for (let i = 0; i < count; i++) arr.push(readString());
+      return arr;
+    };
+    const agentName = readString();
+    const description = readString();
+    const category = readString();
+    const capabilities = readVecString();
+    const metadataUri = readString();
+    const faceImage = readString();
+    const faceMint = new PublicKey(data.slice(offset, offset + 32)); offset += 32;
+    const faceBurnTx = readString();
+    const genesisRecord = Number(data.readBigInt64LE(offset)); offset += 8;
+    // NOTE: No isActive field in deployed program (SDK bug — has phantom isActive)
+    const authority = new PublicKey(data.slice(offset, offset + 32)); offset += 32;
+    const hasPending = data[offset]; offset += 1;
+    let pendingAuthority = null;
+    if (hasPending === 1) {
+      pendingAuthority = new PublicKey(data.slice(offset, offset + 32)).toBase58();
+      offset += 32;
+    }
+    const reputationScore = Number(data.readBigUInt64LE(offset)); offset += 8;
+    const verificationLevel = data[offset]; offset += 1;
+    const reputationUpdatedAt = Number(data.readBigInt64LE(offset)); offset += 8;
+    const verificationUpdatedAt = Number(data.readBigInt64LE(offset)); offset += 8;
+    const createdAt = Number(data.readBigInt64LE(offset)); offset += 8;
+    const updatedAt = Number(data.readBigInt64LE(offset)); offset += 8;
+    const bump = data[offset]; offset += 1;
+    return {
+      agentIdHash: Array.from(agentIdHashBytes),
+      agentName, description, category, capabilities, metadataUri, faceImage,
+      faceMint: faceMint.toBase58(),
+      faceBurnTx,
+      genesisRecord,
+      isBorn: genesisRecord > 0,
+      authority: authority.toBase58(),
+      pendingAuthority,
+      reputationScore,
+      verificationLevel,
+      verificationLabel: ['Unverified','Registered','Verified','Established','Trusted','Sovereign'][verificationLevel] || 'Unknown',
+      reputationPct: (reputationScore / 10000).toFixed(2),
+      reputationUpdatedAt, verificationUpdatedAt,
+      createdAt: createdAt > 0 ? new Date(createdAt * 1000).toISOString() : null,
+      updatedAt: updatedAt > 0 ? new Date(updatedAt * 1000).toISOString() : null,
+      bump,
+    };
+  } catch (e) {
+    return { error: e.message, raw: data.toString('hex').slice(0, 200) };
+  }
+}
+
 module.exports = {
+  // V2 SDK (backward compatible — legacy, kept for escrow V2 / old paths)
   SATPSDK,
   getProgramIds,
   getIdentityPDA,
@@ -319,5 +885,81 @@ module.exports = {
   getReviewsAuthorityPDA,
   getReviewPDA,
   getReviewAttestationPDA,
+  getEscrowPDA,
+  getReviewV3PDA,
   anchorDiscriminator,
+
+  // V3 SDK (local extracted scaffold)
+  SATPV3SDK,
+  createSATPClient,
+  SatpV3Client: v3sdk.SATPV3SDK,
+  SatpV3Builders: v3sdk,
+
+  // V3 PDA derivation (local extracted scaffold)
+  PROGRAM_IDS: v3pda.getV3ProgramIds('devnet'),
+  getV3ProgramIds: v3pda.getV3ProgramIds,
+  hashAgentId: v3pda.hashAgentId,
+  agentIdHash: v3pda.hashAgentId,
+  hashName: v3pda.hashName,
+  getGenesisPDA: v3pda.getGenesisPDA,
+  deriveGenesisPda: v3pda.getGenesisPDA,
+  getV3ReputationAuthorityPDA: v3pda.getV3ReputationAuthorityPDA,
+  deriveReputationAuthorityPda: v3pda.getV3ReputationAuthorityPDA,
+  getV3ValidationAuthorityPDA: v3pda.getV3ValidationAuthorityPDA,
+  deriveValidationAuthorityPda: v3pda.getV3ValidationAuthorityPDA,
+  getV3MintTrackerPDA: v3pda.getV3MintTrackerPDA,
+  deriveMintTrackerPda: v3pda.getV3MintTrackerPDA,
+  getNameRegistryPDA: v3pda.getNameRegistryPDA,
+  deriveNameRegistryPda: v3pda.getNameRegistryPDA,
+  getLinkedWalletPDA: v3pda.getLinkedWalletPDA,
+  deriveLinkedWalletPda: v3pda.getLinkedWalletPDA,
+  getV3ReviewPDA: v3pda.getV3ReviewPDA,
+  deriveReviewPda: v3pda.getV3ReviewPDA,
+  getV3ReviewCounterPDA: v3pda.getV3ReviewCounterPDA,
+  deriveReviewCounterPda: v3pda.getV3ReviewCounterPDA,
+  getV3AttestationPDA: v3pda.getV3AttestationPDA,
+  deriveAttestationPda: v3pda.getV3AttestationPDA,
+  getV3EscrowPDA: v3pda.getV3EscrowPDA,
+  deriveEscrowPda: v3pda.getV3EscrowPDA,
+  deriveReviewAttestationPda: getReviewAttestationPDA,
+  prepareIdentityAttestationRequest,
+  TRUST_PACKET_SCHEMA_VERSION,
+  buildSatpTrustPacket,
+  validateSatpTrustPacket,
+
+  // V3 Deserialization (local extracted scaffold)
+  // NOTE: v3sdk.deserializeGenesis has isActive field mismatch with deployed program
+  // Using corrected manual parser until SDK v3.6+ fixes struct alignment
+  deserializeGenesis: _deserializeGenesisFixed,
+  deserializeGenesisRecord: _deserializeGenesisFixed, // alias for old name
+  deserializeLinkedWallet: v3Borsh.deserializeLinkedWallet,
+  deserializeMintTracker: v3Borsh.deserializeMintTracker,
+  deserializeNameRegistry: v3Borsh.deserializeNameRegistry,
+  deserializeReview: v3Borsh.deserializeReview,
+  deserializeReviewCounter: v3Borsh.deserializeReviewCounter,
+  deserializeAttestation: v3Borsh.deserializeAttestation,
+  deserializeEscrowV3: v3Borsh.deserializeEscrowV3,
+  tryDeserialize: v3Borsh.deserializeAccount,
+
+  // V3 Utilities
+  isBorn: v3sdk.isBorn,
+  trustTier: (score) => score >= 400 ? 'Sovereign' : score >= 200 ? 'Trusted' : score >= 100 ? 'Established' : score >= 50 ? 'Verified' : 'Unverified',
+  reputationPct: (score) => (Number(score || 0) / 10000).toFixed(2),
+  resolveAgent: (agentId, network = 'devnet') => v3pda.getGenesisPDA(agentId, network)[0],
+  verificationLabel: (level) => ['Unverified','Registered','Verified','Established','Trusted','Sovereign'][Number(level)] || 'Unknown',
+  attestationTypeLabel: (type) => String(type || '').replace(/_/g, ' '),
+  escrowStatusLabel: (status) => String(status || '').replace(/_/g, ' '),
+  isAttestationValid: (att) => !!att && !att.revoked && (!att.expiresAt || Number(att.expiresAt) > Math.floor(Date.now() / 1000)),
+  isEscrowExpired: (escrow) => !!escrow && !!escrow.expiresAt && Number(escrow.expiresAt) <= Math.floor(Date.now() / 1000),
+  escrowRemaining: (escrow) => escrow && escrow.expiresAt ? Math.max(0, Number(escrow.expiresAt) - Math.floor(Date.now() / 1000)) : null,
+  EscrowStatus: v3sdk.EscrowStatus,
+
+  // Legacy borsh (V2 compat only — prefer V3 deserializers above)
+  BorshReader: borshReader.BorshReader,
+  deserializeAccount: borshReader.deserializeAccount,
+  deserializeBatch: borshReader.deserializeBatch,
+  getAccountDiscriminator: borshReader.getAccountDiscriminator,
+  accountDiscriminator: borshReader.accountDiscriminator,
+  isAccountType: borshReader.isAccountType,
+  DISCRIMINATORS: borshReader.DISCRIMINATORS,
 };