kontext-sdk 0.8.0 → 0.10.0

package/README.md

@@ -161,6 +161,61 @@ const chain = ctx.verifyDigestChain();
 console.log(chain.valid); // true — no tampering
 ```
 
+### Agent Provenance
+
+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',
+  amount: '5000',
+  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,
+});
+
+// End session, list sessions, list checkpoints
+await ctx.endAgentSession(session.sessionId);
+const sessions = ctx.getAgentSessions('treasury-agent');
+const checkpoints = ctx.getCheckpoints(session.sessionId);
+```
+
+#### CLI Commands
+
+```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
@@ -176,6 +231,68 @@ const ctx = Kontext.init({
 // Call ctx.flush() to write, ctx.restore() to reload
 ```
 
+## Auto-Instrumentation (viem)
+
+Run `npx kontext init` to generate a config file, then wrap your viem client — every stablecoin transfer is automatically logged.
+
+```bash
+npx kontext init
+# Wizard asks: project name, agent ID, wallets to monitor, tokens, chains, mode
+# Creates kontext.config.json
+```
+
+```typescript
+import { Kontext, withKontextCompliance } from 'kontext-sdk';
+import { createWalletClient, http } from 'viem';
+import { base } from 'viem/chains';
+
+const kontext = Kontext.init();  // reads kontext.config.json
+const client = withKontextCompliance(
+  createWalletClient({ chain: base, transport: http() }),
+  kontext,
+);
+
+// Every USDC/USDT/DAI/EURC transfer now auto-logged with compliance proof
+await client.sendTransaction({ to: USDC_ADDRESS, data: transferCalldata });
+```
+
+**Two interception layers:**
+- **Code wrap:** `withKontextCompliance()` intercepts `sendTransaction`/`writeContract` calls. Can block pre-send if non-compliant.
+- **Chain listener:** SDK watches monitored wallet addresses on-chain for ERC-20 Transfer events — catches ALL outgoing stablecoin transfers regardless of origin.
+
+## Pluggable Sanctions Screening
+
+Multi-provider screening with consensus strategies. Bring your own API keys, or use the built-in OFAC SDN list at zero cost.
+
+```typescript
+import {
+  ScreeningAggregator,
+  OFACAddressProvider,
+  UKOFSIProvider,
+  OpenSanctionsProvider,
+  ChainalysisOracleProvider,
+} 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
+  ],
+  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`)
+
 ## Compliance Thresholds
 
 | Threshold | Amount | Trigger |
@@ -190,9 +307,11 @@ OFAC sanctions screening uses the built-in SDN list. No API key required.
 
 - 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