@arc402/sdk 0.2.0

package/src/demos/demo-insurance.ts

@@ -0,0 +1,148 @@
+import { JsonRpcProvider, Wallet, ethers, ContractFactory, NonceManager } from "ethers"
+import { spawn, ChildProcess } from "child_process"
+import { readFileSync } from "fs"
+import { join } from "path"
+
+const FOUNDRY_BIN = process.env.HOME + "/.foundry/bin"
+// Use a PID-based port to avoid conflicts between concurrent runs
+const PORT = 10000 + (process.pid % 10000)
+
+let anvilProcess: ChildProcess | null = null
+process.on("exit", () => { try { anvilProcess?.kill("SIGKILL") } catch {} })
+
+async function startAnvil(): Promise<ChildProcess> {
+  anvilProcess = spawn(
+    FOUNDRY_BIN + "/anvil",
+    ["--port", String(PORT)],
+    { detached: false, stdio: "ignore" }
+  )
+  await new Promise(r => setTimeout(r, 1500))
+  return anvilProcess
+}
+
+function loadArtifact(name: string) {
+  const outDir = join(__dirname, "../../../out")
+  const path = join(outDir, `${name}.sol`, `${name}.json`)
+  const artifact = JSON.parse(readFileSync(path, "utf8"))
+  return { abi: artifact.abi, bytecode: artifact.bytecode.object }
+}
+
+async function main() {
+  console.log("=== ARC-402 DEMO: Insurance Claims Agent ===\n")
+
+  const anvil = await startAnvil()
+
+  const provider = new JsonRpcProvider(`http://127.0.0.1:${PORT}`)
+  // Use NonceManager to ensure correct sequential nonces
+  const owner = new NonceManager(new Wallet("0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80", provider))
+  const medicalProvider = new Wallet("0x59c6995e998f97a5a0044966f0945389dc9e86dae88c7a8412f4603b6b78690d", provider)
+
+  // Deploy contracts
+  const policyArt = loadArtifact("PolicyEngine")
+  const trustArt = loadArtifact("TrustRegistry")
+  const intentArt = loadArtifact("IntentAttestation")
+  const walletArt = loadArtifact("ARC402Wallet")
+
+  const policyEngine = await (await new ContractFactory(policyArt.abi, policyArt.bytecode, owner).deploy()).waitForDeployment()
+  const trustRegistry = await (await new ContractFactory(trustArt.abi, trustArt.bytecode, owner).deploy()).waitForDeployment()
+  const intentAttestation = await (await new ContractFactory(intentArt.abi, intentArt.bytecode, owner).deploy()).waitForDeployment()
+
+  const walletContract = await (await new ContractFactory(walletArt.abi, walletArt.bytecode, owner).deploy(
+    await policyEngine.getAddress(),
+    await trustRegistry.getAddress(),
+    await intentAttestation.getAddress()
+  )).waitForDeployment()
+
+  const walletAddr = await walletContract.getAddress()
+
+  // Add wallet as trust updater
+  await (await (trustRegistry as any).connect(owner).addUpdater(walletAddr)).wait()
+
+  // Register wallet in PolicyEngine so owner can set limits
+  await (await (policyEngine as any).connect(owner).registerWallet(walletAddr, await owner.getAddress())).wait()
+
+  // Fund the wallet with ETH
+  await (await owner.sendTransaction({ to: walletAddr, value: ethers.parseEther("1.0") })).wait()
+
+  // ─── PRIMITIVE 1: POLICY OBJECT ───────────────────────────────────────
+  console.log("[PRIMITIVE 1: POLICY OBJECT]")
+  console.log("Setting policy for claims agent wallet...")
+  console.log("  Category: claims_processing — limit: 0.1 ETH per tx")
+  console.log("  Category: protocol_fee — limit: 0.01 ETH per tx")
+
+  await (await (policyEngine as any).connect(owner).setCategoryLimitFor(walletAddr, "claims_processing", ethers.parseEther("0.1"))).wait()
+  await (await (policyEngine as any).connect(owner).setCategoryLimitFor(walletAddr, "protocol_fee", ethers.parseEther("0.01"))).wait()
+  console.log("Policy set\n")
+
+  // ─── PRIMITIVE 2: CONTEXT BINDING ─────────────────────────────────────
+  console.log("[PRIMITIVE 2: CONTEXT BINDING]")
+  console.log("Opening context: task_type=claims_processing, task_id=claim-4821")
+
+  const contextId = ethers.keccak256(ethers.toUtf8Bytes("claims_processing-claim-4821-" + Date.now()))
+  await (await (walletContract as any).connect(owner).openContext(contextId, "claims_processing")).wait()
+  console.log(`Context ID: ${contextId}`)
+  console.log("Context open\n")
+
+  // ─── PRIMITIVE 3: TRUST PRIMITIVE ─────────────────────────────────────
+  console.log("[PRIMITIVE 3: TRUST PRIMITIVE]")
+  const scoreBefore = await (trustRegistry as any).getScore(walletAddr)
+  const levelBefore = await (trustRegistry as any).getTrustLevel(walletAddr)
+  console.log(`Trust score before: ${scoreBefore} (${levelBefore})\n`)
+
+  // ─── PRIMITIVE 4: INTENT ATTESTATION ──────────────────────────────────
+  console.log("[PRIMITIVE 4: INTENT ATTESTATION]")
+  console.log("Creating intent attestation...")
+
+  const medicalProviderAddr = medicalProvider.address
+  const spendAmount = ethers.parseEther("0.05")
+  console.log(`  Action: acquire_medical_records`)
+  console.log(`  Reason: Claim #4821 requires medical records from Dr. Smith Clinic to assess injury claim`)
+  console.log(`  Recipient: ${medicalProviderAddr} (Medical Records Provider)`)
+  console.log(`  Amount: 0.05 ETH`)
+
+  const attestationId = ethers.keccak256(ethers.toUtf8Bytes("acquire_medical_records-claim-4821-" + Date.now()))
+
+  // Use anvil_impersonateAccount to call attest from wallet contract
+  await provider.send("anvil_impersonateAccount", [walletAddr])
+  await provider.send("anvil_setBalance", [walletAddr, "0xDE0B6B3A7640000"]) // 1 ETH
+
+  const impersonatedWallet = await provider.getSigner(walletAddr)
+  await (await (intentAttestation as any).connect(impersonatedWallet).attest(
+    attestationId,
+    "acquire_medical_records",
+    "Claim #4821 requires medical records from Dr. Smith Clinic to assess injury claim",
+    medicalProviderAddr,
+    spendAmount
+  )).wait()
+  await provider.send("anvil_stopImpersonatingAccount", [walletAddr])
+
+  console.log(`Attestation ID: ${attestationId}`)
+  console.log("Intent attested\n")
+
+  // Execute spend
+  console.log("Executing spend...")
+  const balanceBefore = await provider.send("eth_getBalance", [medicalProviderAddr, "latest"]).then((b: string) => BigInt(b))
+  const tx = await (walletContract as any).connect(owner).executeSpend(medicalProviderAddr, spendAmount, "claims_processing", attestationId)
+  const receipt = await tx.wait()
+  const balanceAfter = await provider.send("eth_getBalance", [medicalProviderAddr, "latest"]).then((b: string) => BigInt(b))
+  console.log(`Spend executed (tx: ${receipt.hash})`)
+  console.log(`  Provider received: ${ethers.formatEther(balanceAfter - balanceBefore)} ETH\n`)
+
+  // Close context
+  console.log("Closing context...")
+  await (await (walletContract as any).connect(owner).closeContext()).wait()
+  const scoreAfter = await (trustRegistry as any).getScore(walletAddr)
+  const levelAfter = await (trustRegistry as any).getTrustLevel(walletAddr)
+  const diff = Number(scoreAfter) - Number(scoreBefore)
+  console.log(`Trust score after: ${scoreAfter} (${levelAfter}) — earned +${diff} for clean context`)
+  console.log("Context closed\n")
+
+  console.log("=== Demo complete ===")
+
+  anvil.kill()
+}
+
+main().catch(e => {
+  console.error("\nDemo failed:", e.message?.split('\n')[0] || e)
+  process.exitCode = 1
+})

