@brainai/satp-client 2.0.4 → 2.0.6

package/README.md

@@ -3,7 +3,7 @@
 **Solana Agent Trust Protocol** - JavaScript/TypeScript SDK for reading and
 building reviewed SATP V3 program interactions.
 
-Current stable npm package: **@brainai/satp-client@2.0.3** | rc dist-tag: **@brainai/satp-client@2.0.2** | Programs: **6**
+Current stable npm package: **@brainai/satp-client@2.0.5** | unpublished source candidate: **@brainai/satp-client@2.0.6** | rc dist-tag: **@brainai/satp-client@2.0.2** | Programs: **6**
 
 ## Installation
 
@@ -11,20 +11,25 @@ Choose stable, rc, or Git based on what the consumer needs to prove:
 
 | Channel | Use when | Command |
 | --- | --- | --- |
-| Stable npm | Default production-style consumption of the stable public package. | `npm install @brainai/satp-client@2.0.3` |
+| Stable npm | Default production-style consumption of the stable public package. | `npm install @brainai/satp-client@2.0.5` |
 | Historical rc exact version | Explicit HQ-assigned reproduction or lockfile evidence for the historical pre-stable artifact. | `npm install @brainai/satp-client@2.0.2` |
 | Release candidate tag | Explicit HQ-assigned rc validation where a moving dist-tag is acceptable and the task names the tag as the target. | `npm install @brainai/satp-client@rc` |
 | Reviewed Git commit | PR coordination or source-review installs tied to an exact SATP commit. | `npm install git+https://github.com/brainAI-bot/satp.git#<SATP_COMMIT>` |
 
-Registry readback on 2026-07-26 shows npm `latest` resolves to
-`@brainai/satp-client@2.0.3` and the `rc` dist-tag resolves to `2.0.2`.
-Stable consumers should use `latest`/`2.0.3` unless HQ assigns an explicit
+Registry readback on 2026-07-31 shows npm `latest` resolves to
+`@brainai/satp-client@2.0.5` and the `rc` dist-tag resolves to `2.0.2`.
+Stable consumers should use `latest`/`2.0.5` unless HQ assigns an explicit
 release-candidate validation task.
 
+Source release-prep on 2026-08-02 advances package metadata to `2.0.6` as the
+next unpublished stable semver candidate because npm `latest` is already
+`2.0.5` and npm package versions are immutable. This does not publish the
+package or move any npm dist-tag.
+
 For stable consumer installs, pin the current published npm package:
 
 ```bash
-npm install @brainai/satp-client@2.0.3
+npm install @brainai/satp-client@2.0.5
 ```
 
 For rc validation:
@@ -56,6 +61,10 @@ a separate HQ approval and the relevant owner-gated runbook. See
 `docs/mainnet-authority-decision-packet-6c8a5545.md` for the public authority
 decision packet.
 
