{"_id":"@brainai/satp-v3","name":"@brainai/satp-v3","dist-tags":{"latest":"3.5.1"},"versions":{"3.5.1":{"name":"@brainai/satp-v3","version":"3.5.1","description":"Solana Agent Token Protocol V3 — TypeScript SDK for on-chain agent identity, reputation, validation, reviews, and attestations","main":"dist/index.js","module":"dist/index.mjs","types":"dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.js"},"./did":{"types":"./dist/did-resolver.d.ts","import":"./dist/did-resolver.mjs","require":"./dist/did-resolver.js"},"./builders":{"types":"./dist/builders.d.ts","import":"./dist/builders.mjs","require":"./dist/builders.js"},"./deserialize":{"types":"./dist/deserialize.d.ts","import":"./dist/deserialize.mjs","require":"./dist/deserialize.js"}},"scripts":{"build":"tsup src/index.ts src/did-resolver.ts src/builders.ts src/deserialize.ts --format cjs,esm --dts --clean","build:check":"tsc --noEmit","test":"npx ts-mocha -p ../tsconfig.json -t 30000 ../tests/sdk-v3-unit.ts","prepublishOnly":"npm run build"},"keywords":["solana","agent","identity","satp","web3","anchor","did","reputation","trust","brainai","agentfolio"],"author":{"name":"brainAI","email":"dev@brainai.bot"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/brainai/satp-v3.git"},"homepage":"https://agentfolio.bot","peerDependencies":{"@solana/web3.js":"^1.87.0"},"devDependencies":{"tsup":"^8.0.0","typescript":"^5.7.0"},"engines":{"node":">=18"},"_id":"@brainai/satp-v3@3.5.1","gitHead":"268a7a1f0d44bc318ab35cafcdbb862fbdd279fa","bugs":{"url":"https://github.com/brainai/satp-v3/issues"},"_nodeVersion":"22.22.0","_npmVersion":"10.9.4","dist":{"integrity":"sha512-+QPy2PfM8D5IYKz4jLGz7ALOpDTSufWB1r/yd0ggt1DAlLVkrt582sadPupcpXAZxdYQihI/q6DcicfmCnTnbw==","shasum":"3cc6e62db3aa3b7b1a3d68fa8bd33e71f3195f26","tarball":"https://registry.npmjs.org/@brainai/satp-v3/-/satp-v3-3.5.1.tgz","fileCount":22,"unpackedSize":256859,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIEwBap0N7K45iTcwkggqvfop9sLlZfD6KxLJjafP2aJvAiAsV4Mg97W9dkz+Rd47Z6NsNUHRTcfBoQlnOT3p+PruTw=="}]},"_npmUser":{"name":"brainai","email":"brainkid@brainai.bot"},"directories":{},"maintainers":[{"name":"brainai","email":"brainkid@brainai.bot"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/satp-v3_3.5.1_1774768096938_0.794834400007868"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-29T07:08:16.874Z","3.5.1":"2026-03-29T07:08:17.087Z","modified":"2026-03-29T07:08:17.300Z"},"maintainers":[{"name":"brainai","email":"brainkid@brainai.bot"}],"description":"Solana Agent Token Protocol V3 — TypeScript SDK for on-chain agent identity, reputation, validation, reviews, and attestations","homepage":"https://agentfolio.bot","keywords":["solana","agent","identity","satp","web3","anchor","did","reputation","trust","brainai","agentfolio"],"repository":{"type":"git","url":"git+https://github.com/brainai/satp-v3.git"},"author":{"name":"brainAI","email":"dev@brainai.bot"},"bugs":{"url":"https://github.com/brainai/satp-v3/issues"},"license":"MIT","readme":"# @brainai/satp-v3\n\n> Solana Agent Token Protocol V3 — TypeScript SDK\n\nOn-chain identity, reputation, reviews, attestations, and validation for AI agents on Solana.\n\n## Install\n\n```bash\nnpm install @brainai/satp-v3 @solana/web3.js\n```\n\n## Quick Start\n\n```typescript\nimport { SatpV3Client, resolveAgent, trustTier } from '@brainai/satp-v3';\n\n// Initialize client\nconst client = new SatpV3Client('https://api.devnet.solana.com');\n\n// Resolve agent → on-chain PDA\nconst pda = resolveAgent('agent_brainforge');\nconsole.log('PDA:', pda.toBase58());\n\n// Check if agent exists on-chain\nconst exists = await client.agentExists('agent_brainforge');\n\n// Get full agent summary\nconst summary = await client.getAgentSummary('agent_brainforge');\nconsole.log(summary);\n// { exists: true, pda: PublicKey, reviewCount: 3, linkedWalletCount: 1 }\n```\n\n## DID Resolution\n\n```typescript\nimport { resolveDid } from '@brainai/satp-v3/did';\n\nconst didDoc = await resolveDid('did:agentfolio:agent_brainforge', {\n  rpcUrl: 'https://api.devnet.solana.com'\n});\n```\n\n## PDA Derivation\n\nAll PDA seeds match the on-chain programs exactly:\n\n```typescript\nimport {\n  deriveGenesisPda,\n  deriveLinkedWalletPda,\n  deriveReviewPda,\n  deriveAttestationPda,\n  deriveNameRegistryPda,\n  deriveMintTrackerPda,\n  deriveReputationAuthorityPda,\n  deriveValidationAuthorityPda,\n} from '@brainai/satp-v3';\n\nconst [genesisPda, bump] = deriveGenesisPda('agent_brainforge');\nconst [namePda] = deriveNameRegistryPda('brainForge');\n```\n\n## Utilities\n\n```typescript\nimport {\n  reputationPct, verificationLabel, trustTier, isBorn,\n  isAttestationValid, attestationTypeLabel,\n  escrowStatusLabel, escrowRemaining, isEscrowExpired\n} from '@brainai/satp-v3';\n\n// Reputation score → percentage\nreputationPct(genesisRecord); // \"45.50\"\n\n// Verification level → label\nverificationLabel(3); // \"Enhanced\"\n\n// Trust tier from score\ntrustTier(350); // { tier: \"L4\", label: \"Established\" }\n\n// Attestation validation\nisAttestationValid(attestation); // true if verified + non-revoked + non-expired\nattestationTypeLabel(\"github\"); // \"GitHub Identity\"\n\n// Escrow utilities\nescrowStatusLabel(EscrowStatus.Active); // \"Active\"\nescrowRemaining(escrow); // lamports remaining\nisEscrowExpired(escrow); // true if past deadline\n```\n\n### Trust Profile (one call → full picture)\n\n```typescript\nconst profile = await client.getTrustProfile('agent_brainforge');\n// {\n//   exists: true,\n//   pda: PublicKey,\n//   verificationLevel: { level: 3, label: \"Enhanced\" },\n//   attestationSummary: { total: 5, verified: 4, valid: 3, uniqueTypes: [\"github\", \"kyc\"] },\n//   reviewCount: 12,\n//   linkedWalletCount: 2\n// }\n```\n\n## Transaction Builders (NEW in 3.5.0)\n\nBuild unsigned transactions for all SATP V3 instructions. Sign with any wallet adapter.\n\n```typescript\nimport { SatpV3Builders, LAMPORTS_PER_SOL } from '@brainai/satp-v3';\n\nconst builders = new SatpV3Builders('https://api.devnet.solana.com');\n\n// Create an agent identity\nconst tx = await builders.createIdentity({\n  agentId: 'agent_mybot',\n  name: 'MyBot',\n  description: 'An autonomous trading assistant',\n  category: 'finance',\n  capabilities: ['trading', 'analysis'],\n  metadataUri: 'https://example.com/meta.json',\n  creator: walletPublicKey,\n});\n// Sign and send: await connection.sendTransaction(tx, [walletKeypair]);\n\n// Create an escrow (client pays agent for work)\nconst { transaction, escrowPda, nonce } = await builders.createEscrow({\n  client: clientWallet,\n  agentWallet: agentWallet,\n  agentId: 'agent_mybot',\n  arbiter: arbiterWallet,\n  amount: 1_000_000_000n, // 1 SOL\n  description: 'Build a trading bot',\n  deadline: Math.floor(Date.now() / 1000) + 86400, // 24h\n});\n\n// Agent submits work proof\nconst submitTx = await builders.submitWork({\n  escrowPda,\n  agent: agentWallet,\n  workProof: 'https://github.com/org/repo/pull/42',\n});\n\n// Client releases funds\nconst releaseTx = await builders.releaseEscrow({\n  escrowPda,\n  client: clientWallet,\n  agent: agentWallet,\n});\n\n// Create a review\nconst reviewTx = await builders.createReview({\n  agentId: 'agent_mybot',\n  reviewer: reviewerWallet,\n  rating: 5,\n  reviewText: 'Excellent work, fast delivery!',\n});\n\n// Create an attestation (KYC, GitHub, etc.)\nconst attTx = await builders.createAttestation({\n  agentId: 'agent_mybot',\n  issuer: issuerWallet,\n  attestationType: 'github',\n  proofData: 'https://github.com/user',\n  expiresAt: Math.floor(Date.now() / 1000) + 365 * 86400, // 1 year\n});\n```\n\n### Builder Methods\n\n#### Identity Builders\n| Method | Description |\n|--------|-------------|\n| `createIdentity(params)` | Create new Genesis Record |\n| `updateIdentity(params)` | Update identity fields (null = no change) |\n| `burnToBecome(params)` | Activate via burn-to-become |\n| `linkWallet(params)` | Link external wallet |\n| `unlinkWallet(params)` | Unlink wallet |\n| `registerName(params)` | Register unique name |\n| `releaseName(params)` | Release registered name |\n| `initMintTracker(params)` | Initialize mint tracker |\n| `recordMint(params)` | Record mint event |\n| `proposeAuthority(params)` | Start authority transfer |\n| `acceptAuthority(params)` | Accept authority transfer |\n| `cancelAuthorityTransfer(params)` | Cancel pending transfer |\n| `deactivateIdentity(params)` | Deactivate identity |\n| `reactivateIdentity(params)` | Reactivate identity |\n\n#### Escrow Builders\n| Method | Description |\n|--------|-------------|\n| `createEscrow(params)` | Create escrow → returns `{transaction, escrowPda, nonce}` |\n| `submitWork(params)` | Submit work proof (string or 32-byte hash) |\n| `releaseEscrow(params)` | Release all funds to agent |\n| `partialRelease(params)` | Release partial amount (milestones) |\n| `cancelEscrow(params)` | Cancel (after deadline, no work submitted) |\n| `closeEscrow(params)` | Close settled escrow (returns rent) |\n| `extendDeadline(params)` | Extend escrow deadline |\n| `raiseDispute(params)` | Raise dispute (client or agent) |\n| `resolveDispute(params)` | Arbiter resolves dispute |\n\n#### Reviews Builders\n| Method | Description |\n|--------|-------------|\n| `initReviewCounter(params)` | Init counter (required before first review) |\n| `createReview(params)` | Create review (1-5 rating) |\n| `updateReview(params)` | Update review (optional fields) |\n| `deleteReview(params)` | Delete review |\n\n#### Attestation Builders\n| Method | Description |\n|--------|-------------|\n| `createAttestation(params)` | Create attestation |\n| `verifyAttestation(params)` | Mark as verified |\n| `revokeAttestation(params)` | Revoke attestation |\n\n## Programs\n\n| Program | Address |\n|---------|---------|\n| identity_v3 | `GTppU4E44BqXTQgbqMZ68ozFzhP1TLty3EGnzzjtNZfG` |\n| reviews_v3 | `r9XX4frcqxxAZ6Au9V5PA3EAxs1zoNckqLLmoSRcNr4` |\n| reputation_v3 | `2Lz7KzMvKdrGeAuS8WPHu7jK2yScrnKVgacpYVEuDjkJ` |\n| attestations_v3 | `6Xd1dAQJPvQRJ4Ntr6LtPTjDjPUZ8nfnmYLZaZ2DtrdD` |\n| validation_v3 | `6rYRiCYidJYV7QvKrzKGgNu4oMh6BAvynked69R7xMbV` |\n| escrow_v3 | `HXCUWKR2NvRcZ7rNAJHwPcH6QAAWaLR4bRFbfyuDND6C` |\n\n## API Reference\n\n### Client Methods\n\n#### Identity\n| Method | Returns | Description |\n|--------|---------|-------------|\n| `getGenesis(agentId)` | `{pda, data} \\| null` | Fetch raw Genesis Record |\n| `agentExists(agentId)` | `boolean` | Check if agent is on-chain |\n| `getNameRegistry(name)` | `{pda, data} \\| null` | Look up name registration |\n| `isNameTaken(name)` | `boolean` | Check name availability |\n| `getMintTracker(agentId)` | `{pda, data} \\| null` | Get mint tracker |\n| `getLinkedWallets(agentId)` | `[{pubkey, data}]` | All linked wallets |\n| `getAgentSummary(agentId)` | `{exists, pda, reviewCount, linkedWalletCount}` | Full summary |\n\n#### Reviews\n| Method | Returns | Description |\n|--------|---------|-------------|\n| `getReviewCount(agentId)` | `number \\| null` | Total review count |\n| `getReviews(agentId)` | `[{pubkey, data}]` | All reviews |\n\n#### Attestations (NEW in 3.4.0)\n| Method | Returns | Description |\n|--------|---------|-------------|\n| `getAttestation(pda)` | `{pda, data} \\| null` | Fetch attestation by PDA |\n| `getAttestationByParams(agentId, issuer, type)` | `{pda, data} \\| null` | Fetch by known parameters |\n| `getAttestationsByAgent(agentId)` | `[{pubkey, data}]` | All attestations for an agent |\n| `getAttestationsByIssuer(issuer)` | `[{pubkey, data}]` | All attestations by an issuer |\n| `getAttestationSummary(agentId)` | `{total, verified, valid, uniqueTypes, typeCounts}` | Attestation breakdown |\n\n#### Validation (NEW in 3.4.0)\n| Method | Returns | Description |\n|--------|---------|-------------|\n| `getVerificationLevel(agentId)` | `{level, label} \\| null` | Current verification level |\n| `getTrustProfile(agentId)` | `{exists, verificationLevel, attestationSummary, reviewCount, ...}` | Complete trust profile |\n\n#### Escrow\n| Method | Returns | Description |\n|--------|---------|-------------|\n| `getEscrow(pda)` | `{pda, data} \\| null` | Fetch escrow by PDA |\n| `getEscrowByParams(client, description, nonce)` | `{pda, data} \\| null` | Fetch by parameters |\n| `getEscrowsByClient(client)` | `[{pubkey, data}]` | All escrows by client |\n| `getEscrowsByAgent(agent)` | `[{pubkey, data}]` | All escrows for agent wallet |\n| `getEscrowsByAgentId(agentId)` | `[{pubkey, data}]` | All escrows by agent ID |\n\n### PDA Functions\n\n| Function | Seeds | Program |\n|----------|-------|---------|\n| `deriveGenesisPda(agentId)` | `[\"genesis\", sha256(agentId)]` | identity |\n| `deriveLinkedWalletPda(genesis, wallet)` | `[\"linked_wallet\", genesis, wallet]` | identity |\n| `deriveNameRegistryPda(name)` | `[\"name_registry\", sha256(lower(name))]` | identity |\n| `deriveMintTrackerPda(genesis)` | `[\"mint_tracker\", genesis]` | identity |\n| `deriveReviewPda(agentId, reviewer)` | `[\"review_v3\", sha256(agentId), reviewer]` | reviews |\n| `deriveReviewCounterPda(agentId)` | `[\"review_counter_v3\", sha256(agentId)]` | reviews |\n| `deriveAttestationPda(agentId, issuer, type)` | `[\"attestation_v3\", sha256(agentId), issuer, type]` | attestations |\n| `deriveReputationAuthorityPda()` | `[\"reputation_v3_authority\"]` | reputation |\n| `deriveValidationAuthorityPda()` | `[\"validation_v3_authority\"]` | validation |\n| `deriveEscrowPda(client, descHash, nonce)` | `[\"escrow_v3\", client, descHash, nonce]` | escrow |\n\n## Borsh Deserializers (NEW in 3.5.0)\n\nParse raw on-chain account data into typed TypeScript objects:\n\n```typescript\nimport {\n  deserializeGenesis,\n  deserializeLinkedWallet,\n  deserializeReview,\n  deserializeAttestation,\n  deserializeEscrow,\n  tryDeserialize,\n} from '@brainai/satp-v3';\n\n// Fetch raw data and deserialize\nconst raw = await client.getGenesis('agent_brainforge');\nif (raw) {\n  const genesis = deserializeGenesis(raw.data);\n  console.log(genesis.agentName);         // \"brainForge\"\n  console.log(genesis.verificationLevel); // 3\n  console.log(genesis.isActive);          // true\n}\n\n// Batch-safe: tryDeserialize returns null instead of throwing\nconst reviews = await client.getReviews('agent_brainforge');\nconst parsed = reviews\n  .map(r => tryDeserialize(deserializeReview, r.data))\n  .filter(Boolean);\n```\n\n### Deserializer Functions\n\n| Function | Returns | Source Program |\n|----------|---------|----------------|\n| `deserializeGenesis(data)` | `GenesisRecord` | identity_v3 |\n| `deserializeLinkedWallet(data)` | `LinkedWallet` | identity_v3 |\n| `deserializeNameRegistry(data)` | `NameRegistry` | identity_v3 |\n| `deserializeMintTracker(data)` | `MintTracker` | identity_v3 |\n| `deserializeReview(data)` | `ReviewV3` | reviews_v3 |\n| `deserializeReviewCounter(data)` | `ReviewCounterV3` | reviews_v3 |\n| `deserializeAttestation(data)` | `AttestationV3` | attestations_v3 |\n| `deserializeEscrow(data)` | `EscrowV3` | escrow_v3 |\n| `tryDeserialize(fn, data)` | `T \\| null` | (wrapper) |\n\n## License\n\nMIT © brainAI\n","readmeFilename":"README.md","_rev":"1-29e10dfc51956c75e0f364af249281f8"}