package/src/demos/demo-multiagent.ts

@@ -0,0 +1,197 @@
+import { JsonRpcProvider, Wallet, ethers, ContractFactory, NonceManager } from "ethers"
+import { spawn, ChildProcess } from "child_process"
+import { readFileSync } from "fs"
+import { join } from "path"
+
+const FOUNDRY_BIN = process.env.HOME + "/.foundry/bin"
+const PORT = 12000 + (process.pid % 10000)
+
+let anvilProcess: ChildProcess | null = null
+process.on("exit", () => { try { anvilProcess?.kill("SIGKILL") } catch {} })
+
+async function startAnvil(): Promise<ChildProcess> {
+  anvilProcess = spawn(FOUNDRY_BIN + "/anvil", ["--port", String(PORT)], { detached: false, stdio: "ignore" })
+  await new Promise(r => setTimeout(r, 1500))
+  return anvilProcess
+}
+
+function loadArtifact(name: string) {
+  const outDir = join(__dirname, "../../../out")
+  const artifact = JSON.parse(readFileSync(join(outDir, `${name}.sol`, `${name}.json`), "utf8"))
+  return { abi: artifact.abi, bytecode: artifact.bytecode.object }
+}
+
+const ANVIL_KEYS = [
+  "0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80",
+  "0x59c6995e998f97a5a0044966f0945389dc9e86dae88c7a8412f4603b6b78690d",
+  "0x5de4111afa1a4b94908f83103eb1f1706367c2e68ca870fc3fb9a804cdab365a",
+]
+
+async function deployWallet(
+  owner: NonceManager,
+  policyEngineAddr: string,
+  trustRegistryAddr: string,
+  intentAttestationAddr: string,
+  trustRegistry: any,
+  walletArt: any
+) {
+  const wallet = await (await new ContractFactory(walletArt.abi, walletArt.bytecode, owner).deploy(
+    policyEngineAddr, trustRegistryAddr, intentAttestationAddr
+  )).waitForDeployment()
+  const addr = await wallet.getAddress()
+  await (await trustRegistry.connect(owner).addUpdater(addr)).wait()
+  return { wallet, addr }
+}
+
+async function main() {
+  console.log("=== ARC-402 DEMO: Multi-Agent Settlement ===\n")
+
+  const anvil = await startAnvil()
+
+  const provider = new JsonRpcProvider(`http://127.0.0.1:${PORT}`)
+  const deployer = new NonceManager(new Wallet(ANVIL_KEYS[0], provider))
+  const orchestratorOwner = new NonceManager(new Wallet(ANVIL_KEYS[1], provider))
+  const specialistOwner = new NonceManager(new Wallet(ANVIL_KEYS[2], provider))
+
+  // Deploy shared infrastructure
+  const policyArt = loadArtifact("PolicyEngine")
+  const trustArt = loadArtifact("TrustRegistry")
+  const intentArt = loadArtifact("IntentAttestation")
+  const walletArt = loadArtifact("ARC402Wallet")
+  const settlementArt = loadArtifact("SettlementCoordinator")
+
+  const policyEngine = await (await new ContractFactory(policyArt.abi, policyArt.bytecode, deployer).deploy()).waitForDeployment()
+  const trustRegistry = await (await new ContractFactory(trustArt.abi, trustArt.bytecode, deployer).deploy()).waitForDeployment()
+  const intentAttestation = await (await new ContractFactory(intentArt.abi, intentArt.bytecode, deployer).deploy()).waitForDeployment()
+  const settlementCoordinator = await (await new ContractFactory(settlementArt.abi, settlementArt.bytecode, deployer).deploy()).waitForDeployment()
+
+  const peAddr = await policyEngine.getAddress()
+  const trAddr = await trustRegistry.getAddress()
+  const iaAddr = await intentAttestation.getAddress()
+  const scAddr = await settlementCoordinator.getAddress()
+
+  console.log("[INFRASTRUCTURE]")
+  console.log(`  PolicyEngine:            ${peAddr}`)
+  console.log(`  TrustRegistry:           ${trAddr}`)
+  console.log(`  IntentAttestation:       ${iaAddr}`)
+  console.log(`  SettlementCoordinator:   ${scAddr}\n`)
+
+  // Deploy two wallets (using deployer as owner for both for simplicity)
+  const { wallet: orchWallet, addr: orchAddr } = await deployWallet(
+    deployer, peAddr, trAddr, iaAddr, trustRegistry, walletArt
+  )
+  const { wallet: specWallet, addr: specAddr } = await deployWallet(
+    deployer, peAddr, trAddr, iaAddr, trustRegistry, walletArt
+  )
+
+  console.log("[WALLETS]")
+  console.log(`  Orchestrator wallet:     ${orchAddr}`)
+  console.log(`  Specialist wallet:       ${specAddr}\n`)
+
+  // Fund orchestrator
+  await (await deployer.sendTransaction({ to: orchAddr, value: ethers.parseEther("5.0") })).wait()
+
+  // Register wallets in PolicyEngine
+  const deployerAddr = await deployer.getAddress()
+  await (await (policyEngine as any).connect(deployer).registerWallet(orchAddr, deployerAddr)).wait()
+  await (await (policyEngine as any).connect(deployer).registerWallet(specAddr, deployerAddr)).wait()
+
+  // Set policies for both wallets
+  await (await (policyEngine as any).connect(deployer).setCategoryLimitFor(orchAddr, "specialist_fee", ethers.parseEther("1.0"))).wait()
+  await (await (policyEngine as any).connect(deployer).setCategoryLimitFor(specAddr, "orchestrator_payment", ethers.parseEther("1.0"))).wait()
+
+  console.log("[PRIMITIVE 1: POLICIES SET FOR BOTH WALLETS]")
+  console.log(`  Orchestrator: specialist_fee limit = 1.0 ETH`)
+  console.log(`  Specialist: orchestrator_payment limit = 1.0 ETH`)
+  console.log("Policies set\n")
+
+  // Orchestrator opens context
+  console.log("[PRIMITIVE 2: ORCHESTRATOR OPENS CONTEXT]")
+  const orchContextId = ethers.keccak256(ethers.toUtf8Bytes("orchestrator-task-" + Date.now()))
+  await (await (orchWallet as any).connect(deployer).openContext(orchContextId, "coordinate_specialist")).wait()
+  console.log(`  Context ID: ${orchContextId}`)
+  console.log("Orchestrator context open\n")
+
+  // Check trust scores
+  const orchScore = await (trustRegistry as any).getScore(orchAddr)
+  const specScore = await (trustRegistry as any).getScore(specAddr)
+  console.log("[PRIMITIVE 3: TRUST SCORES]")
+  console.log(`  Orchestrator trust: ${orchScore} (${await (trustRegistry as any).getTrustLevel(orchAddr)})`)
+  console.log(`  Specialist trust:   ${specScore} (${await (trustRegistry as any).getTrustLevel(specAddr)})\n`)
+
+  // Orchestrator creates intent attestation for settlement
+  console.log("[PRIMITIVE 4: INTENT ATTESTATION]")
+  const settleAmount = ethers.parseEther("0.5")
+  const intentId = ethers.keccak256(ethers.toUtf8Bytes(`settle-orch-spec-${Date.now()}`))
+
+  await provider.send("anvil_impersonateAccount", [orchAddr])
+  await provider.send("anvil_setBalance", [orchAddr, "0x4563918244F40000"]) // 5 ETH
+  const impOrch = await provider.getSigner(orchAddr)
+  await (await (intentAttestation as any).connect(impOrch).attest(
+    intentId,
+    "pay_specialist",
+    "Payment for data analysis task completed by specialist agent",
+    specAddr,
+    settleAmount
+  )).wait()
+  await provider.send("anvil_stopImpersonatingAccount", [orchAddr])
+  console.log(`  Intent attested: ${intentId}`)
+  console.log("Intent attestation created\n")
+
+  // Propose settlement (anyone can propose)
+  console.log("[SETTLEMENT FLOW]")
+  const scAny = settlementCoordinator as any
+  const expiresAt = Math.floor(Date.now() / 1000) + 3600
+  const proposeTx = await (await scAny.connect(deployer).propose(orchAddr, specAddr, settleAmount, intentId, expiresAt)).wait()
+
+  // Extract proposalId from logs
+  let proposalId = ""
+  const iface = settlementCoordinator.interface
+  for (const log of proposeTx.logs) {
+    try {
+      const parsed = iface.parseLog(log)
+      if (parsed && parsed.name === "ProposalCreated") {
+        proposalId = parsed.args[0]
+        break
+      }
+    } catch {}
+  }
+  console.log(`  Proposal ID: ${proposalId}`)
+  console.log("Proposal created")
+
+  // Specialist accepts - specAddr is the contract wallet, needs impersonation + ETH for gas
+  await provider.send("anvil_impersonateAccount", [specAddr])
+  await provider.send("anvil_setBalance", [specAddr, "0x1BC16D674EC80000"]) // 2 ETH for gas
+  const impSpec = await provider.getSigner(specAddr)
+  await (await scAny.connect(impSpec).accept(proposalId)).wait()
+  await provider.send("anvil_stopImpersonatingAccount", [specAddr])
+  console.log("Specialist accepted")
+
+  // Policy verification
+  console.log("\n[POLICY VERIFICATION BEFORE EXECUTION]")
+  const [orchValid] = await (policyEngine as any).validateSpend(orchAddr, "specialist_fee", settleAmount, orchContextId)
+  console.log(`  Orchestrator policy check (specialist_fee, 0.5 ETH): ${orchValid ? "PASS" : "FAIL"}`)
+
+  // Execute settlement - orchAddr must call execute with value
+  const specBalBefore = await provider.send("eth_getBalance", [specAddr, "latest"]).then((b: string) => BigInt(b))
+  await provider.send("anvil_impersonateAccount", [orchAddr])
+  const impOrch2 = await provider.getSigner(orchAddr)
+  await (await scAny.connect(impOrch2).execute(proposalId, { value: settleAmount })).wait()
+  await provider.send("anvil_stopImpersonatingAccount", [orchAddr])
+
+  const specBalAfter = await provider.send("eth_getBalance", [specAddr, "latest"]).then((b: string) => BigInt(b))
+  console.log(`\n  Specialist received: ${ethers.formatEther(specBalAfter - specBalBefore)} ETH`)
+  console.log("Settlement executed\n")
+
+  // Close orchestrator context
+  await (await (orchWallet as any).connect(deployer).closeContext()).wait()
+  const orchScoreAfter = await (trustRegistry as any).getScore(orchAddr)
+  console.log(`[TRUST UPDATE] Orchestrator: ${orchScore} -> ${orchScoreAfter} (+${Number(orchScoreAfter) - Number(orchScore)})`)
+  console.log("Orchestrator context closed\n")
+
+  console.log("=== Multi-Agent Settlement Demo complete ===")
+
+  anvil.kill()
+}
+
+main().catch(e => { console.error("\nDemo failed:", e.message?.split('\n')[0] || e); process.exitCode = 1 })

