@brainai/satp-client 2.0.0

package/README.md

@@ -0,0 +1,82 @@
+# SATP JavaScript SDK
+
+Lightweight SDK for interacting with SATP (Solana Agent Token Protocol) programs on Solana.
+
+## Install
+
+```bash
+cd satp-sdk && npm install
+```
+
+## Quick Start
+
+```js
+const { SATPSDK } = require('./src');
+
+const sdk = new SATPSDK(); // mainnet by default
+// const sdk = new SATPSDK({ rpcUrl: 'https://api.devnet.solana.com' });
+
+// Check if an agent is registered
+const verified = await sdk.verifyAgent('SomeWalletPubkey...');
+
+// Get identity data
+const identity = await sdk.getIdentity('SomeWalletPubkey...');
+
+// Get reputation
+const rep = await sdk.getReputation('SomeWalletPubkey...');
+
+// Derive PDAs (offline, no RPC)
+const pdas = sdk.getPDAs('SomeWalletPubkey...');
+```
+
+## Write Operations (require a signer)
+
+```js
+const { Keypair } = require('@solana/web3.js');
+
+const signer = Keypair.fromSecretKey(/* your key */);
+
+// Register identity
+const sig = await sdk.registerIdentity(signer, 'my-agent', { type: 'ai', version: '1.0' });
+
+// Add reputation (endorser signs)
+const sig2 = await sdk.addReputation(endorserKeypair, targetWallet, 100);
+```
+
+## Transaction Builders (for wallet adapters / frontends)
+
+```js
+// Get unsigned transaction for frontend signing
+const { transaction, identityPDA } = await sdk.buildRegisterIdentity(
+  walletPublicKey, 'agent-name', { metadata: true }
+);
+// Sign with wallet adapter, then send
+```
+
+## API
+
+| Method | Type | Description |
+|--------|------|-------------|
+| `getIdentity(wallet)` | Read | Fetch identity data (or null) |
+| `getReputation(wallet)` | Read | Fetch reputation data (or null) |
+| `verifyAgent(wallet)` | Read | Check if wallet has SATP identity |
+| `getPDAs(wallet)` | Offline | Derive identity + reputation PDAs |
+| `registerIdentity(signer, name, metadata)` | Write | Register on-chain identity |
+| `addReputation(endorser, target, score)` | Write | Add reputation score |
+| `buildRegisterIdentity(wallet, name, meta)` | Builder | Unsigned tx for frontends |
+| `buildAddReputation(wallet, score, endorser)` | Builder | Unsigned tx for frontends |
+
+## Program IDs (Mainnet)
+
+| Program | Address |
+|---------|---------|
+| Identity | `BY4jzmnrui1K5gZ5z5xRQkVfEEMXYHYugtH1Ua867eyr` |
+| Reputation | `TQ4P9R2Y5FRyw1TZfwoWQ2Mf6XeohbGdhYNcDxh6YYh` |
+| Validation | `AdDWFa9oEmZdrTrhu8YTWu4ozbTP7e6qa9rvyqfAvM7N` |
+| Escrow | `STyY8w4ZHws3X1AMoocWuDYBoogVDwvymPy8Wifx5TH` |
+
+## Notes
+
+- Account schemas are best-guess based on Anchor conventions. Once we have the actual IDLs, we can generate exact schemas.
+- Write operations require SOL for transaction fees + rent.
+- Always test on devnet first: `new SATPSDK({ rpcUrl: 'https://api.devnet.solana.com' })`

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@brainai/satp-client",
+  "version": "2.0.0",
+  "description": "SATP v2 Client SDK — Solana Agent Token Protocol (Identity, Reviews, Reputation, Attestations, Validation)",
+  "main": "src/index.js",
+  "files": [
+    "src/",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node test.js"
+  },
+  "keywords": [
+    "solana",
+    "satp",
+    "agent",
+    "identity",
+    "reputation",
+    "blockchain",
+    "web3"
+  ],
+  "author": "brainAI",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/brainai-dev/satp-client"
+  },
+  "homepage": "https://agentfolio.bot",
+  "dependencies": {
+    "@solana/web3.js": "^1.98.4",
+    "borsh": "^2.0.0",
+    "bs58": "^6.0.0"
+  }
+}

