@brainai/satp-client 2.0.0 → 2.0.2

package/package.json

@@ -1,14 +1,37 @@
 {
   "name": "@brainai/satp-client",
-  "version": "2.0.0",
-  "description": "SATP v2 Client SDK — Solana Agent Token Protocol (Identity, Reviews, Reputation, Attestations, Validation)",
+  "version": "2.0.2",
+  "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",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./wallet-control-challenge": {
+      "types": "./src/index.d.ts",
+      "default": "./src/wallet-control-challenge.js"
+    },
+    "./x402-discovery": {
+      "types": "./src/index.d.ts",
+      "default": "./src/x402-discovery.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
   "files": [
     "src/",
+    "examples/",
     "README.md"
   ],
   "scripts": {
-    "test": "node test.js"
+    "test": "node test.js",
+    "test:runtime-policy": "node --test test-runtime-policy-adapter.js",
+    "runtime-policy:example": "node examples/runtime-policy-adapter.js",
+    "test:wallet-control": "node test-wallet-control-challenge.js",
+    "test:x402-discovery": "node test-x402-discovery.js",
+    "check:exports": "node test-release-safety.js"
   },
   "keywords": [
     "solana",
@@ -23,12 +46,26 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/brainai-dev/satp-client"
+    "url": "git+https://github.com/brainAI-bot/satp.git"
+  },
+  "homepage": "https://github.com/brainAI-bot/satp",
+  "engines": {
+    "node": ">=20.18"
   },
-  "homepage": "https://agentfolio.bot",
   "dependencies": {
     "@solana/web3.js": "^1.98.4",
     "borsh": "^2.0.0",
     "bs58": "^6.0.0"
+  },
+  "private": false,
+  "overrides": {
+    "ws": "^8.21.0",
+    "jayson": {
+      "uuid": "^11.1.1"
+    }
+  },
+  "publishConfig": {
+    "tag": "rc",
+    "access": "public"
   }
 }

package/src/attestation-request.js