package/src/demos/demo-research.ts

@@ -0,0 +1,124 @@
+import { JsonRpcProvider, Wallet, ethers, ContractFactory, NonceManager } from "ethers"
+import { spawn, ChildProcess } from "child_process"
+import { readFileSync } from "fs"
+import { join } from "path"
+
+const FOUNDRY_BIN = process.env.HOME + "/.foundry/bin"
+const PORT = 11000 + (process.pid % 10000)
+
+let anvilProcess: ChildProcess | null = null
+process.on("exit", () => { try { anvilProcess?.kill("SIGKILL") } catch {} })
+
+async function startAnvil(): Promise<ChildProcess> {
+  anvilProcess = spawn(FOUNDRY_BIN + "/anvil", ["--port", String(PORT)], { detached: false, stdio: "ignore" })
+  await new Promise(r => setTimeout(r, 1500))
+  return anvilProcess
+}
+
+function loadArtifact(name: string) {
+  const outDir = join(__dirname, "../../../out")
+  const artifact = JSON.parse(readFileSync(join(outDir, `${name}.sol`, `${name}.json`), "utf8"))
+  return { abi: artifact.abi, bytecode: artifact.bytecode.object }
+}
+
+const ANVIL_KEYS = [
+  "0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80",
+  "0x59c6995e998f97a5a0044966f0945389dc9e86dae88c7a8412f4603b6b78690d",
+  "0x5de4111afa1a4b94908f83103eb1f1706367c2e68ca870fc3fb9a804cdab365a",
+  "0x7c852118294e51e653712a81e05800f419141751be58f605c371e15141b007a6",
+]
+
+async function main() {
+  console.log("=== ARC-402 DEMO: Research Agent ===\n")
+
+  const anvil = await startAnvil()
+
+  const provider = new JsonRpcProvider(`http://127.0.0.1:${PORT}`)
+  const owner = new NonceManager(new Wallet(ANVIL_KEYS[0], provider))
+  const dataProviderWallets = [
+    new Wallet(ANVIL_KEYS[1], provider),
+    new Wallet(ANVIL_KEYS[2], provider),
+    new Wallet(ANVIL_KEYS[3], provider),
+  ]
+
+  // Deploy
+  const policyArt = loadArtifact("PolicyEngine")
+  const trustArt = loadArtifact("TrustRegistry")
+  const intentArt = loadArtifact("IntentAttestation")
+  const walletArt = loadArtifact("ARC402Wallet")
+
+  const policyEngine = await (await new ContractFactory(policyArt.abi, policyArt.bytecode, owner).deploy()).waitForDeployment()
+  const trustRegistry = await (await new ContractFactory(trustArt.abi, trustArt.bytecode, owner).deploy()).waitForDeployment()
+  const intentAttestation = await (await new ContractFactory(intentArt.abi, intentArt.bytecode, owner).deploy()).waitForDeployment()
+  const walletContract = await (await new ContractFactory(walletArt.abi, walletArt.bytecode, owner).deploy(
+    await policyEngine.getAddress(),
+    await trustRegistry.getAddress(),
+    await intentAttestation.getAddress()
+  )).waitForDeployment()
+
+  const walletAddr = await walletContract.getAddress()
+  await (await (trustRegistry as any).connect(owner).addUpdater(walletAddr)).wait()
+  await (await (policyEngine as any).connect(owner).registerWallet(walletAddr, await owner.getAddress())).wait()
+  await (await owner.sendTransaction({ to: walletAddr, value: ethers.parseEther("2.0") })).wait()
+
+  // Set research policy (different limits than insurance)
+  console.log("[PRIMITIVE 1: POLICY OBJECT]")
+  console.log("Setting policy for research agent wallet...")
+  console.log("  Category: data_acquisition — limit: 0.05 ETH per tx")
+  console.log("  Category: api_access — limit: 0.02 ETH per tx")
+  console.log("  Category: analysis — limit: 0.03 ETH per tx")
+  await (await (policyEngine as any).connect(owner).setCategoryLimitFor(walletAddr, "data_acquisition", ethers.parseEther("0.05"))).wait()
+  await (await (policyEngine as any).connect(owner).setCategoryLimitFor(walletAddr, "api_access", ethers.parseEther("0.02"))).wait()
+  await (await (policyEngine as any).connect(owner).setCategoryLimitFor(walletAddr, "analysis", ethers.parseEther("0.03"))).wait()
+  console.log("Policy set\n")
+
+  // Open context
+  console.log("[PRIMITIVE 2: CONTEXT BINDING]")
+  const contextId = ethers.keccak256(ethers.toUtf8Bytes("research-market-analysis-" + Date.now()))
+  await (await (walletContract as any).connect(owner).openContext(contextId, "market_research")).wait()
+  console.log(`Context ID: ${contextId}`)
+  console.log("Research context open\n")
+
+  const dataProviders = [
+    { name: "Bloomberg Data Feed", category: "data_acquisition", amount: "0.05", action: "acquire_market_data" },
+    { name: "Reuters API", category: "api_access", amount: "0.02", action: "fetch_news_feed" },
+    { name: "Quant Analysis Service", category: "analysis", amount: "0.03", action: "run_sentiment_analysis" },
+  ]
+
+  console.log("[PRIMITIVE 3 & 4: SEQUENTIAL DATA PROVIDER PAYMENTS]")
+  for (let i = 0; i < dataProviders.length; i++) {
+    const dp = dataProviders[i]
+    const providerAddr = dataProviderWallets[i].address
+    const amount = ethers.parseEther(dp.amount)
+    const attestId = ethers.keccak256(ethers.toUtf8Bytes(`${dp.action}-${i}-${Date.now()}`))
+
+    console.log(`\nPayment ${i + 1}/3: ${dp.name}`)
+    console.log(`  Action: ${dp.action}`)
+    console.log(`  Category: ${dp.category} — ${dp.amount} ETH`)
+
+    await provider.send("anvil_impersonateAccount", [walletAddr])
+    const impersonated = await provider.getSigner(walletAddr)
+    await (await (intentAttestation as any).connect(impersonated).attest(
+      attestId, dp.action, `Research payment to ${dp.name}`, providerAddr, amount
+    )).wait()
+    await provider.send("anvil_stopImpersonatingAccount", [walletAddr])
+
+    const balBefore = await provider.send("eth_getBalance", [providerAddr, "latest"]).then((b: string) => BigInt(b))
+    await (await (walletContract as any).connect(owner).executeSpend(providerAddr, amount, dp.category, attestId)).wait()
+    const balAfter = await provider.send("eth_getBalance", [providerAddr, "latest"]).then((b: string) => BigInt(b))
+    console.log(`  Payment executed — provider received ${ethers.formatEther(balAfter - balBefore)} ETH`)
+  }
+
+  console.log("\n[TRUST & CONTEXT CLOSE]")
+  const scoreBefore = await (trustRegistry as any).getScore(walletAddr)
+  await (await (walletContract as any).connect(owner).closeContext()).wait()
+  const scoreAfter = await (trustRegistry as any).getScore(walletAddr)
+  console.log(`Trust score: ${scoreBefore} -> ${scoreAfter} (+${Number(scoreAfter) - Number(scoreBefore)})`)
+  console.log("Research context closed\n")
+
+  console.log("=== Research Demo complete ===")
+
+  anvil.kill()
+}
+
+main().catch(e => { console.error("\nDemo failed:", e.message?.split('\n')[0] || e); process.exitCode = 1 })