package/src/constants.js

@@ -0,0 +1,67 @@
+const { PublicKey } = require('@solana/web3.js');
+
+// SATP v2 Program IDs — Devnet
+const DEVNET_PROGRAM_IDS = {
+  IDENTITY: new PublicKey('EJtQh4Gyg88zXvSmFpxYkkeZsPwTsjfm4LvjmPQX1FD3'),
+  REVIEWS: new PublicKey('D8HsSpK3JtAN7tVcA1yfgxScju7KcG6skEfaShSKojki'),
+  REPUTATION: new PublicKey('4y4W2Mdfpu91C4iVowiDyJTmdKSjo8bmSDQrX2c84WQF'),
+  ATTESTATIONS: new PublicKey('9xT3eNcndkmnqZtJqDQ1ggckHK7Dxo5EsAt5mHqsPBhP'),
+  VALIDATION: new PublicKey('8jLaqodAzfM7oCxP7aedFeszeNjnJ5ik56dzhDU2HQgc'),
+};
+
+// SATP v2 Program IDs — Mainnet
+const MAINNET_PROGRAM_IDS = {
+  IDENTITY: new PublicKey('97yL33fcu6iWT2TdERS5HeqrMSGiUnxuy6nUcTrKieSq'),
+  REVIEWS: new PublicKey('Ge1sD2qwmH8QaaKCPZzZERvsFXNVMvKbAgTp2p17yjLK'),
+  REPUTATION: new PublicKey('C9ogv8TBrvFy4pLKDoGQg9B73Q5rKPPsQ4kzkcDk6Jd'),
+  ATTESTATIONS: new PublicKey('ENvaD19QzwWWMJFu5r5xJ9SmHqWN6GvyzxACRejqbdug'),
+  VALIDATION: new PublicKey('9p795d2j3eGqzborG2AncucWBaU6PieKxmhKVroV3LNh'),
+};
+
+const MAINNET_RPC = 'https://api.mainnet-beta.solana.com';
+const DEVNET_RPC = 'https://api.devnet.solana.com';
+
+// PDA seeds (must match on-chain programs)
+const IDENTITY_SEED = 'identity';
+const REPUTATION_AUTHORITY_SEED = 'reputation_authority';
+const VALIDATION_AUTHORITY_SEED = 'validation_authority';
+const REVIEW_COUNTER_SEED = 'review_counter';
+const MINT_TRACKER_SEED = 'mint_tracker';
+const REVIEWS_AUTHORITY_SEED = 'reviews_authority';
+const ATTESTATION_SEED = 'attestation';
+const REVIEW_SEED = 'review';
+
+/**
+ * Get program IDs for a given network.
+ * @param {'mainnet'|'devnet'} network
+ * @returns {object} Program ID map
+ */
+function getProgramIds(network = 'devnet') {
+  return network === 'mainnet' ? MAINNET_PROGRAM_IDS : DEVNET_PROGRAM_IDS;
+}
+
+/**
+ * Get RPC URL for a given network.
+ * @param {'mainnet'|'devnet'} network
+ * @returns {string} RPC URL
+ */
+function getRpcUrl(network = 'devnet') {
+  return network === 'mainnet' ? MAINNET_RPC : DEVNET_RPC;
+}
+
+module.exports = {
+  DEVNET_PROGRAM_IDS,
+  MAINNET_PROGRAM_IDS,
+  getProgramIds,
+  getRpcUrl,
+  MAINNET_RPC,
+  DEVNET_RPC,
+  IDENTITY_SEED,
+  REPUTATION_AUTHORITY_SEED,
+  VALIDATION_AUTHORITY_SEED,
+  REVIEW_COUNTER_SEED,
+  MINT_TRACKER_SEED,
+  REVIEWS_AUTHORITY_SEED,
+  ATTESTATION_SEED,
+  REVIEW_SEED,
+};

package/src/index.js