@@ -0,0 +1,149 @@
+'use strict';
+
+const crypto = require('crypto');
+const { PublicKey } = require('@solana/web3.js');
+const {
+  getV3ProgramIds,
+  hashAgentId,
+  getGenesisPDA,
+  getV3AttestationPDA,
+} = require('./v3-pda');
+
+const DEFAULT_NETWORK = 'devnet';
+const DEFAULT_ATTESTER = '11111111111111111111111111111111';
+const REQUEST_SCHEMA_VERSION = 'satp.identityAttestationRequest.v1';
+
+function normalizeNetwork(network = DEFAULT_NETWORK) {
+  if (network !== 'devnet' && network !== 'mainnet') {
+    throw new Error('Invalid network: expected devnet or mainnet');
+  }
+  return network;
+}
+
+function normalizePublicKey(value, field) {
+  try {
+    return new PublicKey(value).toBase58();
+  } catch (err) {
+    throw new Error(`Invalid ${field}: expected a Solana public key`);
+  }
+}
+
+function normalizeString(value, field, { maxBytes } = {}) {
+  if (typeof value !== 'string' || value.trim() === '') {
+    throw new Error(`Invalid ${field}: expected a non-empty string`);
+  }
+  const normalized = value.trim();
+  if (maxBytes && Buffer.byteLength(normalized, 'utf8') > maxBytes) {
+    throw new Error(`Invalid ${field}: expected at most ${maxBytes} UTF-8 bytes`);
+  }
+  return normalized;
+}
+
+function normalizeMetadataHash(metadataHash) {
+  if (typeof metadataHash !== 'string' || !/^[a-fA-F0-9]{64}$/.test(metadataHash)) {
+    throw new Error('Invalid metadataHash: expected a 32-byte hex string');
+  }
+  return metadataHash.toLowerCase();
+}
+
+function normalizeExpiresAt(expiresAt) {
+  if (expiresAt === undefined || expiresAt === null) return null;
+  if (!Number.isSafeInteger(expiresAt) || expiresAt < 0) {
+    throw new Error('Invalid expiresAt: expected a non-negative safe integer Unix timestamp');
+  }
+  return expiresAt;
+}
+
+function publicProgramIds(network) {
+  const ids = getV3ProgramIds(network);
+  return {
+    identity: ids.IDENTITY.toBase58(),
+    attestations: ids.ATTESTATIONS.toBase58(),
+  };
+}
+
+function canonicalStringify(value) {
+  if (Array.isArray(value)) {
+    return `[${value.map(canonicalStringify).join(',')}]`;
+  }
+  if (value && typeof value === 'object') {
+    const body = Object.keys(value)
+      .sort()
+      .map((key) => `${JSON.stringify(key)}:${canonicalStringify(value[key])}`)
+      .join(',');
+    return `{${body}}`;
+  }
+  return JSON.stringify(value);
+}
+
+function hashObject(value) {
+  return crypto.createHash('sha256').update(canonicalStringify(value), 'utf8').digest('hex');
+}
+
+/**
+ * Prepare a deterministic, offline, unsigned identity-attestation request.
+ *
+ * This helper derives request metadata only. It does not connect to RPC, read a
+ * credentials, build a transaction, sign, send, or mutate chain state.
+ *
+ * @param {object} opts
+ * @param {string|PublicKey} opts.subjectWallet - Wallet controlled by the attested identity.
+ * @param {string} [opts.agentId=subjectWallet] - SATP agent identifier used for V3 PDA seeds.
+ * @param {string} [opts.claimType] - Human-readable attestation type.
+ * @param {string} [opts.attestationType=claimType] - Alias for claimType.
+ * @param {string} opts.metadataHash - 32-byte hex SHA-256 hash of the off-chain metadata/proof.
+ * @param {string|PublicKey} [opts.attester] - Attester/issuer public key.
+ * @param {'devnet'|'mainnet'} [opts.network='devnet']
+ * @param {number|null} [opts.expiresAt=null] - Optional Unix timestamp for downstream signing.
+ * @returns {object} Plain JSON-safe request metadata.
+ */
+function prepareIdentityAttestationRequest(opts = {}) {
+  if (!opts || typeof opts !== 'object') {
+    throw new Error('Invalid opts: expected an options object');
+  }
+  const network = normalizeNetwork(opts.network);
+  const subjectWallet = normalizePublicKey(opts.subjectWallet, 'subjectWallet');
+  const agentId = normalizeString(opts.agentId || subjectWallet, 'agentId');
+  const claimType = normalizeString(opts.claimType || opts.attestationType, 'claimType', { maxBytes: 32 });
+  const metadataHash = normalizeMetadataHash(opts.metadataHash);
+  const attester = normalizePublicKey(opts.attester || opts.issuer || DEFAULT_ATTESTER, 'attester');
+  const expiresAt = normalizeExpiresAt(opts.expiresAt);
+  const agentIdHash = hashAgentId(agentId).toString('hex');
+  const [genesisPda, genesisBump] = getGenesisPDA(Buffer.from(agentIdHash, 'hex'), network);
+  const [attestationPda, attestationBump] = getV3AttestationPDA(Buffer.from(agentIdHash, 'hex'), attester, claimType, network);
+
+  const request = {
+    schemaVersion: REQUEST_SCHEMA_VERSION,
+    requestType: 'identity-attestation',
+    mode: 'unsigned-readonly-request',
+    network,
+    signingRequired: false,
+    unsigned: true,
+    subjectWallet,
+    agentId,
+    attester,
+    claimType,
+    attestationType: claimType,
+    metadataHash,
+    proofData: JSON.stringify({ metadataHash }),
+    expiresAt,
+    agentIdHash,
+    genesisPda: genesisPda.toBase58(),
+    genesisBump,
+    attestationPda: attestationPda.toBase58(),
+    attestationBump,
+    programs: publicProgramIds(network),
+    instructions: [],
+    signers: [],
+    transaction: null,
+  };
+
+  return {
+    ...request,
+    requestHash: hashObject(request),
+  };
+}
+
+module.exports = {
+  prepareIdentityAttestationRequest,
+};

package/src/borsh-reader.d.ts

