@brainai/satp-client 2.0.0 → 2.0.1

package/src/pda.js

@@ -9,6 +9,7 @@ const {
   REVIEWS_AUTHORITY_SEED,
   ATTESTATION_SEED,
   REVIEW_SEED,
+  ESCROW_SEED,
 } = require('./constants');
 
 /**
@@ -136,6 +137,46 @@ function getReviewAttestationPDA(agentId, reviewsAuthority, reviewer, network =
   );
 }
 
+/**
+ * Derive the Escrow PDA for a client + description_hash pair.
+ * Seeds: ["escrow", client_pubkey, description_hash]
+ * @param {PublicKey|string} client - Client wallet
+ * @param {Buffer|number[]} descriptionHash - 32-byte SHA256 hash of job description
+ * @param {'mainnet'|'devnet'} network
+ */
+function getEscrowPDA(client, descriptionHash, network = 'devnet') {
+  const clientKey = new PublicKey(client);
+  const hashBuf = Buffer.isBuffer(descriptionHash)
+    ? descriptionHash
+    : Buffer.from(descriptionHash);
+  const programIds = getProgramIds(network);
+  if (!programIds.ESCROW) {
+    throw new Error('SATP v2 mainnet escrow program ID is not configured; pass devnet or wait for an approved mainnet escrow deployment');
+  }
+  return PublicKey.findProgramAddressSync(
+    [Buffer.from(ESCROW_SEED), clientKey.toBuffer(), hashBuf],
+    programIds.ESCROW
+  );
+}
+
+/**
+ * Derive the Review V3 PDA (job-scoped reviews).
+ * Seeds: ["review", job_pubkey, reviewer_pubkey]
+ * @param {PublicKey|string} jobPDA - Job/Escrow account pubkey
+ * @param {PublicKey|string} reviewer - Reviewer wallet
+ * @param {'mainnet'|'devnet'} network
+ */
+function getReviewV3PDA(jobPDA, reviewer, network = 'devnet') {
+  const jobKey = new PublicKey(jobPDA);
+  const reviewerKey = new PublicKey(reviewer);
+  const programIds = getProgramIds(network);
+  // Reviews V3 uses the same REVIEWS program ID
+  return PublicKey.findProgramAddressSync(
+    [Buffer.from(REVIEW_SEED), jobKey.toBuffer(), reviewerKey.toBuffer()],
+    programIds.REVIEWS
+  );
+}
+
 module.exports = {
   getIdentityPDA,
   getReputationAuthorityPDA,
@@ -145,4 +186,6 @@ module.exports = {
   getReviewsAuthorityPDA,
   getReviewPDA,
   getReviewAttestationPDA,
+  getEscrowPDA,
+  getReviewV3PDA,
 };

package/src/trust-packet.js

@@ -0,0 +1,148 @@
+'use strict';
+
+const { prepareIdentityAttestationRequest } = require('./attestation-request');
+
+const TRUST_PACKET_SCHEMA_VERSION = 'satp.trustPacket.v1';
+
+function canonicalStringify(value) {
+  if (Array.isArray(value)) {
+    return '[' + value.map(canonicalStringify).join(',') + ']';
+  }
+  if (value && typeof value === 'object') {
+    return '{' + Object.keys(value).sort().map((key) => JSON.stringify(key) + ':' + canonicalStringify(value[key])).join(',') + '}';
+  }
+  return JSON.stringify(value);
+}
+
+function sameJsonValue(left, right) {
+  return canonicalStringify(left) === canonicalStringify(right);
+}
+
+/**
+ * Build a deterministic, read-only SATP trust packet for consumer preflight.
+ *
+ * The packet wraps the unsigned identity-attestation request with the derived
+ * program IDs, Genesis PDA, attestation PDA, request hash, and explicit flags
+ * proving that no signer, transaction, instruction, RPC write, or payment is
+ * required to consume it.
+ */
+function buildSatpTrustPacket(opts = {}) {
+  const request = prepareIdentityAttestationRequest(opts);
+  return {
+    schemaVersion: TRUST_PACKET_SCHEMA_VERSION,
+    packetType: 'satp-trust-packet',
+    mode: 'offline-readonly-trust-packet',
+    network: request.network,
+    subjectWallet: request.subjectWallet,
+    agentId: request.agentId,
+    claimType: request.claimType,
+    attestationType: request.attestationType,
+    metadataHash: request.metadataHash,
+    attester: request.attester,
+    expiresAt: request.expiresAt,
+    programs: { ...request.programs },
+    pda: {
+      genesis: request.genesisPda,
+      genesisBump: request.genesisBump,
+      attestation: request.attestationPda,
+      attestationBump: request.attestationBump,
+    },
+    requestHash: request.requestHash,
+    flags: {
+      signingRequired: false,
+      transactionRequired: false,
+      writesRequired: false,
+      livePaymentRequired: false,
+      unsigned: true,
+      noSign: true,
+      noTransaction: true,
+    },
+    instructions: [],
+    signers: [],
+    transaction: null,
+    request,
+  };
+}
+
+function validateSatpTrustPacket(packet) {
+  const errors = [];
+  if (!packet || typeof packet !== 'object') {
+    return { ok: false, errors: ['packet must be an object'] };
+  }
+
+  if (packet.schemaVersion !== TRUST_PACKET_SCHEMA_VERSION) {
+    errors.push('schemaVersion must be ' + TRUST_PACKET_SCHEMA_VERSION);
+  }
+  if (packet.packetType !== 'satp-trust-packet') {
+    errors.push('packetType must be satp-trust-packet');
+  }
+  if (packet.mode !== 'offline-readonly-trust-packet') {
+    errors.push('mode must be offline-readonly-trust-packet');
+  }
+
+  const expectedFlags = {
+    signingRequired: false,
+    transactionRequired: false,
+    writesRequired: false,
+    livePaymentRequired: false,
+    unsigned: true,
+    noSign: true,
+    noTransaction: true,
+  };
+  if (!sameJsonValue(packet.flags, expectedFlags)) {
+    errors.push('flags must be read-only, unsigned, and no-transaction');
+  }
+  if (!Array.isArray(packet.instructions) || packet.instructions.length !== 0) {
+    errors.push('instructions must be an empty array');
+  }
+  if (!Array.isArray(packet.signers) || packet.signers.length !== 0) {
+    errors.push('signers must be an empty array');
+  }
+  if (packet.transaction !== null) {
+    errors.push('transaction must be null');
+  }
+
+  let expected;
+  try {
+    expected = buildSatpTrustPacket({
+      subjectWallet: packet.subjectWallet,
+      agentId: packet.agentId,
+      claimType: packet.claimType || packet.attestationType,
+      metadataHash: packet.metadataHash,
+      attester: packet.attester,
+      network: packet.network,
+      expiresAt: packet.expiresAt,
+    });
+  } catch (err) {
+    errors.push('packet cannot be re-derived: ' + err.message);
+    return { ok: false, errors };
+  }
+
+  const fields = [
+    'network',
+    'subjectWallet',
+    'agentId',
+    'claimType',
+    'attestationType',
+    'metadataHash',
+    'attester',
+    'expiresAt',
+    'programs',
+    'pda',
+    'requestHash',
+    'request',
+  ];
+  for (const field of fields) {
+    if (!sameJsonValue(packet[field], expected[field])) {
+      errors.push(field + ' does not match derived trust packet');
+    }
+  }
+
+  return { ok: errors.length === 0, errors };
+}
+
+module.exports = {
+  TRUST_PACKET_SCHEMA_VERSION,
+  buildSatpTrustPacket,
+  validateSatpTrustPacket,
+};

package/src/v3-pda.d.ts

@@ -0,0 +1,72 @@
+import { PublicKey } from '@solana/web3.js';
+
+export type Network = 'mainnet' | 'devnet';
+
+export interface V3ProgramIds {
+  IDENTITY: PublicKey;
+  REVIEWS: PublicKey;
+  REPUTATION: PublicKey;
+  ATTESTATIONS: PublicKey;
+  VALIDATION: PublicKey;
+  ESCROW: PublicKey;
+}
+
+/** Get all V3 program IDs for a network. */
+export function getV3ProgramIds(network?: Network): V3ProgramIds;
+
+/** SHA-256 hash of agent ID string. Returns 32-byte Buffer. */
+export function hashAgentId(agentId: string): Buffer;
+
+/** SHA-256 hash of lowercased name string. Returns 32-byte Buffer. */
+export function hashName(name: string): Buffer;
+
+/** Derive Genesis PDA from agent ID hash. */
+export function getGenesisPDA(agentIdHash: string | Buffer, network?: Network): [PublicKey, number];
+
+/** Derive Reputation V3 Authority PDA. */
+export function getV3ReputationAuthorityPDA(network?: Network): [PublicKey, number];
+
+/** Derive Validation V3 Authority PDA. */
+export function getV3ValidationAuthorityPDA(network?: Network): [PublicKey, number];
+
+/** Derive MintTracker PDA from Genesis PDA. */
+export function getV3MintTrackerPDA(genesisPDA: PublicKey | string, network?: Network): [PublicKey, number];
+
+/** Derive NameRegistry PDA from name hash. */
+export function getNameRegistryPDA(nameHash: string | Buffer, network?: Network): [PublicKey, number];
+
+/** Derive LinkedWallet PDA from Genesis PDA and wallet. */
+export function getLinkedWalletPDA(
+  genesisPDA: PublicKey | string,
+  wallet: PublicKey | string,
+  network?: Network
+): [PublicKey, number];
+
+/** Derive Review V3 PDA from job account and reviewer. */
+export function getV3ReviewPDA(
+  jobPDA: PublicKey | string,
+  reviewer: PublicKey | string,
+  network?: Network
+): [PublicKey, number];
+
+/** Derive Attestation PDA from agent ID hash, attester, and type. */
+export function getV3AttestationPDA(
+  agentIdHash: string | Buffer,
+  attester: PublicKey | string,
+  attestationType: string,
+  network?: Network
+): [PublicKey, number];
+
+/** Derive Review Counter PDA from agent ID. */
+export function getV3ReviewCounterPDA(
+  agentIdOrHash: string | Buffer,
+  network?: Network
+): [PublicKey, number];
+
+/** Derive Escrow V3 PDA from client, description hash, and nonce. */
+export function getV3EscrowPDA(
+  client: PublicKey | string,
+  descriptionHash: Buffer,
+  nonce: number | bigint,
+  network?: Network
+): [PublicKey, number];

package/src/v3-pda.js

@@ -0,0 +1,281 @@
+const { PublicKey } = require('@solana/web3.js');
+const crypto = require('crypto');
+
+// ═══════════════════════════════════════════════════
+//  SATP V3 Program IDs — Devnet
+// ═══════════════════════════════════════════════════
+
+const V3_DEVNET_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('HXCUWKR2NvRcZ7rNAJHwPcH6QAAWaLR4bRFbfyuDND6C'),
+};
+
+const V3_MAINNET_PROGRAM_IDS = null;
+
+// ═══════════════════════════════════════════════════
+//  V3 PDA Seeds — must match on-chain programs
+// ═══════════════════════════════════════════════════
+
+const V3_SEEDS = {
+  GENESIS: 'genesis',
+  REPUTATION_AUTHORITY: 'reputation_v3_authority',
+  VALIDATION_AUTHORITY: 'validation_v3_authority',
+  MINT_TRACKER: 'mint_tracker',
+  NAME_REGISTRY: 'name_registry',
+  LINKED_WALLET: 'linked_wallet',
+  REVIEW: 'review_v3',
+  REVIEW_COUNTER: 'review_counter_v3',
+  ATTESTATION: 'attestation_v3',
+  ESCROW_V3: 'escrow_v3',
+};
+
+// ═══════════════════════════════════════════════════
+//  V3 Program ID Getter
+// ═══════════════════════════════════════════════════
+
+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;
+}
+
+// ═══════════════════════════════════════════════════
+//  Utility: Hash agent_id to 32-byte seed
+// ═══════════════════════════════════════════════════
+
+/**
+ * Hash an agent_id string to 32-byte SHA-256 (matches on-chain solana_program::hash::hash).
+ * @param {string} agentId - Agent identifier string
+ * @returns {Buffer} 32-byte hash
+ */
+function hashAgentId(agentId) {
+  return crypto.createHash('sha256').update(agentId, 'utf8').digest();
+}
+
+/**
+ * Hash a name (lowercased) for name registry PDA.
+ * @param {string} name
+ * @returns {Buffer} 32-byte SHA-256 hash
+ */
+function hashName(name) {
+  return crypto.createHash('sha256').update(name.toLowerCase(), 'utf8').digest();
+}
+
+// ═══════════════════════════════════════════════════
+//  V3 PDA Derivation Functions
+// ═══════════════════════════════════════════════════
+
+/**
+ * Derive Genesis Record PDA.
+ * Seeds: ["genesis", agent_id_hash]
+ * @param {string|Buffer} agentIdOrHash - agent_id string or 32-byte hash
+ * @param {'mainnet'|'devnet'} network
+ * @returns {[PublicKey, number]} [pda, bump]
+ */
+function getGenesisPDA(agentIdOrHash, network = 'devnet') {
+  const hash = typeof agentIdOrHash === 'string'
+    ? hashAgentId(agentIdOrHash)
+    : Buffer.from(agentIdOrHash);
+  const programIds = getV3ProgramIds(network);
+  return PublicKey.findProgramAddressSync(
+    [Buffer.from(V3_SEEDS.GENESIS), hash],
+    programIds.IDENTITY
+  );
+}
+
+/**
+ * Derive Reputation V3 Authority PDA (CPI signer).
+ * Seeds: ["reputation_v3_authority"]
+ * @param {'mainnet'|'devnet'} network
+ * @returns {[PublicKey, number]}
+ */
+function getV3ReputationAuthorityPDA(network = 'devnet') {
+  const programIds = getV3ProgramIds(network);
+  return PublicKey.findProgramAddressSync(
+    [Buffer.from(V3_SEEDS.REPUTATION_AUTHORITY)],
+    programIds.REPUTATION
+  );
+}
+
+/**
+ * Derive Validation V3 Authority PDA (CPI signer).
+ * Seeds: ["validation_v3_authority"]
+ * @param {'mainnet'|'devnet'} network
+ * @returns {[PublicKey, number]}
+ */
+function getV3ValidationAuthorityPDA(network = 'devnet') {
+  const programIds = getV3ProgramIds(network);
+  return PublicKey.findProgramAddressSync(
+    [Buffer.from(V3_SEEDS.VALIDATION_AUTHORITY)],
+    programIds.VALIDATION
+  );
+}
+
+/**
+ * Derive MintTracker PDA.
+ * Seeds: ["mint_tracker", genesis_pda]
+ * @param {PublicKey|string} genesisPDA
+ * @param {'mainnet'|'devnet'} network
+ * @returns {[PublicKey, number]}
+ */
+function getV3MintTrackerPDA(genesisPDA, network = 'devnet') {
+  const genesisKey = new PublicKey(genesisPDA);
+  const programIds = getV3ProgramIds(network);
+  return PublicKey.findProgramAddressSync(
+    [Buffer.from(V3_SEEDS.MINT_TRACKER), genesisKey.toBuffer()],
+    programIds.IDENTITY
+  );
+}
+
+/**
+ * Derive Name Registry PDA.
+ * Seeds: ["name_registry", name_hash]
+ * @param {string|Buffer} nameOrHash - Display name string or 32-byte hash
+ * @param {'mainnet'|'devnet'} network
+ * @returns {[PublicKey, number]}
+ */
+function getNameRegistryPDA(nameOrHash, network = 'devnet') {
+  const hash = typeof nameOrHash === 'string'
+    ? hashName(nameOrHash)
+    : Buffer.from(nameOrHash);
+  const programIds = getV3ProgramIds(network);
+  return PublicKey.findProgramAddressSync(
+    [Buffer.from(V3_SEEDS.NAME_REGISTRY), hash],
+    programIds.IDENTITY
+  );
+}
+
+/**
+ * Derive Linked Wallet PDA.
+ * Seeds: ["linked_wallet", genesis_pda, wallet]
+ * @param {PublicKey|string} genesisPDA
+ * @param {PublicKey|string} wallet
+ * @param {'mainnet'|'devnet'} network
+ * @returns {[PublicKey, number]}
+ */
+function getLinkedWalletPDA(genesisPDA, wallet, network = 'devnet') {
+  const genesisKey = new PublicKey(genesisPDA);
+  const walletKey = new PublicKey(wallet);
+  const programIds = getV3ProgramIds(network);
+  return PublicKey.findProgramAddressSync(
+    [Buffer.from(V3_SEEDS.LINKED_WALLET), genesisKey.toBuffer(), walletKey.toBuffer()],
+    programIds.IDENTITY
+  );
+}
+
+/**
+ * Derive V3 Review PDA (agent-scoped).
+ * Seeds: ["review_v3", SHA256(agent_id), reviewer]
+ * @param {string|Buffer} agentIdOrHash - agent_id string or 32-byte hash
+ * @param {PublicKey|string} reviewer
+ * @param {'mainnet'|'devnet'} network
+ * @returns {[PublicKey, number]}
+ */
+function getV3ReviewPDA(agentIdOrHash, reviewer, network = 'devnet') {
+  const hash = typeof agentIdOrHash === 'string'
+    ? hashAgentId(agentIdOrHash)
+    : Buffer.from(agentIdOrHash);
+  const reviewerKey = new PublicKey(reviewer);
+  const programIds = getV3ProgramIds(network);
+  return PublicKey.findProgramAddressSync(
+    [Buffer.from(V3_SEEDS.REVIEW), hash, reviewerKey.toBuffer()],
+    programIds.REVIEWS
+  );
+}
+
+/**
+ * Derive V3 Review Counter PDA.
+ * Seeds: ["review_counter_v3", SHA256(agent_id)]
+ * @param {string|Buffer} agentIdOrHash - agent_id string or 32-byte hash
+ * @param {'mainnet'|'devnet'} network
+ * @returns {[PublicKey, number]}
+ */
+function getV3ReviewCounterPDA(agentIdOrHash, network = 'devnet') {
+  const hash = typeof agentIdOrHash === 'string'
+    ? hashAgentId(agentIdOrHash)
+    : Buffer.from(agentIdOrHash);
+  const programIds = getV3ProgramIds(network);
+  return PublicKey.findProgramAddressSync(
+    [Buffer.from(V3_SEEDS.REVIEW_COUNTER), hash],
+    programIds.REVIEWS
+  );
+}
+
+/**
+ * Derive V3 Attestation PDA.
+ * Seeds: ["attestation", agent_id_hash, attester, attestation_type]
+ * @param {string|Buffer} agentIdOrHash
+ * @param {PublicKey|string} attester
+ * @param {string} attestationType
+ * @param {'mainnet'|'devnet'} network
+ * @returns {[PublicKey, number]}
+ */
+function getV3AttestationPDA(agentIdOrHash, attester, attestationType, network = 'devnet') {
+  const hash = typeof agentIdOrHash === 'string'
+    ? hashAgentId(agentIdOrHash)
+    : Buffer.from(agentIdOrHash);
+  const attesterKey = new PublicKey(attester);
+  const programIds = getV3ProgramIds(network);
+  return PublicKey.findProgramAddressSync(
+    [
+      Buffer.from(V3_SEEDS.ATTESTATION),
+      hash,
+      attesterKey.toBuffer(),
+      Buffer.from(attestationType, 'utf8'),
+    ],
+    programIds.ATTESTATIONS
+  );
+}
+
+/**
+ * Derive Escrow V3 PDA.
+ * Seeds: ["escrow_v3", client, description_hash, nonce_le_bytes]
+ * @param {PublicKey|string} client - Client wallet
+ * @param {Buffer} descriptionHash - 32-byte SHA-256 of job description
+ * @param {number|bigint} nonce - Unique nonce (u64)
+ * @param {'mainnet'|'devnet'} network
+ * @returns {[PublicKey, number]}
+ */
+function getV3EscrowPDA(client, descriptionHash, nonce, network = 'devnet') {
+  const clientKey = new PublicKey(client);
+  const hashBuf = Buffer.isBuffer(descriptionHash) ? descriptionHash : Buffer.from(descriptionHash);
+  const nonceBuf = Buffer.alloc(8);
+  nonceBuf.writeBigUInt64LE(BigInt(nonce));
+  const programIds = getV3ProgramIds(network);
+  return PublicKey.findProgramAddressSync(
+    [Buffer.from(V3_SEEDS.ESCROW_V3), clientKey.toBuffer(), hashBuf, nonceBuf],
+    programIds.ESCROW
+  );
+}
+
+module.exports = {
+  // Program IDs
+  V3_DEVNET_PROGRAM_IDS,
+  V3_MAINNET_PROGRAM_IDS,
+  getV3ProgramIds,
+  V3_SEEDS,
+
+  // Utilities
+  hashAgentId,
+  hashName,
+
+  // PDA derivation
+  getGenesisPDA,
+  getV3ReputationAuthorityPDA,
+  getV3ValidationAuthorityPDA,
+  getV3MintTrackerPDA,
+  getNameRegistryPDA,
+  getLinkedWalletPDA,
+  getV3ReviewPDA,
+  getV3ReviewCounterPDA,
+  getV3AttestationPDA,
+  getV3EscrowPDA,
+};