Treasury Demo

A standalone demo project that shows the difference between calling external APIs directly and routing calls through ChainLens SDK.

This project is outside the ChainLens monorepo and consumes @chain-lens/sdk and @chain-lens/cli as ordinary npm packages.

---

Purpose

Direct API calls give agents data.
ChainLens gives agents accountable execution.

Scenario: An AI coding agent builds a treasury dashboard. It needs stock prices, crypto prices, FX rates, wallet risk, and news sentiment.

	Direct	ChainLens
Code style	Scattered, inconsistent	Single execution surface
Schema validation	None — runtime crash	Validated before settlement
Cost visibility	No ledger	Per-call cost tracked
Settlement receipt	None	On verified success
Failure record	Console log	Demo telemetry + live SDK telemetry

---

Installation

npm install
npm install -g @chain-lens/cli@latest

Requires @chain-lens/sdk@0.1.2 or later and @chain-lens/cli@0.1.2 or later. Earlier versions had EIP-712 domain name mismatches with Base Sepolia USDC.

---

Environment Setup

Copy .env.example to .env:

cp .env.example .env

.env fields:

# Controls deterministic mock failures.
DEMO_RUN_ID=demo-schema-mismatch-timeout

# Required only for live ChainLens SDK calls.
WALLET_PRIVATE_KEY=0x...
RPC_URL=https://...
CHAIN_ID=84532

# Public gateway (include /api).
CHAINLENS_GATEWAY=https://chainlens.pelicanlab.dev/api

---

Dry-run vs Live mode

Dry-run (default — no wallet needed)

demo:direct and demo:chainlens both run without a wallet.

demo:chainlens detects missing wallet env and prints ChainLens-shaped output using local deterministic mocks. It writes project-local demo telemetry for npm run report, but does not claim to write real SDK telemetry under ~/.chainlens.

Live mode

Set WALLET_PRIVATE_KEY, RPC_URL, and CHAINLENS_GATEWAY in .env. demo:chainlens will use @chain-lens/sdk with a real ViemWallet to call listing #13 with { "symbol": "MSFT" }.

Real SDK telemetry is written only in live mode by @chain-lens/sdk. The demo report intentionally reads the project-local telemetry generated by npm run demo:chainlens, so demo-controlled failures show up with the same failure names shown on stage.

---

Demo Execution Order

Run in this exact order:

npm run demo:direct
npm run demo:chainlens
npm run recommend:broad
npm run recommend:msft
npm run report

---

1. Direct Demo

npm run demo:direct

Five providers are called with intentionally different styles:

• coingecko.ts — crypto prices
• stockVendor.ts — stock prices
• fxAxiosStyle.ts — FX rates (axios-style response shape)
• walletRisk.ts — crashes at runtime due to unexpected schema
• newsSentiment.ts — times out after 5 seconds

Expected output:

Direct Treasury Demo
[coingecko]      ETH price         ok      $3,182.70
[stock-vendor]   AAPL price        ok      $189.42
[fx-axios]       USD/KRW           ok      1,334.77
[walletRisk]     0xA1B2...a1b2     FAILED  cannot read property 'riskScore' of ...
[newsSentiment]  "tech bonds"      TIMEOUT  after 5000ms

Portfolio value: $65,066.83 (incomplete — 2 of 5 sources failed)

There is no cost ledger, no provider risk memory, and no settlement receipt.

---

2. ChainLens Demo

npm run demo:chainlens

• MSFT listing #13 is called via ChainLens SDK (live) or dry-run.
• Wallet risk is validated against a known schema — mismatch is caught before any settlement.
• News sentiment times out — no settlement is submitted.
• Failed calls show no settlement submitted.

Local mock failure note: The schema mismatch and timeout are demo-controlled local failures. They show ChainLens semantics without relying on a live public broken listing.

---

3. Recommend

npm run recommend:broad
npm run recommend:msft

• Broad query: Shows ChainLens verified listings alongside Coinbase Bazaar candidates.
• Narrow MSFT query: Pushes listing #13 to first place.

Bazaar candidates are external candidates, not ChainLens-verified. They are discoverable but not yet wrapped or listed on ChainLens.

---

4. Report

npm run report

npm run report reads project-local demo telemetry written by npm run demo:chainlens. It is not a backend query and does not mix in old records from ~/.chainlens.

Use the raw CLI command chainlens report only when you specifically want the SDK's real local telemetry history.

npm run report는 .env에서 WALLET_PRIVATE_KEY를 자동으로 로드합니다. chainlens report를 shell에서 직접 실행할 경우 환경변수를 먼저 export해야 합니다.

• Shows the latest demo run's calls, successes, failures, spend, and failure breakdown.
• The demo telemetry file is reset each time npm run demo:chainlens starts.

Telemetry is local. Run npm run demo:chainlens before npm run report.

---

Acceptance Criteria

• npm run demo:direct runs without external wallet setup
• npm run demo:chainlens runs in dry-run mode without wallet setup
• With wallet env, demo:chainlens attempts one live ChainLens SDK call
• Live SDK client uses ChainLens, ViemWallet, viem WalletClient
• CHAIN_ID is parsed as number; only 84532 | 8453 accepted
• Dry-run does not claim to write real SDK telemetry
• recommend:broad and recommend:msft show ChainLens and Bazaar sources
• README labels local mock failures as demo-controlled
• No source file imports from ../ChainLens/packages/*
• Direct demo shows no cost ledger, no provider risk memory, no receipt
• ChainLens demo shows settlement difference between success and failure