@@ -0,0 +1,213 @@
+import { PublicKey } from '@solana/web3.js';
+
+/**
+ * BorshReader — streaming Borsh deserializer for raw account data.
+ */
+export class BorshReader {
+  buf: Buffer;
+  offset: number;
+
+  constructor(buf: Buffer, offset?: number);
+
+  readBytes(n: number): Buffer;
+  readU8(): number;
+  readU16(): number;
+  readU32(): number;
+  readU64Num(): number;
+  readU64BigInt(): bigint;
+  readI64(): number;
+  readI64BigInt(): bigint;
+  readBool(): boolean;
+  readFixedBytes32(): Buffer;
+  readPubkey(): PublicKey;
+  readPubkeyBase58(): string;
+  readString(): string;
+  readVecString(): string[];
+  readOption<T>(readerFn: (this: BorshReader) => T): T | null;
+  readOptionPubkey(): string | null;
+  readOptionI64(): number | null;
+  readOptionBytes32Hex(): string | null;
+  skipDiscriminator(): this;
+  remaining(): number;
+}
+
+// ─── Parsed Account Types ─────────────────────────
+
+export interface ParsedGenesisRecord {
+  agentIdHash: string;
+  agentName: string;
+  description: string;
+  category: string;
+  capabilities: string[];
+  metadataUri: string;
+  faceImage: string | null;
+  faceMint: string | null;
+  faceBurnTx: string | null;
+  genesisRecord: number;
+  isBorn: boolean;
+  isActive: boolean;
+  authority: string;
+  pendingAuthority: string | null;
+  reputationScore: number;
+  verificationLevel: number;
+  reputationUpdatedAt: number;
+  verificationUpdatedAt: number;
+  createdAt: number;
+  updatedAt: number;
+  bump: number;
+}
+
+export interface ParsedLinkedWallet {
+  identity: string;
+  wallet: string;
+  chain: string;
+  label: string;
+  verifiedAt: number;
+  isActive: boolean;
+  bump: number;
+}
+
+export interface ParsedMintTracker {
+  identity: string;
+  mintCount: number;
+  lastMintTimestamp: number;
+  bump: number;
+}
+
+export interface ParsedNameRegistry {
+  name: string;
+  nameHash: string;
+  identity: string;
+  authority: string;
+  registeredAt: number;
+  isActive: boolean;
+  bump: number;
+}
+
+export interface ParsedReview {
+  agentId: string;
+  agentIdHash: string;
+  reviewer: string;
+  rating: number;
+  reviewText: string;
+  metadata: string;
+  createdAt: number;
+  updatedAt: number;
+  isActive: boolean;
+  bump: number;
+}
+
+export interface ParsedReviewCounter {
+  agentId: string;
+  agentIdHash: string;
+  count: number;
+  bump: number;
+}
+
+export interface ParsedAttestation {
+  agentId: string;
+  agentIdHash: string;
+  attestationType: string;
+  issuer: string;
+  proofData: string;
+  verified: boolean;
+  createdAt: number;
+  expiresAt: number | null;
+  isRevoked: boolean;
+  isExpired: boolean;
+  isValid: boolean;
+  bump: number;
+}
+
+export type EscrowStatusV3 =
+  | 'Active'
+  | 'WorkSubmitted'
+  | 'Released'
+  | 'Cancelled'
+  | 'Disputed'
+  | 'Resolved';
+
+export interface ParsedEscrowV3 {
+  client: string;
+  agent: string;
+  agentIdHash: string;
+  amount: number;
+  releasedAmount: number;
+  remaining: number;
+  descriptionHash: string;
+  deadline: number;
+  nonce: number;
+  status: EscrowStatusV3 | string;
+  statusCode: number;
+  minVerificationLevel: number;
+  requireBorn: boolean;
+  createdAt: number;
+  arbiter: string;
+  workHash: string | null;
+  workSubmittedAt: number | null;
+  disputeReasonHash: string | null;
+  disputedAt: number | null;
+  disputedBy: string | null;
+  bump: number;
+}
+
+// ─── Account Type Names ───────────────────────────
+
+export type AccountTypeName =
+  | 'GenesisRecord'
+  | 'LinkedWallet'
+  | 'MintTracker'
+  | 'NameRegistry'
+  | 'Review'
+  | 'ReviewCounter'
+  | 'Attestation'
+  | 'EscrowV3';
+
+export type ParsedAccountData =
+  | ParsedGenesisRecord
+  | ParsedLinkedWallet
+  | ParsedMintTracker
+  | ParsedNameRegistry
+  | ParsedReview
+  | ParsedReviewCounter
+  | ParsedAttestation
+  | ParsedEscrowV3;
+
+// ─── Deserializer Functions ───────────────────────
+
+export function deserializeGenesisRecord(data: Buffer): ParsedGenesisRecord;
+export function deserializeLinkedWallet(data: Buffer): ParsedLinkedWallet;
+export function deserializeMintTracker(data: Buffer): ParsedMintTracker;
+export function deserializeNameRegistry(data: Buffer): ParsedNameRegistry;
+export function deserializeReview(data: Buffer): ParsedReview;
+export function deserializeReviewCounter(data: Buffer): ParsedReviewCounter;
+export function deserializeAttestation(data: Buffer): ParsedAttestation;
+export function deserializeEscrowV3(data: Buffer): ParsedEscrowV3;
+
+/** Auto-detect and deserialize any SATP V3 account. */
+export function deserializeAccount(data: Buffer): {
+  type: AccountTypeName;
+  data: ParsedAccountData;
+};
+
+/** Batch deserialize getProgramAccounts results. */
+export function deserializeBatch(
+  accounts: Array<{ pubkey: PublicKey; account: { data: Buffer } }>,
+  expectedType?: AccountTypeName
+): Array<{
+  pubkey: string;
+  type: AccountTypeName;
+  data: ParsedAccountData;
+}>;
+
+/** Get the 8-byte Anchor discriminator for a known account type. */
+export function getAccountDiscriminator(accountName: string): Buffer;
+
+/** Compute Anchor account discriminator: SHA256("account:<name>")[0..8] */
+export function accountDiscriminator(accountName: string): Buffer;
+
+/** Check if raw data matches a specific account type's discriminator. */
+export function isAccountType(data: Buffer, accountName: AccountTypeName): boolean;
+
+/** Pre-computed discriminators for all V3 account types. */
+export const DISCRIMINATORS: Record<AccountTypeName, Buffer>;