@aifinpay/deployments 1.1.0

package/README.md

@@ -0,0 +1,133 @@
+# @aifinpay/deployments
+
+## Deployment registry & artifact manager
+
+This package provides a programmatic interface for querying AIFP deployment records and contract artifacts (ABI/IDL).
+
+### Quick Start
+
+```typescript
+import { AifinpayRegistry, ArtifactRegistry } from "@aifinpay/deployments";
+
+// Load deployment registries
+const evmRegistry = AifinpayRegistry.loadEvm("latest");      // or "1.4", "1.3", etc.
+const solanaRegistry = AifinpayRegistry.loadSolana("latest");
+
+// Load contract artifacts
+const artifacts = ArtifactRegistry.load();
+
+// Query deployments
+const optimism = evmRegistry.getEvmDeployment(10);
+const splitterAddr = evmRegistry.getSplitterAddress(10);
+const stablecoins = evmRegistry.getStablecoins(10);
+
+// Get supported chains
+const chains = evmRegistry.getSupportedChains("enabled");  // [10, 137, ...]
+const networks = evmRegistry.getNetworkList();             // [{ chainId, name, status, ... }]
+
+// Export as markdown/json/csv
+const markdown = evmRegistry.exportAsMarkdown("prod");
+const json = evmRegistry.exportAsJson();
+const csv = evmRegistry.exportAsCsv();
+
+// Query artifacts
+const abi = artifacts.getEvmAbi("B2BSplitterV14", "1.4");
+const solanaIdl = artifacts.getSolanaIdl("mainnet");
+```
+
+See [USAGE.md](./USAGE.md) for complete documentation.
+
+---
+
+## Registry grabber (legacy)
+
+`src/grabber.ts` pulls the latest deployment records from the canonical
+upstream repositories and produces per-ecosystem split registry files:
+
+- EVM v1.4: `registry/splitter/evm/v1.4/deployments.json`
+- Solana v1.4: `registry/splitter/solana/deployments.json`
+
+```bash
+cd deployments
+npm ci --no-audit --no-fund
+npm run build          # compile TypeScript
+npm run registry:build # fetch upstream + write registry/*.json
+npm test               # offline unit tests
+```
+
+## Registry layout
+
+Per-ecosystem split files are the canonical artifacts. ABI and IDL
+subdirectories are kept for downstream consumers that need raw contract
+artifacts:
+
+```
+registry/
+├── splitter/                  # versioned registry with governance metadata
+│   ├── evm/
+│   │   ├── v1.4/deployments.json  # EVM v1.4 full contract suite
+│   │   ├── v1.3/deployments.json  # EVM v1.3 route table
+│   │   ├── v1.2/deployments.json  # EVM v1.2 legacy
+│   │   └── v1.1/deployments.json  # EVM v1.1 legacy
+│   ├── solana/deployments.json # Solana v1.4 program deployments
+│   └── casper/deployments.json # Casper deployments
+├── abi/
+│   ├── evm/         # EVM ABI bundles (B2BSplitterV14, TimelockWrapper)
+│   └── tron/        # Tron ABI bundles when applicable
+└── idl/
+    ├── solana/      # Solana IDL (splitter-v14 mainnet/devnet)
+    ├── aptos/       # Aptos IDL artifacts
+    └── casper/      # Casper IDL artifacts
+```
+
+### Version history
+
+| Registry | Location | Versions | Status |
+|---|---|---|---|
+| Legacy route table | `registry/splitter/evm/v1.3` | v1.2 `legacy`, v1.3 `merchant-aifp1` / `agent-x402` | Superseded; kept for `node/` SDK generation |
+| Legacy v1.2 | `registry/splitter/evm/v1.2` | v1.2 with `paymentId` replay guard | Superseded |
+| Legacy v1.1 | `registry/splitter/evm/v1.1` | v1.1 initial release | Superseded |
+| This package | `registry/splitter/evm/v1.4/deployments.json` | v1.4 EVM | Active grabber output |
+| This package | `registry/splitter/solana/deployments.json` | v1.4 Solana | Active grabber output |
+
+## Exports
+
+### Deployment Registry
+
+- `AifinpayRegistry.loadEvm(version?)` — load EVM deployment registry (default: "latest" = "1.4")
+- `AifinpayRegistry.loadSolana(version?)` — load Solana deployment registry (default: "latest" = "1.4")
+- `getEvmDeployment(chainId)` — O(1) lookup by chain ID
+- `getEvmByNetwork(network)` — lookup by network name
+- `getSplitterAddress(chainId)`, `getTokenListAddress(chainId)`, `getProfilesAddress(chainId)` — contract addresses
+- `getStablecoins(chainId)` — stablecoin list
+- `isSettlementEnabled(chainId)` — settlement status
+- `getGovernanceSafe(env)` — Safe multisig address
+- `filterByStatus(status)`, `getProdDeployments()`, `getTestnetDeployments()` — filtering
+- `getSupportedChains(filter?)` — get list of supported chain IDs (filter: "all" | "prod" | "testnet" | "enabled")
+- `getNetworkList(filter?)` — get network list with metadata
+- `isChainSupported(chainId)` — check if chain is supported
+- `getChainIdByNetwork(network)` — get chain ID by name
+- `getNetworkByChainId(chainId)` — get network name by ID
+- `exportAsMarkdown(filter?)`, `exportAsJson(filter?)`, `exportAsCsv(filter?)` — export formats
+
+### Artifact Registry
+
+- `ArtifactRegistry.load()` — load all ABI/IDL artifacts
+- `getEvmAbi(contractName, version?)` — EVM ABI
+- `getSolanaIdl(cluster)` — Solana IDL (mainnet/devnet)
+- `getCasperIdl(network)` — Casper IDL (mainnet/testnet)
+- `getAptosIdl(contractName, version?)` — Aptos IDL
+- `getTronAbi(contractName, version?)` — Tron ABI
+
+### Legacy grabber (deprecated)
+
+- `buildRegistry()` — fetch upstream EVM + Solana records (deprecated: use `AifinpayRegistry.loadEvm()`)
+- `writeSplitRegistries(registry, outDir)` — write split registry files
+- `grabEvmDeployments()` / `grabSolanaDeployments()` — grab one chain family
+- `getEvmDeployment(registry, chainId)` / `getSolanaDeployment(registry, cluster)` — O(1) lookup helpers
+- `isEvmDeployment(d)` / `isSolanaDeployment(d)` — type guards
+
+### Types
+
+- `DeploymentRegistry`, `EcosystemRegistry`, `Deployment`, `EvmDeployment`, `SolanaDeployment`, `Stablecoin`
+- `EvmDeploymentRecord`, `SolanaDeploymentRecord`, `EvmAbiArtifact`, `SolanaIdlArtifact`

