@lawreneliang/atel-sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ATEL
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,221 @@
+# ATEL SDK
+
+**Agent Trust & Economics Layer** — a TypeScript protocol SDK for building trustworthy, auditable multi-agent systems.
+
+ATEL provides the cryptographic primitives and protocol building blocks that let AI agents collaborate safely: identity verification, scoped consent, policy enforcement, tamper-evident execution traces, Merkle-tree proofs, and reputation scoring.
+
+## Quick Start
+
+```bash
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Run the end-to-end demo
+npx tsx demo/full-demo.ts
+```
+
+Phase 0.5 commands:
+
+```bash
+# Real external API e2e demo
+npm run demo:real
+
+# Testnet anchoring smoke (requires chain env vars)
+npm run smoke:anchor
+
+# Performance baseline
+npm run test:perf
+
+# 5-10 agent continuous run (Phase 0.5)
+npm run run:cluster
+
+# deploy acceptance (service + sync + proof + anchor)
+npm run acceptance:deploy
+```
+
+The demo simulates two agents collaborating on a flight search task, exercising the end-to-end trust workflow.
+
+## Architecture
+
+ATEL is organized into 13 composable modules:
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│                         ATEL SDK                             │
+├──────────┬──────────┬──────────┬──────────┬─────────────────┤
+│ Identity │  Schema  │  Policy  │ Gateway  │      Trace      │
+├──────────┴──────────┴──────────┴──────────┴─────────────────┤
+│ Proof  │ Score │ Graph │ TrustManager │ Rollback │ Anchor    │
+├───────────────────────────────┬──────────────────────────────┤
+│          Orchestrator         │      Trust Score Service     │
+└───────────────────────────────┴──────────────────────────────┘
+```
+
+| Module | Description |
+|--------|-------------|
+| **Identity** | Ed25519 key pairs, DID creation (`did:atel:*`), signing & verification |
+| **Schema** | Task and Capability JSON schemas, validation, factory functions, matching |
+| **Policy** | Consent tokens (scoped, time-limited), policy engine with call tracking |
+| **Gateway** | Central tool invocation gateway with policy enforcement and deterministic hashing |
+| **Trace** | Append-only, hash-chained execution log with auto-checkpoints |
+| **Proof** | Merkle-tree proof bundles with multi-check verification |
+| **Score** | Local trust-score computation based on execution history |
+| **Graph** | Multi-dimensional trust graph, direct/indirect/composite trust |
+| **TrustManager** | Unified score + graph submission and trust query API |
+| **Rollback** | Compensation and rollback execution manager |
+| **Anchor** | Multi-chain proof anchoring (Base/BSC/Solana/Mock) |
+| **Orchestrator** | High-level API wiring task delegation/execution/verify |
+| **Service** | HTTP API for score + graph queries with JSON persistence |
+
+## Trust Modes
+
+ATEL supports two deployment modes that can coexist:
+
+- `Local Mode` (default): execute, prove, verify, and score locally with no network dependency.
+- `Network Mode` (optional): keep local trust updates, and additionally sync summaries to a shared trust service.
+
+This means local capability is never removed when network trust is enabled.
+
+## API Reference
+
+Detailed API guide: `docs/API.md`  
+Start here (one-page onboarding): `docs/START-HERE.md`  
+5-minute quickstart: `docs/QUICKSTART-5MIN.md`  
+Phase 0.5 runbook: `docs/PHASE-0.5.md`
+Service deployment: `docs/SERVICE-DEPLOY.md`
+
+ATEL skill package: `skills/atel/SKILL.md`
+
+### Module 1: Identity
+
+```typescript
+import { AgentIdentity, generateKeyPair, createDID, sign, verify } from '@lawreneliang/atel-sdk';
+
+const agent = new AgentIdentity();
+console.log(agent.did);           // "did:atel:..."
+const sig = agent.sign(payload);
+const ok = agent.verify(payload, sig);
+```
+
+### Module 2: Schema
+
+```typescript
+import { createTask, createCapability, matchTaskToCapability } from '@lawreneliang/atel-sdk';
+
+const task = createTask({
+  issuer: agent.did,
+  intent: { type: 'flight_search', goal: 'Find flights SIN→HND' },
+  risk: { level: 'medium' },
+});
+
+const cap = createCapability({
+  provider: executor.did,
+  capabilities: [{ type: 'flight_search', description: '...' }],
+});
+
+const match = matchTaskToCapability(task, cap);
+```
+
+### Module 3: Policy
+
+```typescript
+import { mintConsentToken, verifyConsentToken, PolicyEngine } from '@lawreneliang/atel-sdk';
+
+const token = mintConsentToken(
+  issuer.did, executor.did,
+  ['tool:http:get', 'data:public_web:read'],
+  { max_calls: 10, ttl_sec: 3600 },
+  'medium',
+  issuer.secretKey,
+);
+
+verifyConsentToken(token, issuer.publicKey);
+
+const engine = new PolicyEngine(token);
+const decision = engine.evaluate(action);  // 'allow' | 'deny' | 'needs_confirm'
+```
+
+### Module 4: Gateway
+
+```typescript
+import { ToolGateway } from '@lawreneliang/atel-sdk';
+
+const gateway = new ToolGateway(policyEngine);
+gateway.registerTool('http.get', async (input) => { /* ... */ });
+
+const result = await gateway.callTool({
+  tool: 'http.get',
+  input: { url: '...' },
+  consentToken: '...',
+});
+// result.output, result.input_hash, result.output_hash
+```
+
+### Module 5: Trace
+
+```typescript
+import { ExecutionTrace } from '@lawreneliang/atel-sdk';
+
+const trace = new ExecutionTrace(taskId, agentIdentity);
+trace.append('TASK_ACCEPTED', { ... });
+trace.append('TOOL_CALL', { ... });
+trace.finalize(result);
+
+const { valid, errors } = trace.verify();
+```
+
+### Module 6: Proof
+
+```typescript
+import { ProofGenerator, ProofVerifier } from '@lawreneliang/atel-sdk';
+
+const gen = new ProofGenerator(trace, identity);
+const bundle = gen.generate(policyRef, consentRef, resultRef);
+
+const report = ProofVerifier.verify(bundle, { trace });
+// report.valid, report.checks, report.summary
+```
+
+### Module 7: Score
+
+```typescript
+import { TrustScoreClient } from '@lawreneliang/atel-sdk';
+
+const client = new TrustScoreClient();
+client.submitExecutionSummary({ executor: did, task_id, success: true, ... });
+
+const report = client.getAgentScore(did);
+// report.trust_score (0-100), report.risk_flags, etc.
+```
+
+## Trust Score Formula
+
+```
+base        = success_rate × 60
+volume      = min(total_tasks / 100, 1) × 15
+risk_bonus  = (high_risk_successes / total) × 15
+consistency = (1 − violation_rate) × 10
+─────────────────────────────────────────
+score       = base + volume + risk_bonus + consistency   (clamped 0–100)
+```
+
+## Current Status (2026-02-13)
+
+- [x] **Phase 0 MVP complete** — 13 modules implemented, core trust workflow end-to-end
+- [x] **241 tests in suite** — unit/integration coverage across modules
+- [x] **Demo coverage** — success path + failure scenarios
+- [ ] **Phase 0.5 validation** — real agents + real external tools + real testnet anchoring
+
+## Roadmap
+
+- [ ] **Phase 0.5** — Internal multi-agent cluster with real API/tool workloads
+- [ ] **Phase 1** — Enterprise pilot + external integration hardening
+- [ ] **Phase 2** — Open SDK access + Trust Score/Graph network rollout
+- [ ] **Phase 3+** — Discovery/Directory and Router/Marketplace layers
+
+## License
+
+MIT

package/dist/anchor/base.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Base Chain Anchor Provider.
+ *
+ * Extends {@link EvmAnchorProvider} with Base-specific defaults.
+ * Base is an EVM-compatible L2 built on the OP Stack.
+ *
+ * Default RPC: https://mainnet.base.org
+ */
+import { EvmAnchorProvider, type EvmAnchorConfig } from './evm.js';
+/**
+ * Anchor provider for the Base chain.
+ */
+export declare class BaseAnchorProvider extends EvmAnchorProvider {
+    /** Default Base mainnet RPC URL */
+    static readonly DEFAULT_RPC_URL = "https://mainnet.base.org";
+    /**
+     * @param config - RPC URL and optional private key.
+     *   If `rpcUrl` is omitted, the Base mainnet default is used.
+     */
+    constructor(config?: Partial<EvmAnchorConfig>);
+}

package/dist/anchor/base.js

@@ -0,0 +1,26 @@
+/**
+ * Base Chain Anchor Provider.
+ *
+ * Extends {@link EvmAnchorProvider} with Base-specific defaults.
+ * Base is an EVM-compatible L2 built on the OP Stack.
+ *
+ * Default RPC: https://mainnet.base.org
+ */
+import { EvmAnchorProvider } from './evm.js';
+/**
+ * Anchor provider for the Base chain.
+ */
+export class BaseAnchorProvider extends EvmAnchorProvider {
+    /** Default Base mainnet RPC URL */
+    static DEFAULT_RPC_URL = 'https://mainnet.base.org';
+    /**
+     * @param config - RPC URL and optional private key.
+     *   If `rpcUrl` is omitted, the Base mainnet default is used.
+     */
+    constructor(config) {
+        super('Base', 'base', {
+            rpcUrl: config?.rpcUrl ?? BaseAnchorProvider.DEFAULT_RPC_URL,
+            privateKey: config?.privateKey,
+        });
+    }
+}

package/dist/anchor/bsc.d.ts

@@ -0,0 +1,20 @@
+/**
+ * BSC (BNB Smart Chain) Anchor Provider.
+ *
+ * Extends {@link EvmAnchorProvider} with BSC-specific defaults.
+ *
+ * Default RPC: https://bsc-dataseed.binance.org
+ */
+import { EvmAnchorProvider, type EvmAnchorConfig } from './evm.js';
+/**
+ * Anchor provider for the BSC chain.
+ */
+export declare class BSCAnchorProvider extends EvmAnchorProvider {
+    /** Default BSC mainnet RPC URL */
+    static readonly DEFAULT_RPC_URL = "https://bsc-dataseed.binance.org";
+    /**
+     * @param config - RPC URL and optional private key.
+     *   If `rpcUrl` is omitted, the BSC mainnet default is used.
+     */
+    constructor(config?: Partial<EvmAnchorConfig>);
+}

package/dist/anchor/bsc.js

@@ -0,0 +1,25 @@
+/**
+ * BSC (BNB Smart Chain) Anchor Provider.
+ *
+ * Extends {@link EvmAnchorProvider} with BSC-specific defaults.
+ *
+ * Default RPC: https://bsc-dataseed.binance.org
+ */
+import { EvmAnchorProvider } from './evm.js';
+/**
+ * Anchor provider for the BSC chain.
+ */
+export class BSCAnchorProvider extends EvmAnchorProvider {
+    /** Default BSC mainnet RPC URL */
+    static DEFAULT_RPC_URL = 'https://bsc-dataseed.binance.org';
+    /**
+     * @param config - RPC URL and optional private key.
+     *   If `rpcUrl` is omitted, the BSC mainnet default is used.
+     */
+    constructor(config) {
+        super('BSC', 'bsc', {
+            rpcUrl: config?.rpcUrl ?? BSCAnchorProvider.DEFAULT_RPC_URL,
+            privateKey: config?.privateKey,
+        });
+    }
+}

package/dist/anchor/evm.d.ts

@@ -0,0 +1,67 @@
+/**
+ * EVM Anchor Provider — shared base class for EVM-compatible chains.
+ *
+ * Anchors a hash by sending a zero-value transaction to the signer's
+ * own address with the hash encoded in the `data` field. This is the
+ * simplest on-chain timestamping approach — no contract deployment needed.
+ *
+ * Both {@link BaseAnchorProvider} and {@link BSCAnchorProvider} extend this class.
+ *
+ * @remarks
+ * ⚠️ SECURITY: The `privateKey` is used to sign transactions.
+ * Never hard-code private keys in source code. Use environment variables
+ * or a secure vault in production.
+ */
+import { ethers } from 'ethers';
+import type { AnchorProvider, AnchorRecord, AnchorVerification } from './index.js';
+/** Configuration for an EVM-based anchor provider */
+export interface EvmAnchorConfig {
+    /** JSON-RPC endpoint URL */
+    rpcUrl: string;
+    /**
+     * Hex-encoded private key for signing transactions.
+     * Optional — if omitted the provider can only verify / lookup.
+     *
+     * ⚠️ SECURITY: Keep this value secret. Load from env vars or a vault.
+     */
+    privateKey?: string;
+}
+/**
+ * Abstract EVM anchor provider.
+ *
+ * Subclasses only need to supply `name`, `chain`, and a default RPC URL.
+ */
+export declare class EvmAnchorProvider implements AnchorProvider {
+    readonly name: string;
+    readonly chain: string;
+    /** Ethers JSON-RPC provider (read-only access) */
+    protected readonly provider: ethers.JsonRpcProvider;
+    /** Wallet for signing (undefined when no private key is supplied) */
+    protected readonly wallet?: ethers.Wallet;
+    /**
+     * @param name - Human-readable provider name.
+     * @param chain - Chain identifier.
+     * @param config - RPC URL and optional private key.
+     */
+    constructor(name: string, chain: string, config: EvmAnchorConfig);
+    /**
+     * Encode a hash string into the hex data payload for a transaction.
+     *
+     * Format: `0x` + hex(ATEL_ANCHOR:<hash>)
+     */
+    static encodeData(hash: string): string;
+    /**
+     * Decode the hash from a transaction data field.
+     *
+     * @returns The decoded hash, or `null` if the data doesn't match the expected format.
+     */
+    static decodeData(data: string): string | null;
+    /** @inheritdoc */
+    anchor(hash: string, metadata?: Record<string, unknown>): Promise<AnchorRecord>;
+    /** @inheritdoc */
+    verify(hash: string, txHash: string): Promise<AnchorVerification>;
+    /** @inheritdoc */
+    lookup(hash: string): Promise<AnchorRecord[]>;
+    /** @inheritdoc */
+    isAvailable(): Promise<boolean>;
+}

package/dist/anchor/evm.js

@@ -0,0 +1,176 @@
+/**
+ * EVM Anchor Provider — shared base class for EVM-compatible chains.
+ *
+ * Anchors a hash by sending a zero-value transaction to the signer's
+ * own address with the hash encoded in the `data` field. This is the
+ * simplest on-chain timestamping approach — no contract deployment needed.
+ *
+ * Both {@link BaseAnchorProvider} and {@link BSCAnchorProvider} extend this class.
+ *
+ * @remarks
+ * ⚠️ SECURITY: The `privateKey` is used to sign transactions.
+ * Never hard-code private keys in source code. Use environment variables
+ * or a secure vault in production.
+ */
+import { ethers } from 'ethers';
+/**
+ * Prefix prepended to the hash in the transaction data field
+ * so anchored transactions are easily identifiable.
+ */
+const ANCHOR_PREFIX = 'ATEL_ANCHOR:';
+/**
+ * Abstract EVM anchor provider.
+ *
+ * Subclasses only need to supply `name`, `chain`, and a default RPC URL.
+ */
+export class EvmAnchorProvider {
+    name;
+    chain;
+    /** Ethers JSON-RPC provider (read-only access) */
+    provider;
+    /** Wallet for signing (undefined when no private key is supplied) */
+    wallet;
+    /**
+     * @param name - Human-readable provider name.
+     * @param chain - Chain identifier.
+     * @param config - RPC URL and optional private key.
+     */
+    constructor(name, chain, config) {
+        this.name = name;
+        this.chain = chain;
+        this.provider = new ethers.JsonRpcProvider(config.rpcUrl);
+        if (config.privateKey) {
+            // ⚠️ SECURITY: The wallet holds the private key in memory.
+            this.wallet = new ethers.Wallet(config.privateKey, this.provider);
+        }
+    }
+    /**
+     * Encode a hash string into the hex data payload for a transaction.
+     *
+     * Format: `0x` + hex(ATEL_ANCHOR:<hash>)
+     */
+    static encodeData(hash) {
+        return ethers.hexlify(ethers.toUtf8Bytes(`${ANCHOR_PREFIX}${hash}`));
+    }
+    /**
+     * Decode the hash from a transaction data field.
+     *
+     * @returns The decoded hash, or `null` if the data doesn't match the expected format.
+     */
+    static decodeData(data) {
+        try {
+            const text = ethers.toUtf8String(data);
+            if (text.startsWith(ANCHOR_PREFIX)) {
+                return text.slice(ANCHOR_PREFIX.length);
+            }
+            return null;
+        }
+        catch {
+            return null;
+        }
+    }
+    /** @inheritdoc */
+    async anchor(hash, metadata) {
+        if (!this.wallet) {
+            throw new Error(`${this.name}: Cannot anchor without a private key`);
+        }
+        const data = EvmAnchorProvider.encodeData(hash);
+        try {
+            const tx = await this.wallet.sendTransaction({
+                to: this.wallet.address,
+                value: 0n,
+                data,
+            });
+            const receipt = await tx.wait();
+            if (!receipt) {
+                throw new Error('Transaction receipt is null — tx may have been dropped');
+            }
+            return {
+                hash,
+                txHash: receipt.hash,
+                chain: this.chain,
+                timestamp: Date.now(),
+                blockNumber: receipt.blockNumber,
+                metadata,
+            };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            throw new Error(`${this.name} anchor failed: ${message}`);
+        }
+    }
+    /** @inheritdoc */
+    async verify(hash, txHash) {
+        try {
+            const tx = await this.provider.getTransaction(txHash);
+            if (!tx) {
+                return {
+                    valid: false,
+                    hash,
+                    txHash,
+                    chain: this.chain,
+                    detail: 'Transaction not found',
+                };
+            }
+            const decoded = EvmAnchorProvider.decodeData(tx.data);
+            if (decoded === null) {
+                return {
+                    valid: false,
+                    hash,
+                    txHash,
+                    chain: this.chain,
+                    detail: 'Transaction data does not contain a valid anchor',
+                };
+            }
+            const valid = decoded === hash;
+            // Try to get block timestamp
+            let blockTimestamp;
+            if (tx.blockNumber) {
+                try {
+                    const block = await this.provider.getBlock(tx.blockNumber);
+                    blockTimestamp = block ? block.timestamp * 1000 : undefined;
+                }
+                catch {
+                    // Non-critical — skip timestamp
+                }
+            }
+            return {
+                valid,
+                hash,
+                txHash,
+                chain: this.chain,
+                blockTimestamp,
+                detail: valid
+                    ? 'Hash matches on-chain data'
+                    : `Hash mismatch: expected "${hash}", found "${decoded}"`,
+            };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return {
+                valid: false,
+                hash,
+                txHash,
+                chain: this.chain,
+                detail: `Verification error: ${message}`,
+            };
+        }
+    }
+    /** @inheritdoc */
+    async lookup(hash) {
+        // On-chain lookup without an indexer is not feasible for EVM chains.
+        // In production, integrate with a subgraph or event indexer.
+        // For now, return an empty array — local records are managed by AnchorManager.
+        return [];
+    }
+    /** @inheritdoc */
+    async isAvailable() {
+        try {
+            await this.provider.getBlockNumber();
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+}