package/src/dispute-arbitration.ts

@@ -0,0 +1,196 @@
+import { ContractRunner, ethers } from "ethers";
+import { ArbitratorBondState, DisputeClass, DisputeFeeState, DisputeMode } from "./types";
+
+const DISPUTE_ARBITRATION_ABI = [
+  // Views
+  "function getDisputeFeeState(uint256 agreementId) view returns (tuple(uint8 mode, uint8 disputeClass, address opener, address client, address provider, address token, uint256 agreementPrice, uint256 feeRequired, uint256 openerPaid, uint256 respondentPaid, uint256 openedAt, bool active, bool resolved))",
+  "function getArbitratorBondState(address arbitrator, uint256 agreementId) view returns (tuple(uint256 bondAmount, uint256 lockedAt, bool locked, bool slashed, bool returned))",
+  "function getFeeQuote(uint256 agreementPrice, address token, uint8 mode, uint8 disputeClass) view returns (uint256 feeInTokens)",
+  "function getAcceptedArbitrators(uint256 agreementId) view returns (address[])",
+  "function isEligibleArbitrator(address arbitrator) view returns (bool)",
+  "function tokenUsdRate18(address token) view returns (uint256)",
+  "function feeFloorUsd18() view returns (uint256)",
+  "function feeCapUsd18() view returns (uint256)",
+  "function minBondFloorUsd18() view returns (uint256)",
+  // Transactions
+  "function joinMutualDispute(uint256 agreementId) payable",
+  "function acceptAssignment(uint256 agreementId) payable",
+  "function triggerFallback(uint256 agreementId) returns (bool)",
+  "function slashArbitrator(uint256 agreementId, address arbitrator, string reason)",
+  "function reclaimExpiredBond(uint256 agreementId)",
+  "function transferOwnership(address newOwner)",
+  "function acceptOwnership()",
+  "function setTokenUsdRate(address token, uint256 usdRate18)",
+  "function setFeeFloorUsd(uint256 floorUsd18)",
+  "function setFeeCapUsd(uint256 capUsd18)",
+  "function setMinBondFloorUsd(uint256 floorUsd18)",
+  "function setServiceAgreement(address sa)",
+  "function setTrustRegistry(address tr)",
+  "function setTreasury(address treasury)",
+  // Events
+  "event DisputeFeeOpened(uint256 indexed agreementId, uint8 mode, uint8 disputeClass, uint256 feeRequired, address token)",
+  "event MutualDisputeFunded(uint256 indexed agreementId, address respondent, uint256 respondentFee)",
+  "event DisputeFeeResolved(uint256 indexed agreementId, uint8 outcome, uint256 openerRefund)",
+  "event ArbitratorAssigned(uint256 indexed agreementId, address indexed arbitrator, uint256 bondAmount)",
+  "event ArbitratorBondReturned(uint256 indexed agreementId, address indexed arbitrator, uint256 amount)",
+  "event ArbitratorBondSlashed(uint256 indexed agreementId, address indexed arbitrator, uint256 amount, string reason)",
+  "event ArbitratorFeePaid(uint256 indexed agreementId, address indexed arbitrator, uint256 feeShare)",
+  "event DisputeFallbackTriggered(uint256 indexed agreementId, string reason)",
+  "event TokenRateSet(address indexed token, uint256 usdRate18)",
+];
+
+export class DisputeArbitrationClient {
+  private contract: ethers.Contract;
+
+  constructor(address: string, runner: ContractRunner) {
+    this.contract = new ethers.Contract(address, DISPUTE_ARBITRATION_ABI, runner);
+  }
+
+  // ─── Views ────────────────────────────────────────────────────────────────
+
+  async getDisputeFeeState(agreementId: bigint): Promise<DisputeFeeState> {
+    const r = await this.contract.getDisputeFeeState(agreementId);
+    return {
+      mode: Number(r.mode) as DisputeMode,
+      disputeClass: Number(r.disputeClass) as DisputeClass,
+      opener: r.opener,
+      client: r.client,
+      provider: r.provider,
+      token: r.token,
+      agreementPrice: BigInt(r.agreementPrice),
+      feeRequired: BigInt(r.feeRequired),
+      openerPaid: BigInt(r.openerPaid),
+      respondentPaid: BigInt(r.respondentPaid),
+      openedAt: BigInt(r.openedAt),
+      active: r.active,
+      resolved: r.resolved,
+    };
+  }
+
+  async getArbitratorBondState(arbitrator: string, agreementId: bigint): Promise<ArbitratorBondState> {
+    const r = await this.contract.getArbitratorBondState(arbitrator, agreementId);
+    return {
+      bondAmount: BigInt(r.bondAmount),
+      lockedAt: BigInt(r.lockedAt),
+      locked: r.locked,
+      slashed: r.slashed,
+      returned: r.returned,
+    };
+  }
+
+  async getFeeQuote(
+    agreementPrice: bigint,
+    token: string,
+    mode: DisputeMode,
+    disputeClass: DisputeClass
+  ): Promise<bigint> {
+    return BigInt(await this.contract.getFeeQuote(agreementPrice, token, mode, disputeClass));
+  }
+
+  async getAcceptedArbitrators(agreementId: bigint): Promise<string[]> {
+    return this.contract.getAcceptedArbitrators(agreementId);
+  }
+
+  async isEligibleArbitrator(address: string): Promise<boolean> {
+    return this.contract.isEligibleArbitrator(address);
+  }
+
+  async getTokenUsdRate(token: string): Promise<bigint> {
+    return BigInt(await this.contract.tokenUsdRate18(token));
+  }
+
+  // ─── Transactions ─────────────────────────────────────────────────────────
+
+  /** Respondent in MUTUAL dispute funds their half of the fee. */
+  async joinMutualDispute(
+    agreementId: bigint,
+    halfFeeEth: bigint = 0n // 0 for ERC-20 agreements (pre-approve instead)
+  ): Promise<ethers.TransactionReceipt> {
+    const tx = await this.contract.joinMutualDispute(agreementId, { value: halfFeeEth });
+    return (await tx.wait())!;
+  }
+
+  /** Nominated arbitrator accepts assignment and posts bond. */
+  async acceptAssignment(
+    agreementId: bigint,
+    bondEth: bigint = 0n // 0 for ERC-20 agreements (pre-approve instead)
+  ): Promise<ethers.TransactionReceipt> {
+    const tx = await this.contract.acceptAssignment(agreementId, { value: bondEth });
+    return (await tx.wait())!;
+  }
+
+  /** Trigger fallback to human backstop queue (mutual unfunded or panel not formed). */
+  async triggerFallback(agreementId: bigint): Promise<ethers.TransactionReceipt> {
+    const tx = await this.contract.triggerFallback(agreementId);
+    return (await tx.wait())!;
+  }
+
+  /** Owner-only: slash an arbitrator for manual rules violation. */
+  async slashArbitrator(
+    agreementId: bigint,
+    arbitrator: string,
+    reason: string
+  ): Promise<ethers.TransactionReceipt> {
+    const tx = await this.contract.slashArbitrator(agreementId, arbitrator, reason);
+    return (await tx.wait())!;
+  }
+
+  /**
+   * Arbitrators can reclaim their bond after 45 days if the dispute was never resolved via resolveDisputeFee.
+   * Prevents permanent bond lock on stalled disputes.
+   */
+  async reclaimExpiredBond(agreementId: bigint): Promise<ethers.TransactionReceipt> {
+    const tx = await this.contract.reclaimExpiredBond(agreementId);
+    return (await tx.wait())!;
+  }
+
+  /** Step 1 of two-step ownership transfer. Owner-only. */
+  async proposeOwner(newOwner: string): Promise<ethers.TransactionReceipt> {
+    const tx = await this.contract.transferOwnership(newOwner);
+    return (await tx.wait())!;
+  }
+
+  /** Step 2 of two-step ownership transfer. Must be called by the pending owner. */
+  async acceptOwnership(): Promise<ethers.TransactionReceipt> {
+    const tx = await this.contract.acceptOwnership();
+    return (await tx.wait())!;
+  }
+
+  // ─── Admin ────────────────────────────────────────────────────────────────
+
+  /**
+   * Set the USD rate for a payment token. Owner only.
+   * @param token Token address (address(0) for ETH)
+   * @param usdRate18 USD per token with 18 decimals (e.g. 2000e18 for ETH at $2000)
+   * IMPORTANT: This is an admin-set rate, not a trustless oracle. Keep it current.
+   */
+  async setTokenUsdRate(token: string, usdRate18: bigint): Promise<ethers.TransactionReceipt> {
+    const tx = await this.contract.setTokenUsdRate(token, usdRate18);
+    return (await tx.wait())!;
+  }
+
+  async setFeeFloorUsd(floorUsd18: bigint): Promise<ethers.TransactionReceipt> {
+    const tx = await this.contract.setFeeFloorUsd(floorUsd18);
+    return (await tx.wait())!;
+  }
+
+  async setFeeCapUsd(capUsd18: bigint): Promise<ethers.TransactionReceipt> {
+    const tx = await this.contract.setFeeCapUsd(capUsd18);
+    return (await tx.wait())!;
+  }
+
+  async setServiceAgreement(address: string): Promise<ethers.TransactionReceipt> {
+    const tx = await this.contract.setServiceAgreement(address);
+    return (await tx.wait())!;
+  }
+
+  async setTrustRegistry(address: string): Promise<ethers.TransactionReceipt> {
+    const tx = await this.contract.setTrustRegistry(address);
+    return (await tx.wait())!;
+  }
+
+  async setTreasury(address: string): Promise<ethers.TransactionReceipt> {
+    const tx = await this.contract.setTreasury(address);
+    return (await tx.wait())!;
+  }
+}