kontext-sdk 0.9.0 → 0.11.0

package/README.md

@@ -1,180 +1,45 @@
 # kontext-sdk
 
-Compliance audit trail CLI and SDK for AI agents making stablecoin payments on Base.
+The trust layer for agentic stablecoin and fiat payments.
 
-**USDC** · **USDT** · **DAI** · **EURC** · **USDP** · **USDG** · **x402** · **Circle Programmable Wallets**
-
----
-
-## 30-Second Demo
-
-```bash
-npx kontext-sdk check 0xAgentWallet 0xMerchant --amount 5000 --token USDC
-```
-
-```
-OFAC Sanctions:  CLEAR
-Travel Rule:     TRIGGERED ($5,000 >= $3,000 EDD threshold)
-CTR Threshold:   CLEAR ($5,000 < $10,000)
-Large TX Alert:  CLEAR ($5,000 < $50,000)
-Risk Level:      medium
-```
-
-No install. No config. No API key. One command.
+Cryptographic verifiable intent for org-wide payments using one line of code and a CLI.
 
 ## Install
 
 ```bash
-npm install -g kontext-sdk
-```
-
-Then run `kontext` from anywhere. Or use `npx kontext-sdk` for one-off checks.
-
-## Claude Code / Cursor / Windsurf
-
-```json
-{
-  "mcpServers": {
-    "kontext": {
-      "command": "npx",
-      "args": ["-y", "kontext-sdk", "mcp"]
-    }
-  }
-}
-```
-
-Then ask: *"verify this USDC transaction for compliance"*
-
-## CLI Commands
-
-### `kontext check <from> <to>` — stateless compliance check
-
-```bash
-npx kontext-sdk check 0xSender 0xReceiver --amount 5000 --token USDC
+npm install kontext-sdk
 ```
 
-Instant OFAC screening + threshold checks. No state, no persistence.
-
-### `kontext verify` — log + check + digest proof
+## Auto-instrumentation (recommended)
 
 ```bash
-npx kontext-sdk verify --tx 0xabc123 --amount 5000 --token USDC \
-  --from 0xAgent --to 0xMerchant --agent my-bot
-```
-
-Runs compliance checks, logs the transaction, appends to the tamper-evident digest chain. Persists to `.kontext/` in the current directory.
-
-### `kontext reason` — log agent reasoning
-
-```bash
-npx kontext-sdk reason "API returned data I need. Price within budget." \
-  --agent my-bot --session sess_abc --step 1
-```
-
-### `kontext cert` — export compliance certificate
-
-```bash
-npx kontext-sdk cert --agent my-bot --output cert.json
-```
-
-### `kontext audit` — verify digest chain integrity
-
-```bash
-npx kontext-sdk audit --verify
-```
-
-### `kontext mcp` — MCP server mode
-
-```bash
-npx kontext-sdk mcp
-```
-
-Starts an MCP server on stdio for Claude Code, Cursor, and Windsurf.
-
-### Flags
-
-- `--json` on any command outputs structured JSON
-- `--amount <number>` transaction amount in token units
-- `--token <symbol>` one of USDC, USDT, DAI, EURC, USDP, USDG
-
-## SDK — Programmatic Usage
-
-For tighter integration, use the SDK directly:
-
-```typescript
-import { Kontext, FileStorage } from 'kontext-sdk';
-
-const ctx = Kontext.init({
-  projectId: 'my-agent',
-  environment: 'production',
-  storage: new FileStorage('.kontext'),
-});
-
-// One-call: compliance check + transaction log + digest proof
-const result = await ctx.verify({
-  txHash: '0xabc...',
-  chain: 'base',
-  amount: '5000',
-  token: 'USDC',
-  from: '0xAgent...',
-  to: '0xMerchant...',
-  agentId: 'payment-agent',
-});
-
-// result.compliant = true/false
-// result.checks = [{ name: 'OFAC Sanctions', passed: true }, ...]
-// result.riskLevel = 'low' | 'medium' | 'high' | 'critical'
-// result.digestProof = 'sha256:a1b2c3...'
+npx kontext init
+# Creates kontext.config.json with your wallets, tokens, chains, and compliance mode
 ```
 