@@ -0,0 +1,323 @@
+const {
+  Connection,
+  PublicKey,
+  Transaction,
+  TransactionInstruction,
+  SystemProgram,
+} = require('@solana/web3.js');
+const borsh = require('borsh');
+const { getProgramIds, getRpcUrl } = require('./constants');
+const {
+  getIdentityPDA,
+  getReputationAuthorityPDA,
+  getValidationAuthorityPDA,
+  getReviewCounterPDA,
+  getMintTrackerPDA,
+  getReviewsAuthorityPDA,
+  getReviewPDA,
+  getReviewAttestationPDA,
+} = require('./pda');
+const {
+  IdentityAccount, IDENTITY_SCHEMA,
+  ReputationAccount, REPUTATION_SCHEMA,
+} = require('./schema');
+const crypto = require('crypto');
+
+/**
+ * Compute Anchor instruction discriminator.
+ * @param {string} ixName - e.g. "create_identity"
+ * @returns {Buffer} 8-byte discriminator
+ */
+function anchorDiscriminator(ixName) {
+  return crypto.createHash('sha256')
+    .update(`global:${ixName}`)
+    .digest()
+    .slice(0, 8);
+}
+
+class SATPSDK {
+  /**
+   * @param {object} opts
+   * @param {'mainnet'|'devnet'} [opts.network='devnet'] - Network selection
+   * @param {string} [opts.rpcUrl] - Custom RPC endpoint (overrides network default)
+   * @param {string} [opts.commitment='confirmed'] - Commitment level
+   */
+  constructor(opts = {}) {
+    this.network = opts.network || 'devnet';
+    this.rpcUrl = opts.rpcUrl || getRpcUrl(this.network);
+    this.commitment = opts.commitment || 'confirmed';
+    this.connection = new Connection(this.rpcUrl, this.commitment);
+    this.programIds = getProgramIds(this.network);
+  }
+
+  // ─── Identity ──────────────────────────────────────────
+
+  /**
+   * Build a createIdentity transaction.
+   * @param {PublicKey|string} wallet - Owner wallet (signer)
+   * @param {string} agentName
+   * @param {string|object} metadata - JSON string or object
+   * @returns {{ transaction: Transaction, identityPDA: PublicKey }}
+   */
+  async buildCreateIdentity(wallet, agentName, metadata) {
+    const walletKey = new PublicKey(wallet);
+    const [identityPDA] = getIdentityPDA(walletKey, this.network);
+    const metaStr = typeof metadata === 'object' ? JSON.stringify(metadata) : metadata;
+
+    const disc = anchorDiscriminator('create_identity');
+    const nameBytes = Buffer.from(agentName, 'utf8');
+    const metaBytes = Buffer.from(metaStr, 'utf8');
+
+    const data = Buffer.concat([
+      disc,
+      Buffer.from(new Uint32Array([nameBytes.length]).buffer),
+      nameBytes,
+      Buffer.from(new Uint32Array([metaBytes.length]).buffer),
+      metaBytes,
+    ]);
+
+    const ix = new TransactionInstruction({
+      programId: this.programIds.IDENTITY,
+      keys: [
+        { pubkey: walletKey, isSigner: true, isWritable: true },
+        { pubkey: identityPDA, isSigner: false, isWritable: true },
+        { pubkey: SystemProgram.programId, isSigner: false, isWritable: false },
+      ],
+      data,
+    });
+
+    const tx = new Transaction().add(ix);
+    tx.feePayer = walletKey;
+    tx.recentBlockhash = (await this.connection.getLatestBlockhash()).blockhash;
+
+    return { transaction: tx, identityPDA };
+  }
+
+  /**
+   * Create an identity on-chain (requires a Keypair signer).
+   */
+  async createIdentity(signer, agentName, metadata) {
+    const { transaction } = await this.buildCreateIdentity(signer.publicKey, agentName, metadata);
+    const sig = await this.connection.sendTransaction(transaction, [signer]);
+    await this.connection.confirmTransaction(sig, this.commitment);
+    return sig;
+  }
+
+  /**
+   * Fetch identity data for a wallet. Returns null if not found.
+   */
+  async getIdentity(wallet) {
+    const [pda] = getIdentityPDA(new PublicKey(wallet), this.network);
+    const acct = await this.connection.getAccountInfo(pda);
+    if (!acct) return null;
+
+    try {
+      const decoded = borsh.deserialize(IDENTITY_SCHEMA, IdentityAccount, acct.data);
+      return {
+        owner: new PublicKey(decoded.owner).toBase58(),
+        agentName: decoded.agentName,
+        metadata: decoded.metadata,
+        createdAt: Number(decoded.createdAt),
+        updatedAt: Number(decoded.updatedAt),
+        pda: pda.toBase58(),
+      };
+    } catch (e) {
+      return { pda: pda.toBase58(), raw: acct.data.toString('hex'), error: e.message };
+    }
+  }
+
+  // ─── Reputation (v2 CPI-based recompute) ───────────────
+
+  /**
+   * Build a recomputeReputation transaction.
+   * This is permissionless — anyone can call it to recompute an agent's score.
+   * The Reputation program CPIs into Identity to update the score.
+   *
+   * @param {PublicKey|string} agentWallet - Agent whose reputation to recompute
+   * @param {PublicKey|string} payer - Transaction fee payer (signer)
+   * @returns {{ transaction: Transaction }}
+   */
+  async buildRecomputeReputation(agentWallet, payer) {
+    const agentKey = new PublicKey(agentWallet);
+    const payerKey = new PublicKey(payer);
+    const [identityPDA] = getIdentityPDA(agentKey, this.network);
+    const [repAuthority] = getReputationAuthorityPDA(this.network);
+    const [reviewCounter] = getReviewCounterPDA(agentKey, this.network);
+
+    const disc = anchorDiscriminator('recompute_reputation');
+
+    const ix = new TransactionInstruction({
+      programId: this.programIds.REPUTATION,
+      keys: [
+        { pubkey: payerKey, isSigner: true, isWritable: true },
+        { pubkey: identityPDA, isSigner: false, isWritable: true },
+        { pubkey: reviewCounter, isSigner: false, isWritable: false },
+        { pubkey: repAuthority, isSigner: false, isWritable: false },
+        { pubkey: this.programIds.IDENTITY, isSigner: false, isWritable: false },
+      ],
+      data: disc,
+    });
+
+    const tx = new Transaction().add(ix);
+    tx.feePayer = payerKey;
+    tx.recentBlockhash = (await this.connection.getLatestBlockhash()).blockhash;
+
+    return { transaction: tx };
+  }
+
+  /**
+   * Trigger reputation recompute (permissionless).
+   */
+  async recomputeReputation(signerKeypair, agentWallet) {
+    const { transaction } = await this.buildRecomputeReputation(agentWallet, signerKeypair.publicKey);
+    const sig = await this.connection.sendTransaction(transaction, [signerKeypair]);
+    await this.connection.confirmTransaction(sig, this.commitment);
+    return sig;
+  }
+
+  /**
+   * Fetch reputation data for a wallet.
+   */
+  async getReputation(wallet) {
+    const [pda] = getIdentityPDA(new PublicKey(wallet), this.network);
+    const acct = await this.connection.getAccountInfo(pda);
+    if (!acct) return null;
+
+    try {
+      const decoded = borsh.deserialize(IDENTITY_SCHEMA, IdentityAccount, acct.data);
+      return {
+        owner: new PublicKey(decoded.owner).toBase58(),
+        agentName: decoded.agentName,
+        reputationScore: decoded.reputationScore || 0,
+        verificationLevel: decoded.verificationLevel || 0,
+        pda: pda.toBase58(),
+      };
+    } catch (e) {
+      return { pda: pda.toBase58(), raw: acct.data.toString('hex'), error: e.message };
+    }
+  }
+
+  // ─── Validation (v2 CPI-based recompute) ───────────────
+
+  /**
+   * Build a recomputeLevel transaction.
+   * Permissionless — recomputes verification level based on attestation count.
+   *
+   * @param {PublicKey|string} agentWallet - Agent whose level to recompute
+   * @param {PublicKey|string} payer - Transaction fee payer
+   * @returns {{ transaction: Transaction }}
+   */
+  async buildRecomputeLevel(agentWallet, payer) {
+    const agentKey = new PublicKey(agentWallet);
+    const payerKey = new PublicKey(payer);
+    const [identityPDA] = getIdentityPDA(agentKey, this.network);
+    const [valAuthority] = getValidationAuthorityPDA(this.network);
+
+    const disc = anchorDiscriminator('recompute_level');
+
+    const ix = new TransactionInstruction({
+      programId: this.programIds.VALIDATION,
+      keys: [
+        { pubkey: payerKey, isSigner: true, isWritable: true },
+        { pubkey: identityPDA, isSigner: false, isWritable: true },
+        { pubkey: valAuthority, isSigner: false, isWritable: false },
+        { pubkey: this.programIds.IDENTITY, isSigner: false, isWritable: false },
+      ],
+      data: disc,
+    });
+
+    const tx = new Transaction().add(ix);
+    tx.feePayer = payerKey;
+    tx.recentBlockhash = (await this.connection.getLatestBlockhash()).blockhash;
+
+    return { transaction: tx };
+  }
+
+  /**
+   * Trigger verification level recompute (permissionless).
+   */
+  async recomputeLevel(signerKeypair, agentWallet) {
+    const { transaction } = await this.buildRecomputeLevel(agentWallet, signerKeypair.publicKey);
+    const sig = await this.connection.sendTransaction(transaction, [signerKeypair]);
+    await this.connection.confirmTransaction(sig, this.commitment);
+    return sig;
+  }
+
+  // ─── MintTracker ───────────────────────────────────────
+
+  /**
+   * Build initMintTracker transaction.
+   * @param {PublicKey|string} wallet - Identity owner
+   * @returns {{ transaction: Transaction, mintTrackerPDA: PublicKey }}
+   */
+  async buildInitMintTracker(wallet) {
+    const walletKey = new PublicKey(wallet);
+    const [identityPDA] = getIdentityPDA(walletKey, this.network);
+    const [mintTrackerPDA] = getMintTrackerPDA(identityPDA, this.network);
+
+    const disc = anchorDiscriminator('init_mint_tracker');
+
+    const ix = new TransactionInstruction({
+      programId: this.programIds.IDENTITY,
+      keys: [
+        { pubkey: walletKey, isSigner: true, isWritable: true },
+        { pubkey: identityPDA, isSigner: false, isWritable: false },
+        { pubkey: mintTrackerPDA, isSigner: false, isWritable: true },
+        { pubkey: SystemProgram.programId, isSigner: false, isWritable: false },
+      ],
+      data: disc,
+    });
+
+    const tx = new Transaction().add(ix);
+    tx.feePayer = walletKey;
+    tx.recentBlockhash = (await this.connection.getLatestBlockhash()).blockhash;
+
+    return { transaction: tx, mintTrackerPDA };
+  }
+
+  // ─── Verification ──────────────────────────────────────
+
+  /**
+   * Check if a wallet has a registered SATP identity.
+   */
+  async verifyAgent(wallet) {
+    const identity = await this.getIdentity(wallet);
+    return identity !== null && !identity.error;
+  }
+
+  // ─── Utility ───────────────────────────────────────────
+
+  /**
+   * Derive all PDAs for a wallet without RPC calls.
+   */
+  getPDAs(wallet) {
+    const walletKey = new PublicKey(wallet);
+    const [identityPDA] = getIdentityPDA(walletKey, this.network);
+    const [reviewCounter] = getReviewCounterPDA(walletKey, this.network);
+    const [mintTracker] = getMintTrackerPDA(identityPDA, this.network);
+    const [repAuthority] = getReputationAuthorityPDA(this.network);
+    const [valAuthority] = getValidationAuthorityPDA(this.network);
+
+    return {
+      identity: identityPDA.toBase58(),
+      reviewCounter: reviewCounter.toBase58(),
+      mintTracker: mintTracker.toBase58(),
+      reputationAuthority: repAuthority.toBase58(),
+      validationAuthority: valAuthority.toBase58(),
+    };
+  }
+}
+
+module.exports = {
+  SATPSDK,
+  getProgramIds,
+  getIdentityPDA,
+  getReputationAuthorityPDA,
+  getValidationAuthorityPDA,
+  getReviewCounterPDA,
+  getMintTrackerPDA,
+  getReviewsAuthorityPDA,
+  getReviewPDA,
+  getReviewAttestationPDA,
+  anchorDiscriminator,
+};