+Legacy `SATPSDK` is V2-only compatibility. It defaults to devnet and rejects
+`network: 'mainnet'` unless `allowLegacyV2Mainnet: true` is passed explicitly.
+New integrations should prefer `SATPV3SDK` or `createSATPClient`.
+
 RC-S6 semantic uncertainty outcomes are covered by the offline conformance gate
 merged in `93db1b3` (PR #53, `[#43394290]`) and runnable with
 `npm run test:conformance:rc-s6` from the repository root. Treat positive
@@ -73,6 +82,13 @@ For the root consumer quickstart covering stable npm, rc validation, Git-review
 pins, read-only trust packets, conformance checks, and network boundaries, see
 [`docs/quickstart.md`](../../docs/quickstart.md).
 
+For copy-paste MCP, A2A/agent-runtime, and x402 paid-endpoint examples, see
+[`docs/adoption-quickstarts.md`](../../docs/adoption-quickstarts.md) or run:
+
+```bash
+node packages/satp-client/examples/adoption-quickstarts.js
+```
+
 ```javascript
 const { SATPV3SDK } = require('@brainai/satp-client');
 
@@ -116,14 +132,14 @@ const tx = await sdk.buildCreateIdentity(creatorPubkey, 'myAgent', {
 
 ## Programs & Program IDs
 
-| Program | Devnet | Description |
+| Program | Mainnet | Description |
 |---------|--------|-------------|
 | `identity_v3` | `GTppU4E44BqXTQgbqMZ68ozFzhP1TLty3EGnzzjtNZfG` | Agent identity, names, wallets, face/birth |
 | `reviews_v3` | `r9XX4frcqxxAZ6Au9V5PA3EAxs1zoNckqLLmoSRcNr4` | Peer reviews with 1-5 star ratings |
 | `attestations_v3` | `6Xd1dAQJPvQRJ4Ntr6LtPTjDjPUZ8nfnmYLZaZ2DtrdD` | Third-party attestations & proofs |
 | `reputation_v3` | `2Lz7KzMvKdrGeAuS8WPHu7jK2yScrnKVgacpYVEuDjkJ` | Weighted reputation scoring (CPI → identity) |
 | `validation_v3` | `6rYRiCYidJYV7QvKrzKGgNu4oMh6BAvynked69R7xMbV` | Validation level computation (CPI → identity) |
-| `escrow_v3` | `B1Se8SPx7GLUisa4LYeXY1tDZy5TviJrsV2yMLgqUXmg` | SOL escrow for agent jobs |
+| `escrow_v3` | `HXCUWKR2NvRcZ7rNAJHwPcH6QAAWaLR4bRFbfyuDND6C` | SOL escrow for agent jobs |
 
 ## API Reference
 
@@ -183,6 +199,15 @@ builds a runtime policy action descriptor. It asserts
 `paymentAuthorization: false`, `actionAuthorization: false`,
 `spendAuthorized: false`, and `livePaymentRequired: false`.
 
+The proposed issue #14 Track C endpoint spec for third-party SATP reputation
+and evidence consumers lives in
+[`docs/x402-reputation-evidence-lookup-api.md`](../../docs/x402-reputation-evidence-lookup-api.md).
+Its companion offline caller example is runnable with:
+
+```bash
+node packages/satp-client/examples/x402-reputation-evidence-lookup-client.js
+```
+
 ### Runtime Policy Adapter Helper
 
 `createRuntimePolicyAdapter(opts)` provides a host-oriented wrapper around the
@@ -541,6 +566,10 @@ const genesis = deserializeGenesisRecord(acct.data);
 console.log(genesis.agentName, genesis.reputationScore, genesis.isBorn);
 ```
 
+Genesis parsing is layout-aware for RC-S6 review. Parsed records include
+`layout` and `hasIsActiveField`; `isActive` is `null` when the account bytes do
+not carry the historical `is_active` field.
+
 ### Usage: Auto-detect Account Type
 
 ```js

package/examples/adoption-quickstarts.js

@@ -0,0 +1,173 @@
+#!/usr/bin/env node
+'use strict';
+
+const {
+  buildRuntimePolicyActionDescriptorFromX402Discovery,
+  buildSatpTrustPacket,
+  createRuntimePolicyAdapter,
+  getV3ProgramIds,
+  validateSatpTrustPacket,
+} = require('../src');
+
+const METADATA_HASH = '93d122f8879fe87c186c10a00db8fbc80a73cecd2ede44b9ffa6410be3c2b805';
+
+async function mcpToolServerQuickstart() {
+  function createSatpMcpTools() {
+    return {
+      'satp.getPrograms': async ({ network = 'devnet' } = {}) => ({
+        network,
+        programs: getV3ProgramIds(network),
+        guardrails: {
+          readOnly: true,
+          writesSolanaState: false,
+          usesKeypairs: false,
+        },
+      }),
+
+      'satp.prepareAttestationRequest': async ({
+        subjectWallet,
+        agentId,
+        claimType = 'identity',
+        metadataHash,
+        network = 'devnet',
+      }) => {
+        const packet = buildSatpTrustPacket({
+          subjectWallet,
+          agentId,
+          claimType,
+          metadataHash,
+          network,
+        });
+        const validation = validateSatpTrustPacket(packet);
+        if (!validation.ok) throw new Error(validation.errors.join('; '));
+
+        return {
+          packet,
+          guardrails: {
+            readOnly: true,
+            livePaymentRequired: false,
+            transaction: null,
+          },
+        };
+      },
+    };
+  }
+
+  const tools = createSatpMcpTools();
+  const prepared = await tools['satp.prepareAttestationRequest']({
+    subjectWallet: '11111111111111111111111111111111',
+    agentId: 'example-mcp-agent',
+    metadataHash: METADATA_HASH,
+  });
+  return {
+    audience: 'mcp-tool-server-builders',
+    mode: prepared.packet.mode,
+    guardrails: prepared.guardrails,
+  };
+}
+
+function agentRuntimeQuickstart() {
+  const now = new Date().toISOString();
+  const adapter = createRuntimePolicyAdapter({
+    policy: {
+      minimumTrustScore: 70,
+      denyTrustScoreBelow: 25,
+      requireVerifiedIdentity: true,
+      maxAutoSpendUsd: 0,
+    },
+  });
+  const identity = {
+    agentId: 'partner-runtime-agent',
+    active: true,
+    satpVerified: true,
+    trustScore: 82,
+    capabilities: ['a2a:task.delegate'],
+    evidenceUpdatedAt: now,
+  };
+  const action = adapter.action({
+    type: 'a2a_agent_runtime',
+    resource: 'a2a://task/delegate',
+    operation: 'delegate',
+    capability: 'a2a:task.delegate',
+    requiresFreshEvidence: true,
+    operatorApprovalRequired: false,
+  });
+  const result = adapter.evaluate(identity, action, { now });
+  const auditTrace = adapter.auditTrace(identity, action, { result, now });
+
+  return {
+    audience: 'a2a-agent-runtime-builders',
+    decision: result.decision,
+    reasonCodes: result.reasonCodes,
+    localDecisionOnly: auditTrace.guardrails.localDecisionOnly,
+  };
+}
+
+function x402PaidEndpointQuickstart() {
+  const discovery = {
+    endpoint: 'https://api.example.test/satp/reputation',
+    action: 'lookup',
+    accepts: [{
+      scheme: 'exact',
+      network: 'solana-mainnet',
+      asset: 'USDC',
+      maxAmountRequired: '10000',
+      resource: 'https://api.example.test/satp/reputation',
+      description: 'SATP-backed reputation evidence lookup',
+    }],
+  };
+  const lookupAction = buildRuntimePolicyActionDescriptorFromX402Discovery(
+    discovery,
+    { maxCostUsd: 0.01 }
+  );
+  const adapter = createRuntimePolicyAdapter({
+    policy: { maxAutoSpendUsd: 0, minimumTrustScore: 70 },
+  });
+  const identity = {
+    agentId: 'x402-consumer-agent',
+    active: true,
+    satpVerified: true,
+    trustScore: 90,
+    capabilities: ['satp:evidence.lookup'],
+    evidenceUpdatedAt: '2026-05-21T00:00:00Z',
+  };
+  const result = adapter.evaluate(identity, lookupAction, {
+    evidenceLookupPaymentPreapproved: false,
+    now: '2026-07-31T00:00:00Z',
+  });
+
+  return {
+    audience: 'x402-paid-endpoint-builders',
+    decision: result.decision,
+    reasonCodes: result.reasonCodes,
+    guardrail: lookupAction.evidenceLookup.guardrail,
+    paymentBoundary: {
+      satpPackageUseIsFreeOpen: true,
+      x402OnlyForHostedReputationEvidenceLookup: true,
+      paymentIsNotActionAuthorization: true,
+      livePaymentRequired: false,
+    },
+  };
+}
+
+async function run() {
+  const examples = [
+    await mcpToolServerQuickstart(),
+    agentRuntimeQuickstart(),
+    x402PaidEndpointQuickstart(),
+  ];
+  console.log(JSON.stringify({ examples }, null, 2));
+}
+
+if (require.main === module) {
+  run().catch((err) => {
+    console.error(err);
+    process.exitCode = 1;
+  });
+}
+
+module.exports = {
+  agentRuntimeQuickstart,
+  mcpToolServerQuickstart,
+  x402PaidEndpointQuickstart,
+};

package/examples/runtime-policy-adapter.js

@@ -44,7 +44,7 @@ const examples = [
     },
   },
   {
-    name: 'Host trust-score degrade',
+    name: 'AgentFolio trust-score degrade',
     identity: { ...trustedIdentity, trustScore: 62 },
     action: buildRuntimePolicyActionDescriptor({
       type: 'agentfolio_trust_gate',
@@ -55,6 +55,18 @@ const examples = [
       now: '2026-05-21T00:00:00Z',
     },
   },
+  {
+    name: 'Host trust-score gate alias',
+    identity: { ...trustedIdentity, trustScore: 74 },
+    action: buildRuntimePolicyActionDescriptor({
+      type: 'host_trust_gate',
+      profileId: 'brainchain-demo',
+      minimumTrustScore: 80,
+    }),
+    options: {
+      now: '2026-05-21T00:00:00Z',
+    },
+  },
   {
     name: 'Optional paid x402 evidence lookup',
     identity: { ...trustedIdentity, evidenceUpdatedAt: '2026-04-01T00:00:00Z' },

package/examples/x402-reputation-evidence-lookup-client.js

@@ -0,0 +1,182 @@
+#!/usr/bin/env node
+'use strict';
+
+const assert = require('node:assert/strict');
+const {
+  X402_PAYMENT_IS_NOT_ACTION_AUTHORIZATION,
+  buildRuntimePolicyActionDescriptorFromX402Discovery,
+} = require('../src');
+
+const LOOKUP_SCHEMA_VERSION = 'satp.x402ReputationEvidenceLookup.v1';
+
+const discoveryMetadata = {
+  schemaVersion: 'satp.x402DiscoveryMetadata.v1',
+  protocol: 'x402',
+  action: 'satp.reputationEvidence.lookup',
+  endpoint: 'https://satp-provider.example/v1/satp/evidence/reputation',
+  resource: 'satp://evidence/reputation',
+  paymentRequired: true,
+  accepts: [
+    {
+      scheme: 'exact',
+      network: '<provider-selected-payment-network>',
+      asset: '<provider-selected-asset>',
+      payTo: '<provider-controlled-recipient>',
+      maxAmountRequired: '<provider-disclosed-maximum>',
+      resource: 'https://satp-provider.example/v1/satp/evidence/reputation',
+      description: 'Read-only SATP reputation evidence lookup',
+      mimeType: 'application/json',
+      maxTimeoutSeconds: 60,
+    },
+  ],
+  guardrail: X402_PAYMENT_IS_NOT_ACTION_AUTHORIZATION,
+};
+
+function buildLookupUrl(endpoint, request) {
+  const url = new URL(endpoint);
+  if (request.agentId) url.searchParams.set('agentId', request.agentId);
+  if (request.wallet) url.searchParams.set('wallet', request.wallet);
+  if (request.network) url.searchParams.set('network', request.network);
+  if (request.include) url.searchParams.set('include', request.include.join(','));
+  if (request.minEvidenceUpdatedAt) url.searchParams.set('minEvidenceUpdatedAt', request.minEvidenceUpdatedAt);
+  if (request.trace) url.searchParams.set('trace', request.trace);
+  return url;
+}
+
+function assertLookupBoundary(body) {
+  assert.equal(body.schemaVersion, LOOKUP_SCHEMA_VERSION);
+  assert.equal(body.policyBoundary.guardrail, X402_PAYMENT_IS_NOT_ACTION_AUTHORIZATION);
+  assert.equal(body.policyBoundary.paymentAuthorization, false);
+  assert.equal(body.policyBoundary.actionAuthorization, false);
+  assert.equal(body.policyBoundary.spendAuthorized, false);
+}
+
+async function fetchSatpReputationEvidence({
+  fetchImpl,
+  endpoint = discoveryMetadata.endpoint,
+  request,
+  x402PaymentHeader,
+}) {
+  if (typeof fetchImpl !== 'function') throw new Error('fetchImpl is required for this offline example');
+  const url = buildLookupUrl(endpoint, request);
+  const response = await fetchImpl(url, {
+    method: 'GET',
+    headers: {
+      Accept: 'application/json',
+      'X-PAYMENT': x402PaymentHeader,
+    },
+  });
+  const body = await response.json();
+  assertLookupBoundary(body);
+  if (!response.ok) {
+    throw new Error(body.error && body.error.code ? body.error.code : 'satp_lookup_failed');
+  }
+  return body;
+}
+
+function createMockFetch() {
+  return async function mockFetch(url, options = {}) {
+    assert.equal(url.pathname, '/v1/satp/evidence/reputation');
+    assert.equal(url.searchParams.get('agentId'), 'brainChain');
+    assert.equal(options.headers.Accept, 'application/json');
+    assert.equal(options.headers['X-PAYMENT'], 'fixture-x402-payment-proof');
+
+    return {
+      ok: true,
+      async json() {
+        return {
+          schemaVersion: LOOKUP_SCHEMA_VERSION,
+          lookup: {
+            lookupId: 'lkp_fixture_brainchain_devnet_01',
+            agentId: 'brainChain',
+            wallet: '7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgBNG',
+            network: 'devnet',
+            queriedAt: '2026-07-28T03:18:00Z',
+          },
+          reputation: {
+            score: 88,
+            tier: 'trusted',
+            sourceProgram: 'reputation_v3',
+            computedAt: '2026-07-28T03:10:00Z',
+          },
+          evidence: {
+            attestations: [
+              {
+                claimType: 'github_verified',
+                issuer: 'satp-attestation-authority',
+                status: 'valid',
+              },
+            ],
+          },
+          proof: {
+            source: 'satp',
+            programSet: 'v3',
+            trace: 'redacted',
+            evidenceUpdatedAt: '2026-07-28T03:10:00Z',
+          },
+          policyBoundary: {
+            paymentAuthorization: false,
+            actionAuthorization: false,
+            spendAuthorized: false,
+            livePaymentRequiredByClient: false,
+            guardrail: X402_PAYMENT_IS_NOT_ACTION_AUTHORIZATION,
+            message: 'x402 payment grants lookup access only and does not authorize SATP agent actions.',
+          },
+        };
+      },
+    };
+  };
+}
+
+async function runExample() {
+  const descriptor = buildRuntimePolicyActionDescriptorFromX402Discovery(discoveryMetadata, {
+    sourceKind: 'well-known-x402',
+    maxCostUsd: 0,
+  });
+  assert.equal(descriptor.operation, 'satp.reputationEvidence.lookup');
+  assert.equal(descriptor.paymentAuthorization, false);
+  assert.equal(descriptor.actionAuthorization, false);
+  assert.equal(descriptor.spendAuthorized, false);
+  assert.equal(descriptor.livePaymentRequired, false);
+
+  const body = await fetchSatpReputationEvidence({
+    fetchImpl: createMockFetch(),
+    request: {
+      agentId: 'brainChain',
+      network: 'devnet',
+      include: ['identity', 'reputation', 'attestations', 'policy'],
+      trace: 'redacted',
+    },
+    x402PaymentHeader: 'fixture-x402-payment-proof',
+  });
+
+  return {
+    endpoint: discoveryMetadata.endpoint,
+    lookupId: body.lookup.lookupId,
+    score: body.reputation.score,
+    guardrail: body.policyBoundary.guardrail,
+    paymentAuthorization: body.policyBoundary.paymentAuthorization,
+    actionAuthorization: body.policyBoundary.actionAuthorization,
+    spendAuthorized: body.policyBoundary.spendAuthorized,
+    livePaymentRequired: descriptor.livePaymentRequired,
+  };
+}
+
+if (require.main === module) {
+  runExample()
+    .then((result) => console.log(JSON.stringify(result, null, 2)))
+    .catch((err) => {
+      console.error(err.message);
+      process.exitCode = 1;
+    });
+}
+
+module.exports = {
+  LOOKUP_SCHEMA_VERSION,
+  discoveryMetadata,
+  buildLookupUrl,
+  assertLookupBoundary,
+  fetchSatpReputationEvidence,
+  createMockFetch,
+  runExample,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brainai/satp-client",
-  "version": "2.0.4",
+  "version": "2.0.6",
   "description": "SATP client SDK surface prepared for release-candidate review; publish only after the release packet passes.",
   "main": "src/index.js",
   "types": "src/index.d.ts",
@@ -26,6 +26,7 @@
     "README.md"
   ],
   "scripts": {
+    "check:package-health": "node ../../scripts/check-satp-client-package-health.js",
     "test": "node test.js",
     "test:runtime-policy": "node --test test-runtime-policy-adapter.js",
     "runtime-policy:example": "node examples/runtime-policy-adapter.js",

package/src/borsh-reader.d.ts

@@ -45,7 +45,7 @@ export interface ParsedGenesisRecord {
   faceBurnTx: string | null;
   genesisRecord: number;
   isBorn: boolean;
-  isActive: boolean;
+  isActive: boolean | null;
   authority: string;
   pendingAuthority: string | null;
   reputationScore: number;
@@ -55,6 +55,8 @@ export interface ParsedGenesisRecord {
   createdAt: number;
   updatedAt: number;
   bump: number;
+  layout: 'idl-with-is-active' | 'deployed-no-is-active';
+  hasIsActiveField: boolean;
 }
 
 export interface ParsedLinkedWallet {

package/src/borsh-reader.js

@@ -64,8 +64,9 @@ class BorshReader {
 
   /** Read u64 LE → number (safe for values < 2^53) */
   readU64() {
-    return Number(this.buf.readBigUInt64LE(this.offset));
-    // Note: offset advanced after return won't work — fix:
+    const val = Number(this.buf.readBigUInt64LE(this.offset));
+    this.offset += 8;
+    return val;
   }
 
   /** Read u64 LE → number, advances offset */
@@ -185,7 +186,7 @@ class BorshReader {
  * @param {Buffer} data - Raw account data (with 8-byte discriminator)
  * @returns {object} Parsed GenesisRecord
  */
-function deserializeGenesisRecord(data) {
+function parseGenesisRecordLayout(data, includeIsActive) {
   const r = new BorshReader(data).skipDiscriminator();
 
   const agentIdHash = r.readFixedBytes32();
@@ -198,7 +199,7 @@ function deserializeGenesisRecord(data) {
   const faceMint = r.readPubkey();
   const faceBurnTx = r.readString();
   const genesisRecord = r.readI64();
-  const isActive = r.readBool();
+  const isActive = includeIsActive ? r.readBool() : null;
   const authority = r.readPubkeyBase58();
   const pendingAuthority = r.readOptionPubkey();
   const reputationScore = r.readU64Num();
@@ -209,6 +210,10 @@ function deserializeGenesisRecord(data) {
   const updatedAt = r.readI64();
   const bump = r.readU8();
 
+  if (r.remaining() !== 0) {
+    throw new Error(`GenesisRecord layout left ${r.remaining()} unread bytes`);
+  }
+
   return {
     agentIdHash: agentIdHash.toString('hex'),
     agentName,
@@ -231,9 +236,23 @@ function deserializeGenesisRecord(data) {
     createdAt,
     updatedAt,
     bump,
+    layout: includeIsActive ? 'idl-with-is-active' : 'deployed-no-is-active',
+    hasIsActiveField: includeIsActive,
   };
 }
 
+function deserializeGenesisRecord(data) {
+  const errors = [];
+  for (const includeIsActive of [true, false]) {
+    try {
+      return parseGenesisRecordLayout(data, includeIsActive);
+    } catch (e) {
+      errors.push(e.message);
+    }
+  }
+  throw new Error(`Unable to deserialize GenesisRecord with known layouts: ${errors.join('; ')}`);
+}
+
 /**
  * Deserialize a LinkedWallet from raw account data.
  * @param {Buffer} data - Raw account data (with 8-byte discriminator)

package/src/constants.js

@@ -10,8 +10,10 @@ const DEVNET_PROGRAM_IDS = {
   ESCROW: new PublicKey('UpJ7jmUzHkQ7EdBKiBv3zq8Dr1fVh6GVWKa7nYtwQ22'),
 };
 
-// SATP v2 Program IDs — Mainnet
-const MAINNET_PROGRAM_IDS = {
+const LEGACY_V2_MAINNET_FENCE_MESSAGE = 'Legacy SATP V2 mainnet program IDs are fenced; use getV3ProgramIds("mainnet") for V3 or pass allowLegacyV2Mainnet: true for explicit read-only legacy V2 access';
+
+// SATP v2 Program IDs — Mainnet. Keep internal so direct public imports fail closed.
+const LEGACY_V2_MAINNET_PROGRAM_IDS = {
   IDENTITY: new PublicKey('97yL33fcu6iWT2TdERS5HeqrMSGiUnxuy6nUcTrKieSq'),
   REVIEWS: new PublicKey('Ge1sD2qwmH8QaaKCPZzZERvsFXNVMvKbAgTp2p17yjLK'),
   REPUTATION: new PublicKey('C9ogv8TBrvFy4pLKDoGQg9B73Q5rKPPsQ4kzkcDk6Jd'),
@@ -20,6 +22,18 @@ const MAINNET_PROGRAM_IDS = {
   ESCROW: null,
 };
 
+const MAINNET_PROGRAM_IDS = new Proxy({}, {
+  get() {
+    throw new Error(LEGACY_V2_MAINNET_FENCE_MESSAGE);
+  },
+  ownKeys() {
+    throw new Error(LEGACY_V2_MAINNET_FENCE_MESSAGE);
+  },
+  getOwnPropertyDescriptor() {
+    throw new Error(LEGACY_V2_MAINNET_FENCE_MESSAGE);
+  },
+});
+
 const MAINNET_RPC = 'https://api.mainnet-beta.solana.com';
 const DEVNET_RPC = 'https://api.devnet.solana.com';
 
@@ -37,13 +51,21 @@ const ESCROW_SEED = 'escrow';
 /**
  * Get program IDs for a given network.
  * @param {'mainnet'|'devnet'} network
+ * @param {object} [opts]
+ * @param {boolean} [opts.allowLegacyV2Mainnet=false]
  * @returns {object} Program ID map
  */
-function getProgramIds(network = 'devnet') {
+function getProgramIds(network = 'devnet', opts = {}) {
   if (network !== 'devnet' && network !== 'mainnet') {
     throw new Error('Invalid network: expected devnet or mainnet');
   }
-  return network === 'mainnet' ? MAINNET_PROGRAM_IDS : DEVNET_PROGRAM_IDS;
+  if (network === 'mainnet') {
+    if (opts.allowLegacyV2Mainnet !== true) {
+      throw new Error(LEGACY_V2_MAINNET_FENCE_MESSAGE);
+    }
+    return LEGACY_V2_MAINNET_PROGRAM_IDS;
+  }
+  return DEVNET_PROGRAM_IDS;
 }
 
 /**
@@ -61,6 +83,7 @@ function getRpcUrl(network = 'devnet') {
 module.exports = {
   DEVNET_PROGRAM_IDS,
   MAINNET_PROGRAM_IDS,
+  LEGACY_V2_MAINNET_FENCE_MESSAGE,
   getProgramIds,
   getRpcUrl,
   MAINNET_RPC,

package/src/index.d.ts

@@ -467,6 +467,7 @@ export interface SATSDKOptions {
   network?: Network;
   rpcUrl?: string;
   commitment?: 'processed' | 'confirmed' | 'finalized';
+  allowLegacyV2Mainnet?: boolean;
 }
 
 export interface V2Identity {

package/src/index.js

@@ -46,10 +46,15 @@ class SATPSDK {
    */
   constructor(opts = {}) {
     this.network = opts.network || 'devnet';
+    if (this.network === 'mainnet' && opts.allowLegacyV2Mainnet !== true) {
+      throw new Error('Legacy SATPSDK V2 mainnet access is fenced; use SATPV3SDK for V3 or pass allowLegacyV2Mainnet: true for explicit read-only legacy V2 access');
+    }
     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);
+    this.programIds = getProgramIds(this.network, {
+      allowLegacyV2Mainnet: opts.allowLegacyV2Mainnet === true,
+    });
   }
 
   // ─── Identity ──────────────────────────────────────────
@@ -822,71 +827,6 @@ function createSATPClient(opts = {}) {
 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,
@@ -981,10 +921,8 @@ module.exports = {
   evaluateRuntimePolicy,
 
   // 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
+  deserializeGenesis: v3Borsh.deserializeGenesisRecord,
+  deserializeGenesisRecord: v3Borsh.deserializeGenesisRecord,
   deserializeLinkedWallet: v3Borsh.deserializeLinkedWallet,
   deserializeMintTracker: v3Borsh.deserializeMintTracker,
   deserializeNameRegistry: v3Borsh.deserializeNameRegistry,

package/src/runtime-policy-adapter.js

@@ -36,6 +36,7 @@ const DEFAULT_POLICY = Object.freeze({
 
 const RUNTIME_POLICY_AUDIT_TRACE_SCHEMA_VERSION = 'satp.runtimePolicyAuditTrace.v1';
 const RUNTIME_POLICY_HOST_ACTION_DESCRIPTOR_SCHEMA_VERSION = 'satp.runtimePolicyHostActionDescriptor.v1';
+const TRUST_SCORE_GATE_TYPES = new Set(['agentfolio_trust_gate', 'host_trust_gate']);
 
 function createRuntimePolicyAdapter(config = {}) {
   if (!config || typeof config !== 'object' || Array.isArray(config)) {
@@ -361,7 +362,7 @@ function firstDefined(...values) {
 
 function defaultResourceForAction(type, action) {
   if (type === 'mcp_protected_tool') return 'mcp://protected/tool';
-  if (type === 'agentfolio_trust_gate') {
+  if (TRUST_SCORE_GATE_TYPES.has(type)) {
     if (action.profileId) {
       return `https://agentfolio.bot/api/profile/${encodeURIComponent(String(action.profileId))}/trust-score`;
     }