-### Log Reasoning
-
 ```typescript
-await ctx.logReasoning({
-  agentId: 'payment-agent',
-  action: 'approve-transfer',
-  reasoning: 'Price within budget. Merchant verified.',
-  confidence: 0.95,
-});
-```
+import { Kontext, withKontextCompliance } from 'kontext-sdk';
 
-### Compliance Certificate
+const kontext = Kontext.init();  // reads kontext.config.json
+const client = withKontextCompliance(walletClient, kontext);
 
-```typescript
-const cert = await ctx.generateComplianceCertificate({
-  agentId: 'payment-agent',
-  includeReasoning: true,
-});
+// Every USDC/USDT/DAI/EURC transfer is now auto-verified
+await client.sendTransaction({ to: usdcAddress, data: transferCalldata });
 ```
 
-### Trust Score
+Two interception layers for full coverage:
+- **Code wrap** -- intercepts `sendTransaction`/`writeContract` on your viem client
+- **Chain listener** -- watches monitored wallets on-chain for all outgoing stablecoin transfers
 
-```typescript
-const score = await ctx.getTrustScore('payment-agent');
-// score.score = 87, score.level = 'high'
-```
+## Explicit verify
 
-### Verify Digest Chain
+For direct control over individual transactions:
 
 ```typescript
-const chain = ctx.verifyDigestChain();
-console.log(chain.valid); // true — no tampering
-```
+import { Kontext } from 'kontext-sdk';
 
-### Agent Provenance
+const ctx = Kontext.init({ projectId: 'my-agent' });
 
-Three layers of accountability: session delegation, action binding, and human attestation.
-
-```typescript
-// Layer 1: Session delegation — record who authorized the agent
-const session = await ctx.createAgentSession({
-  agentId: 'treasury-agent',
-  delegatedBy: 'user:vinay',
-  scope: ['transfer', 'approve'],
-  expiresAt: new Date(Date.now() + 3600_000).toISOString(),
-});
-
-// Layer 2: Action binding — tie every call to the session
 const result = await ctx.verify({
   txHash: '0xabc...',
   chain: 'base',
@@ -182,109 +47,67 @@ const result = await ctx.verify({
   token: 'USDC',
   from: '0xAgent...',
   to: '0xMerchant...',
-  agentId: 'treasury-agent',
-  sessionId: session.sessionId,
-});
-
-// Layer 3: Human attestation — reviewer signs off
-const checkpoint = await ctx.createCheckpoint({
-  sessionId: session.sessionId,
-  actionIds: [result.transaction.id],
-  summary: 'Reviewed $5K transfer to known vendor',
-});
-
-await ctx.attestCheckpoint({
-  checkpointId: checkpoint.checkpointId,
-  attestedBy: 'compliance@company.com',
-  signature: reviewerSignature,
+  agentId: 'payment-agent',
 });
 
-// End session, list sessions, list checkpoints
-await ctx.endAgentSession(session.sessionId);
-const sessions = ctx.getAgentSessions('treasury-agent');
-const checkpoints = ctx.getCheckpoints(session.sessionId);
+// result.compliant -- true/false
+// result.checks -- OFAC, Travel Rule, CTR thresholds
+// result.riskLevel -- low | medium | high | critical
+// result.digestProof -- tamper-evident SHA-256 chain
 ```
 
-#### CLI Commands
+## What's verified
 
-```bash
-npx kontext-sdk session create --agent treasury-agent --delegated-by user:vinay --scope transfer,approve
-npx kontext-sdk session list --agent treasury-agent
-npx kontext-sdk session end <sessionId>
-npx kontext-sdk checkpoint create --session <sessionId> --actions act_1,act_2 --summary "Reviewed transfers"
-npx kontext-sdk checkpoint attest <checkpointId> --attested-by compliance@company.com
-npx kontext-sdk checkpoint list --session <sessionId>
-```
-
-### Persist Across Restarts
-
-```typescript
-import { FileStorage } from 'kontext-sdk';
-
-const ctx = Kontext.init({
-  projectId: 'my-agent',
-  environment: 'production',
-  storage: new FileStorage('.kontext'),
-});
-
-// Data persists to .kontext/ directory
-// Call ctx.flush() to write, ctx.restore() to reload
-```
+Every stablecoin transfer gets:
+- OFAC sanctions screening (built-in SDN list, no API key)
+- Travel Rule threshold detection ($3K EDD, $10K CTR, $50K large tx)
+- Tamper-evident audit trail (patented digest chain)
+- Agent trust score (0-100)
+- Compliance certificate with SHA-256 proof
 