package/src/pda.js

@@ -0,0 +1,148 @@
+const { PublicKey } = require('@solana/web3.js');
+const {
+  getProgramIds,
+  IDENTITY_SEED,
+  REPUTATION_AUTHORITY_SEED,
+  VALIDATION_AUTHORITY_SEED,
+  REVIEW_COUNTER_SEED,
+  MINT_TRACKER_SEED,
+  REVIEWS_AUTHORITY_SEED,
+  ATTESTATION_SEED,
+  REVIEW_SEED,
+} = require('./constants');
+
+/**
+ * Derive the Identity PDA for a wallet.
+ * Seeds: ["identity", wallet_pubkey]
+ * @param {PublicKey|string} wallet
+ * @param {'mainnet'|'devnet'} network
+ */
+function getIdentityPDA(wallet, network = 'devnet') {
+  const walletKey = new PublicKey(wallet);
+  const programIds = getProgramIds(network);
+  return PublicKey.findProgramAddressSync(
+    [Buffer.from(IDENTITY_SEED), walletKey.toBuffer()],
+    programIds.IDENTITY
+  );
+}
+
+/**
+ * Derive the Reputation Authority PDA (program signer for CPI).
+ * Seeds: ["reputation_authority"]
+ * @param {'mainnet'|'devnet'} network
+ */
+function getReputationAuthorityPDA(network = 'devnet') {
+  const programIds = getProgramIds(network);
+  return PublicKey.findProgramAddressSync(
+    [Buffer.from(REPUTATION_AUTHORITY_SEED)],
+    programIds.REPUTATION
+  );
+}
+
+/**
+ * Derive the Validation Authority PDA (program signer for CPI).
+ * Seeds: ["validation_authority"]
+ * @param {'mainnet'|'devnet'} network
+ */
+function getValidationAuthorityPDA(network = 'devnet') {
+  const programIds = getProgramIds(network);
+  return PublicKey.findProgramAddressSync(
+    [Buffer.from(VALIDATION_AUTHORITY_SEED)],
+    programIds.VALIDATION
+  );
+}
+
+/**
+ * Derive the Review Counter PDA for an agent.
+ * Seeds: ["review_counter", agent_id]
+ * @param {PublicKey|string} agentId
+ * @param {'mainnet'|'devnet'} network
+ */
+function getReviewCounterPDA(agentId, network = 'devnet') {
+  const agentKey = new PublicKey(agentId);
+  const programIds = getProgramIds(network);
+  return PublicKey.findProgramAddressSync(
+    [Buffer.from(REVIEW_COUNTER_SEED), agentKey.toBuffer()],
+    programIds.REVIEWS
+  );
+}
+
+/**
+ * Derive the MintTracker PDA for an identity.
+ * Seeds: ["mint_tracker", identity_pda]
+ * @param {PublicKey|string} identityPDA
+ * @param {'mainnet'|'devnet'} network
+ */
+function getMintTrackerPDA(identityPDA, network = 'devnet') {
+  const identityKey = new PublicKey(identityPDA);
+  const programIds = getProgramIds(network);
+  return PublicKey.findProgramAddressSync(
+    [Buffer.from(MINT_TRACKER_SEED), identityKey.toBuffer()],
+    programIds.IDENTITY
+  );
+}
+
+/**
+ * Derive the Reviews Authority PDA (program signer for CPI into Attestations).
+ * Seeds: ["reviews_authority"]
+ * @param {'mainnet'|'devnet'} network
+ */
+function getReviewsAuthorityPDA(network = 'devnet') {
+  const programIds = getProgramIds(network);
+  return PublicKey.findProgramAddressSync(
+    [Buffer.from(REVIEWS_AUTHORITY_SEED)],
+    programIds.REVIEWS
+  );
+}
+
+/**
+ * Derive the Review PDA for a specific reviewer + agent pair.
+ * Seeds: ["review", agent_id, reviewer]
+ * @param {PublicKey|string} agentId
+ * @param {PublicKey|string} reviewer
+ * @param {'mainnet'|'devnet'} network
+ */
+function getReviewPDA(agentId, reviewer, network = 'devnet') {
+  const agentKey = new PublicKey(agentId);
+  const reviewerKey = new PublicKey(reviewer);
+  const programIds = getProgramIds(network);
+  return PublicKey.findProgramAddressSync(
+    [Buffer.from(REVIEW_SEED), agentKey.toBuffer(), reviewerKey.toBuffer()],
+    programIds.REVIEWS
+  );
+}
+
+/**
+ * Derive the Review Attestation PDA (auto-created via CPI when a review is submitted).
+ * Seeds: ["attestation", agent_id, reviews_authority, "review", reviewer]
+ * @param {PublicKey|string} agentId
+ * @param {PublicKey} reviewsAuthority - Use getReviewsAuthorityPDA() to derive
+ * @param {PublicKey|string} reviewer
+ * @param {'mainnet'|'devnet'} network
+ */
+function getReviewAttestationPDA(agentId, reviewsAuthority, reviewer, network = 'devnet') {
+  const agentKey = new PublicKey(agentId);
+  const reviewerKey = new PublicKey(reviewer);
+  const programIds = getProgramIds(network);
+  return PublicKey.findProgramAddressSync(
+    [
+      Buffer.from(ATTESTATION_SEED),
+      agentKey.toBuffer(),
+      reviewsAuthority.toBuffer(),
+      Buffer.from(REVIEW_SEED),
+      reviewerKey.toBuffer(),
+    ],
+    programIds.ATTESTATIONS
+  );
+}
+
+module.exports = {
+  getIdentityPDA,
+  getReputationAuthorityPDA,
+  getValidationAuthorityPDA,
+  getReviewCounterPDA,
+  getMintTrackerPDA,
+  getReviewsAuthorityPDA,
+  getReviewPDA,
+  getReviewAttestationPDA,
+};