@@ -373,27 +374,27 @@ function defaultResourceForAction(type, action) {
 
 function defaultOperationForAction(type) {
   if (type === 'mcp_protected_tool') return 'invoke';
-  if (type === 'agentfolio_trust_gate') return 'trust-score-read';
+  if (TRUST_SCORE_GATE_TYPES.has(type)) return 'trust-score-read';
   if (type === 'x402_endpoint') return 'lookup';
   return null;
 }
 
 function defaultCapabilityForAction(type) {
-  if (type === 'agentfolio_trust_gate') return 'agentfolio:trust-read';
+  if (TRUST_SCORE_GATE_TYPES.has(type)) return 'agentfolio:trust-read';
   return null;
 }
 
 function defaultMinimumTrustScoreForAction(type) {
-  if (type === 'agentfolio_trust_gate') return DEFAULT_POLICY.minimumTrustScore;
+  if (TRUST_SCORE_GATE_TYPES.has(type)) return DEFAULT_POLICY.minimumTrustScore;
   return null;
 }
 
 function defaultAllowDegradedForAction(type) {
-  return type === 'agentfolio_trust_gate';
+  return TRUST_SCORE_GATE_TYPES.has(type);
 }
 
 function defaultRequiresFreshEvidenceForAction(type) {
-  return type === 'mcp_protected_tool' || type === 'agentfolio_trust_gate';
+  return type === 'mcp_protected_tool' || TRUST_SCORE_GATE_TYPES.has(type);
 }
 
 function defaultCostUsdForAction(type) {

package/src/v3-pda.js

@@ -15,7 +15,7 @@ const V3_DEVNET_PROGRAM_IDS = {
 };
 
 // Mainnet registry source: Anchor.toml [programs.mainnet], checked by
-// scripts/verify-v3-program-sources.mjs and the D1 authority packet.
+// scripts/verify-v3-program-sources.mjs and docs/v3-program-source-verification.md.
 // 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.

package/src/v3-sdk.d.ts

@@ -48,7 +48,9 @@ export interface GenesisRecord {
   metadataUri: string;
   reputationScore: number;
   verificationLevel: number;
-  isActive: boolean;
+  isActive: boolean | null;
+  layout?: 'idl-with-is-active' | 'deployed-no-is-active';
+  hasIsActiveField?: boolean;
   createdAt: number;
   updatedAt: number;
   pendingAuthority: string | null;

package/src/v3-sdk.js

@@ -26,6 +26,7 @@ const {
   SPL_TOKEN_PROGRAM_ID,
   ASSOCIATED_TOKEN_PROGRAM_ID,
 } = require('./v3-pda');
+const { deserializeGenesisRecord } = require('./borsh-reader');
 
 const DEVNET_RPC = 'https://api.devnet.solana.com';
 const MAINNET_RPC = 'https://api.mainnet-beta.solana.com';
@@ -1960,78 +1961,9 @@ class SATPV3SDK {
     if (!acct) return null;
 
     try {
-      const data = acct.data.slice(8); // skip Anchor discriminator
-      let offset = 0;
-
-      const agentIdHash = data.slice(offset, offset + 32); offset += 32;
-
-      // Read strings
-      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;
-      const isActive = data[offset] === 1; offset += 1;
-      const authority = new PublicKey(data.slice(offset, offset + 32)); offset += 32;
-
-      // Option<Pubkey> — Borsh: 0x00 = None (1 byte only), 0x01 + 32 bytes = Some
-      const hasPending = data[offset] === 1; offset += 1;
-      let pendingAuthority = null;
-      if (hasPending) {
-        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;
-
-      const isBorn = genesisRecord !== 0;
-
       return {
+        ...deserializeGenesisRecord(acct.data),
         pda: pda.toBase58(),
-        agentIdHash: Buffer.from(agentIdHash).toString('hex'),
-        agentName,
-        description,
-        category,
-        capabilities,
-        metadataUri,
-        faceImage: faceImage || null,
-        faceMint: faceMint.equals(PublicKey.default) ? null : faceMint.toBase58(),
-        faceBurnTx: faceBurnTx || null,
-        genesisRecord,
-        isBorn,
-        isActive,
-        authority: authority.toBase58(),
-        pendingAuthority,
-        reputationScore,
-        verificationLevel,
-        reputationUpdatedAt,
-        verificationUpdatedAt,
-        createdAt,
-        updatedAt,
-        bump,
       };
     } catch (e) {
       return { pda: pda.toBase58(), raw: acct.data.toString('hex'), error: e.message };