-## Pluggable Sanctions Screening
+## Pluggable screening
 
-Multi-provider screening with consensus strategies. Bring your own API keys, or use the built-in OFAC SDN list at zero cost.
+Bring your own providers or use the built-in OFAC list:
 
 ```typescript
-import {
-  ScreeningAggregator,
-  OFACAddressProvider,
-  UKOFSIProvider,
-  OpenSanctionsProvider,
-  ChainalysisOracleProvider,
-} from 'kontext-sdk';
+import { ScreeningAggregator, OFACAddressProvider, OpenSanctionsProvider } from 'kontext-sdk';
 
 const screener = new ScreeningAggregator({
   providers: [
-    new OFACAddressProvider(),                             // built-in, no API key
-    new UKOFSIProvider(),                                  // built-in, no API key
-    new OpenSanctionsProvider({ apiKey: 'os_...' }),       // 331+ sources
-    new ChainalysisOracleProvider({ apiKey: 'ch_...' }),   // on-chain oracle
+    new OFACAddressProvider(),                          // built-in, free
+    new OpenSanctionsProvider({ apiKey: 'os_...' }),    // 331+ sources
   ],
   consensus: 'ANY_MATCH',
 });
-
-const result = await screener.screenAddress('0x...');
-// result.flagged = true/false
-// result.matches = [{ provider, list, matchType, confidence, ... }]
-// result.providerResults = per-provider breakdown
 ```
 
-**Built-in providers (no API key):** OFAC SDN addresses, UK OFSI addresses
-**API providers:** OpenSanctions (address + entity), Chainalysis Oracle (address), Chainalysis Free API (address)
-**Local providers:** OpenSanctions local dataset (download via `kontext sync`)
+## Agent reasoning
 
-## Compliance Thresholds
+```typescript
+await ctx.logReasoning({
+  agentId: 'payment-agent',
+  action: 'approve-transfer',
+  reasoning: 'Amount within daily limit. Recipient on allowlist.',
+  confidence: 0.95,
+});
+```
 
-| Threshold | Amount | Trigger |
-|-----------|--------|---------|
-| **EDD / Travel Rule** | $3,000 | Enhanced Due Diligence required |
-| **CTR** | $10,000 | Currency Transaction Report |
-| **Large TX Alert** | $50,000 | Large Transaction Alert |
+## MCP server
 
-OFAC sanctions screening uses the built-in SDN list. No API key required.
+```json
+{
+  "mcpServers": {
+    "kontext": {
+      "command": "npx",
+      "args": ["-y", "@kontext-sdk/cli", "mcp"]
+    }
+  }
+}
+```
 
-## What's Included
+## Zero runtime dependencies
 
-- Tamper-evident audit trail (patented digest chain)
-- OFAC sanctions screening (SDN list, no API key)
-- Pluggable multi-provider screening (OFAC, UK OFSI, OpenSanctions, Chainalysis)
-- Compliance certificates with SHA-256 proof
-- Agent reasoning logs
-- Trust scoring and anomaly detection
-- Agent provenance — session delegation, action binding, human attestation
-- MCP server mode for AI coding tools
-- Zero runtime dependencies
+The SDK has no `dependencies`. Works in Node.js 18+, TypeScript 5.0+.
 
 ## License
 
@@ -292,6 +115,4 @@ MIT
 
 ---
 
-Kontext provides compliance logging tools. Regulatory responsibility remains with the operator. This software does not constitute legal advice and does not guarantee regulatory compliance. Consult qualified legal counsel for your specific obligations.
-
 Built by [Legaci Labs](https://www.getkontext.com)