package/src/schema.js

@@ -0,0 +1,59 @@
+const borsh = require('borsh');
+
+// ---- Identity Account Schema ----
+class IdentityAccount {
+  constructor(fields) {
+    this.discriminator = fields.discriminator; // 8 bytes (Anchor)
+    this.owner = fields.owner;                 // 32 bytes pubkey
+    this.agentName = fields.agentName;         // string
+    this.metadata = fields.metadata;           // string (JSON)
+    this.createdAt = fields.createdAt;         // i64 timestamp
+    this.updatedAt = fields.updatedAt;         // i64 timestamp
+    this.bump = fields.bump;                   // u8
+  }
+}
+
+const IDENTITY_SCHEMA = new Map([
+  [IdentityAccount, {
+    kind: 'struct',
+    fields: [
+      ['discriminator', [8]],
+      ['owner', [32]],
+      ['agentName', 'string'],
+      ['metadata', 'string'],
+      ['createdAt', 'u64'],
+      ['updatedAt', 'u64'],
+      ['bump', 'u8'],
+    ],
+  }],
+]);
+
+// ---- Reputation Account Schema ----
+class ReputationAccount {
+  constructor(fields) {
+    this.discriminator = fields.discriminator;
+    this.owner = fields.owner;
+    this.score = fields.score;               // u64
+    this.endorsements = fields.endorsements; // u32 count
+    this.lastEndorser = fields.lastEndorser; // 32 bytes pubkey
+    this.updatedAt = fields.updatedAt;
+    this.bump = fields.bump;
+  }
+}
+
+const REPUTATION_SCHEMA = new Map([
+  [ReputationAccount, {
+    kind: 'struct',
+    fields: [
+      ['discriminator', [8]],
+      ['owner', [32]],
+      ['score', 'u64'],
+      ['endorsements', 'u32'],
+      ['lastEndorser', [32]],
+      ['updatedAt', 'u64'],
+      ['bump', 'u8'],
+    ],
+  }],
+]);
+
+module.exports = { IdentityAccount, IDENTITY_SCHEMA, ReputationAccount, REPUTATION_SCHEMA };