package/USAGE.md

@@ -0,0 +1,534 @@
+# @aifinpay/deployments — Usage Guide
+
+Programmatic interface for querying AIFP deployment records and contract artifacts (ABI/IDL).
+
+## Installation
+
+```bash
+npm install @aifinpay/deployments
+```
+
+## Quick Start
+
+```typescript
+import { AifinpayRegistry, ArtifactRegistry } from "@aifinpay/deployments";
+
+// Load registries
+const evmRegistry = AifinpayRegistry.loadEvm();      // latest = v1.4
+const solanaRegistry = AifinpayRegistry.loadSolana(); // latest = v1.4
+const artifacts = ArtifactRegistry.load();
+```
+
+---
+
+## AifinpayRegistry — Deployment Records
+
+### Load EVM Registry
+
+```typescript
+// Load latest version (v1.4)
+const registry = AifinpayRegistry.loadEvm();
+
+// Load specific version
+const v14 = AifinpayRegistry.loadEvm("1.4");
+const v13 = AifinpayRegistry.loadEvm("1.3");
+const v12 = AifinpayRegistry.loadEvm("1.2");
+const v11 = AifinpayRegistry.loadEvm("1.1");
+
+// Explicit latest
+const latest = AifinpayRegistry.loadEvm("latest");
+```
+
+### Load Solana Registry
+
+```typescript
+// Load latest version (v1.4)
+const registry = AifinpayRegistry.loadSolana();
+
+// Explicit version
+const v14 = AifinpayRegistry.loadSolana("1.4");
+const latest = AifinpayRegistry.loadSolana("latest");
+```
+
+### Query Deployments
+
+```typescript
+const registry = AifinpayRegistry.loadEvm();
+
+// Get deployment by chain ID
+const optimism = registry.getEvmDeployment(10);
+if (optimism) {
+  console.log(optimism.chain);        // "optimism"
+  console.log(optimism.status);       // "enabled"
+  console.log(optimism.contracts);    // { splitter, tokenList, profiles, ... }
+}
+
+// Get deployment by network name
+const polygon = registry.getEvmByNetwork("polygon");
+console.log(polygon?.chainId); // 137
+
+// Get all deployments
+const all = registry.getAllEvmDeployments();
+
+// Filter by status
+const enabled = registry.filterByStatus("enabled");
+const disabled = registry.filterByStatus("disabled");
+
+// Get prod/testnet deployments
+const prod = registry.getProdDeployments();
+const testnet = registry.getTestnetDeployments();
+```
+
+### Contract Addresses
+
+```typescript
+const registry = AifinpayRegistry.loadEvm();
+const chainId = 10; // Optimism
+
+// Get contract addresses
+const splitter = registry.getSplitterAddress(chainId);
+const tokenList = registry.getTokenListAddress(chainId);
+const profiles = registry.getProfilesAddress(chainId);
+
+// All return null if not found
+const unknown = registry.getSplitterAddress(99999); // null
+```
+
+### Stablecoins
+
+```typescript
+const registry = AifinpayRegistry.loadEvm();
+const chainId = 10; // Optimism
+
+const stablecoins = registry.getStablecoins(chainId);
+// Returns: Array<{ symbol: string, name: string, address: string }>
+
+for (const coin of stablecoins) {
+  console.log(`${coin.symbol}: ${coin.address}`);
+}
+
+// Empty array if chain not found
+const empty = registry.getStablecoins(99999); // []
+```
+
+### Settlement Status
+
+```typescript
+const registry = AifinpayRegistry.loadEvm();
+
+// Check if settlement is enabled
+const enabled = registry.isSettlementEnabled(10); // true/false
+
+// Returns false for unknown chains
+const disabled = registry.isSettlementEnabled(99999); // false
+```
+
+### Governance
+
+```typescript
+const registry = AifinpayRegistry.loadEvm();
+
+// Get Safe multisig addresses
+const prodSafe = registry.getGovernanceSafe("prod");
+const testnetSafe = registry.getGovernanceSafe("testnet");
+```
+
+### Registry Metadata
+
+```typescript
+const registry = AifinpayRegistry.loadEvm();
+
+console.log(registry.getVersion());      // "1.4"
+console.log(registry.getGeneratedAt());  // ISO 8601 timestamp
+```
+
+### Supported Chains
+
+```typescript
+const registry = AifinpayRegistry.loadEvm();
+
+// Get all supported chain IDs
+const allChains = registry.getSupportedChains();           // [1, 10, 137, ...]
+
+// Get only production chains
+const prodChains = registry.getSupportedChains("prod");
+
+// Get only testnet chains
+const testnetChains = registry.getSupportedChains("testnet");
+
+// Get only enabled chains (status = "enabled" AND settlementEnabled = true)
+const enabledChains = registry.getSupportedChains("enabled");
+```
+
+### Network List
+
+```typescript
+const registry = AifinpayRegistry.loadEvm();
+
+// Get network list with metadata
+const networks = registry.getNetworkList();
+// Returns: Array<{ chainId, name, status, settlementEnabled, testnet }>
+
+for (const network of networks) {
+  console.log(`${network.name} (chainId: ${network.chainId}): ${network.status}`);
+}
+
+// Filter by production only
+const prodNetworks = registry.getNetworkList("prod");
+```
+
+### Chain Helpers
+
+```typescript
+const registry = AifinpayRegistry.loadEvm();
+
+// Check if a chain is supported
+const isSupported = registry.isChainSupported(10);  // true/false
+
+// Get chain ID by network name
+const optimismId = registry.getChainIdByNetwork("optimism");  // 10
+
+// Get network name by chain ID
+const networkName = registry.getNetworkByChainId(10);  // "optimism"
+```
+
+### Export Formats
+
+```typescript
+const registry = AifinpayRegistry.loadEvm();
+
+// Export as markdown table
+const markdown = registry.exportAsMarkdown();
+console.log(markdown);
+// | Chain ID | Network | Status | Settlement | Testnet |
+// |----------|---------|--------|------------|---------|
+// | 10 | optimism | enabled | ✅ | No |
+// | 137 | polygon | enabled | ✅ | No |
+
+// Export filtered markdown
+const prodMarkdown = registry.exportAsMarkdown("prod");
+const enabledMarkdown = registry.exportAsMarkdown("enabled");
+
+// Export as JSON
+const json = registry.exportAsJson();
+console.log(json);
+// [{"chainId":10,"name":"optimism","status":"enabled",...}, ...]
+
+// Export as CSV
+const csv = registry.exportAsCsv();
+console.log(csv);
+// chainId,name,status,settlementEnabled,testnet
+// 10,optimism,enabled,true,false
+// 137,polygon,enabled,true,false
+```
+
+---
+
+## ArtifactRegistry — ABI/IDL Artifacts
+
+### Load Artifacts
+
+```typescript
+const artifacts = ArtifactRegistry.load();
+```
+
+### EVM ABI
+
+```typescript
+const artifacts = ArtifactRegistry.load();
+
+// Get ABI by contract name and version
+const abi = artifacts.getEvmAbi("B2BSplitterV14", "1.4");
+if (abi) {
+  console.log(abi.contractName);  // "B2BSplitterV14"
+  console.log(abi.version);       // "1.4"
+  console.log(abi.abi);           // ABI array
+  console.log(abi.bytecode);      // Optional bytecode
+}
+
+// Default version (1.4)
+const defaultAbi = artifacts.getEvmAbi("B2BSplitterV14");
+
+// Get all ABIs
+const allAbis = artifacts.getAllEvmAbis();
+
+// Returns null if not found
+const unknown = artifacts.getEvmAbi("UnknownContract"); // null
+```
+
+### Solana IDL
+
+```typescript
+const artifacts = ArtifactRegistry.load();
+
+// Get IDL by cluster
+const mainnetIdl = artifacts.getSolanaIdl("mainnet");
+const devnetIdl = artifacts.getSolanaIdl("devnet");
+
+if (mainnetIdl) {
+  console.log(mainnetIdl.programName);  // "splitter"
+  console.log(mainnetIdl.version);      // "1.4"
+  console.log(mainnetIdl.cluster);      // "mainnet"
+  console.log(mainnetIdl.idl);          // Full IDL object
+}
+
+// Get all IDLs
+const allIdls = artifacts.getAllSolanaIdls();
+```
+
+### Casper IDL
+
+```typescript
+const artifacts = ArtifactRegistry.load();
+
+// Get IDL by network
+const testnetIdl = artifacts.getCasperIdl("testnet");
+const mainnetIdl = artifacts.getCasperIdl("mainnet");
+
+// Get all Casper IDLs
+const allIdls = artifacts.getAllCasperIdls();
+```
+
+### Aptos IDL
+
+```typescript
+const artifacts = ArtifactRegistry.load();
+
+// Get IDL by contract name
+const splitterIdl = artifacts.getAptosIdl("splitter");
+
+// Get specific version
+const versionedIdl = artifacts.getAptosIdl("splitter", "1.4");
+
+// Get all Aptos IDLs
+const allIdls = artifacts.getAllAptosIdls();
+```
+
+### Tron ABI
+
+```typescript
+const artifacts = ArtifactRegistry.load();
+
+// Get ABI by contract name
+const splitterAbi = artifacts.getTronAbi("B2BSplitter");
+
+// Get specific version
+const versionedAbi = artifacts.getTronAbi("B2BSplitter", "1.4");
+
+// Get all Tron ABIs
+const allAbis = artifacts.getAllTronAbis();
+```
+
+---
+
+## Complete Examples
+
+### Setup Payment on Chain
+
+```typescript
+import { AifinpayRegistry, ArtifactRegistry } from "@aifinpay/deployments";
+
+async function setupPayment(chainId: number) {
+  // Load registries
+  const evmRegistry = AifinpayRegistry.loadEvm();
+  const artifacts = ArtifactRegistry.load();
+
+  // Get deployment
+  const deployment = evmRegistry.getEvmDeployment(chainId);
+  if (!deployment) {
+    throw new Error(`No deployment for chain ${chainId}`);
+  }
+
+  // Check settlement status
+  if (!evmRegistry.isSettlementEnabled(chainId)) {
+    throw new Error(`Settlement disabled on chain ${chainId}`);
+  }
+
+  // Get contract addresses
+  const splitterAddress = evmRegistry.getSplitterAddress(chainId);
+  const tokenListAddress = evmRegistry.getTokenListAddress(chainId);
+
+  // Get stablecoins
+  const stablecoins = evmRegistry.getStablecoins(chainId);
+  console.log(`Available stablecoins: ${stablecoins.map(s => s.symbol).join(", ")}`);
+
+  // Get ABI for contract interaction
+  const abi = artifacts.getEvmAbi("B2BSplitterV14", "1.4");
+  if (!abi) {
+    throw new Error("ABI not found");
+  }
+
+  // Get governance info
+  const prodSafe = evmRegistry.getGovernanceSafe("prod");
+  console.log(`Governance Safe: ${prodSafe}`);
+
+  return {
+    deployment,
+    splitterAddress,
+    tokenListAddress,
+    stablecoins,
+    abi: abi.abi,
+  };
+}
+
+// Usage
+const config = await setupPayment(10); // Optimism
+console.log(config);
+```
+
+### Generate Supported Chains Documentation
+
+```typescript
+import { AifinpayRegistry } from "@aifinpay/deployments";
+
+const registry = AifinpayRegistry.loadEvm();
+
+// Generate markdown table for README
+const markdown = registry.exportAsMarkdown("prod");
+console.log(markdown);
+// | Chain ID | Network   | Status  | Settlement | Testnet |
+// |----------|-----------|---------|------------|---------|
+// | 10       | optimism  | enabled | ✅         | No      |
+// | 137      | polygon   | enabled | ✅         | No      |
+
+// Generate JSON for API response
+const json = registry.exportAsJson("enabled");
+console.log(json);
+
+// Generate CSV for spreadsheet
+const csv = registry.exportAsCsv();
+console.log(csv);
+```
+
+### Check Chain Support
+
+```typescript
+import { AifinpayRegistry } from "@aifinpay/deployments";
+
+const registry = AifinpayRegistry.loadEvm();
+
+// Check if specific chains are supported
+const supportedChains = [1, 10, 137, 8453];
+for (const chainId of supportedChains) {
+  const name = registry.getNetworkByChainId(chainId);
+  const isSupported = registry.isChainSupported(chainId);
+  console.log(`Chain ${chainId} (${name}): ${isSupported ? "✅" : "❌"}`);
+}
+
+// Get chain ID for network name
+const optimismId = registry.getChainIdByNetwork("optimism");
+console.log(`Optimism chain ID: ${optimismId}`);  // 10
+```
+
+---
+
+## Error Handling
+
+```typescript
+const registry = AifinpayRegistry.loadEvm();
+
+// Methods return null for not found
+const deployment = registry.getEvmDeployment(99999);
+if (deployment === null) {
+  console.log("Chain not supported");
+}
+
+// Methods return empty arrays for not found
+const stablecoins = registry.getStablecoins(99999);
+if (stablecoins.length === 0) {
+  console.log("No stablecoins configured");
+}
+
+// Settlement returns false for unknown chains
+const enabled = registry.isSettlementEnabled(99999);
+if (!enabled) {
+  console.log("Settlement not available");
+}
+```
+
+---
+
+## TypeScript Types
+
+```typescript
+import type {
+  EvmDeploymentRecord,
+  SolanaDeploymentRecord,
+  EvmAbiArtifact,
+  SolanaIdlArtifact,
+} from "@aifinpay/deployments";
+
+// EVM deployment record
+interface EvmDeploymentRecord {
+  chain: string;
+  chainId: number;
+  environment: "dev" | "prod";
+  testnet: boolean;
+  status: "enabled" | "disabled" | "invalid" | "retired";
+  settlementEnabled: boolean;
+  contracts: {
+    splitter: string;
+    tokenList: string;
+    profiles: string;
+    admin: string;
+    signer: string;
+    pauser: string;
+    treasury: string;
+  };
+  assets: Array<{
+    symbol: string;
+    name: string;
+    address: string;
+  }>;
+  safe: {
+    address: string;
+    version: string;
+    threshold: number;
+  };
+}
+
+// EVM ABI artifact
+interface EvmAbiArtifact {
+  contractName: string;
+  version: string;
+  abi: unknown[];
+  bytecode?: string;
+}
+
+// Solana IDL artifact
+interface SolanaIdlArtifact {
+  programName: string;
+  version: string;
+  cluster: "mainnet" | "devnet";
+  idl: unknown;
+}
+```
+
+---
+
+## Registry Structure
+
+The package ships with pre-built registry files:
+
+```
+registry/
+├── splitter/
+│   ├── evm/
+│   │   ├── v1.4/deployments.json  # Latest EVM
+│   │   ├── v1.3/deployments.json  # Historical
+│   │   ├── v1.2/deployments.json  # Historical
+│   │   └── v1.1/deployments.json  # Historical
+│   └── solana/
+│       └── deployments.json       # Solana v1.4
+├── abi/
+│   ├── evm/
+│   │   ├── B2BSplitterV14/
+│   │   └── TimelockWrapper/
+│   └── tron/
+└── idl/
+    ├── solana/splitter-v14/
+    ├── casper/
+    └── aptos/
+```
+
+Use `loadEvm("1.4")` for the latest EVM version, or specify an older version for legacy deployments.