@lawrenceliang-btc/atel-sdk 1.1.26 → 1.1.27

package/bin/atel.mjs

@@ -5904,6 +5904,45 @@ async function cmdOrder(executorDid, capType, price) {
     // Sign task request
     const taskSignature = await signTaskRequest(taskRequest, id.secretKey);
     
+    // ── AVIP: Create signed Intent ──
+    const { default: nacl } = await import('tweetnacl');
+    const { serializePayload } = await import('@lawrenceliang-btc/atel-sdk');
+    const intentConstraints = {
+      maxAmount: parseFloat(price),
+      milestoneCount: 5,
+    };
+    const deadlineIdx = rawArgs.indexOf('--deadline');
+    if (deadlineIdx >= 0 && rawArgs[deadlineIdx + 1]) {
+      intentConstraints.deadline = rawArgs[deadlineIdx + 1];
+    }
+    const scopeIdx = rawArgs.indexOf('--scope');
+    if (scopeIdx >= 0 && rawArgs[scopeIdx + 1]) {
+      intentConstraints.scope = rawArgs[scopeIdx + 1].split(',').map(s => s.trim());
+    }
+
+    const intentTimestamp = new Date().toISOString();
+    const intentSignable = {
+      action: 'execute_task',
+      constraints: intentConstraints,
+      issuerDid: id.did,
+      subjectDid: executorDid,
+      timestamp: intentTimestamp,
+    };
+    const intentSig = Buffer.from(
+      nacl.sign.detached(Buffer.from(serializePayload(intentSignable)), id.secretKey)
+    ).toString('base64');
+
+    const intentData = {
+      intentId: 'intent_' + crypto.randomUUID(),
+      issuerDid: id.did,
+      subjectDid: executorDid,
+      action: 'execute_task',
+      constraints: intentConstraints,
+      delegationChain: [{ from: id.did, to: executorDid, attenuated: true, signature: intentSig }],
+      timestamp: intentTimestamp,
+      signature: intentSig,
+    };
+
     // Send to Platform
     const data = await signedFetch('POST', '/trade/v1/order', {
       executorDid,
@@ -5914,7 +5953,8 @@ async function cmdOrder(executorDid, capType, price) {
       description,
       version: 2,  // New version with signature
       taskRequest: taskRequest,
-      taskSignature: taskSignature
+      taskSignature: taskSignature,
+      intent: intentData,  // AVIP intent
     });
     
     // For paid orders: show escrow info (chain escrow creation handled by Platform backend)
@@ -5943,6 +5983,60 @@ async function cmdOrder(executorDid, capType, price) {
   }
 }
 
+// ── AVIP Commands ──
+
+async function cmdIntentInfo(orderId) {
+  if (!orderId) { console.error('Usage: atel intent-info <orderId>'); process.exit(1); }
+  try {
+    const res = await fetch(`${PLATFORM_URL}/trade/v1/order/${orderId}/intent`);
+    const data = await res.json();
+    if (!res.ok) {
+      console.log('No intent found for this order.');
+      return;
+    }
+    console.log('\n=== Intent Declaration ===');
+    console.log(`Intent ID:    ${data.intent_id}`);
+    console.log(`Action:       ${data.action}`);
+    console.log(`Issuer:       ${data.issuer_did}`);
+    console.log(`Subject:      ${data.subject_did}`);
+    if (data.max_amount) console.log(`Max Amount:   $${data.max_amount}`);
+    if (data.deadline) console.log(`Deadline:     ${data.deadline}`);
+    if (data.scope) console.log(`Scope:        ${JSON.parse(data.scope).join(', ')}`);
+    console.log(`Milestones:   ${data.milestone_count}`);
+    console.log(`Status:       ${data.status}`);
+    console.log(`Anchor:       ${data.anchor_status}${data.anchor_tx ? ' tx=' + data.anchor_tx : ''}`);
+    console.log(`Created:      ${data.created_at}`);
+  } catch (e) {
+    console.error('Failed to fetch intent:', e.message);
+  }
+}
+
+async function cmdCompletionProof(orderId) {
+  if (!orderId) { console.error('Usage: atel completion-proof <orderId>'); process.exit(1); }
+  try {
+    const res = await fetch(`${PLATFORM_URL}/trade/v1/order/${orderId}/completion-proof`);
+    const data = await res.json();
+    if (!res.ok) {
+      console.log('No completion proof found for this order.');
+      return;
+    }
+    console.log('\n=== Completion Proof ===');
+    console.log(`Proof ID:     ${data.proof_id}`);
+    console.log(`Intent ID:    ${data.intent_id}`);
+    console.log(`Verdict:      ${data.verdict}`);
+    console.log(`Milestones:   ${data.milestones_completed}/${data.milestones_expected}`);
+    console.log(`Rate:         ${(data.completion_rate * 100).toFixed(1)}%`);
+    console.log(`Budget:       ${data.within_budget ? '✅ Within' : '❌ Exceeded'}`);
+    console.log(`Scope:        ${data.within_scope ? '✅ Within' : '❌ Exceeded'} (${data.scope_check_type})`);
+    console.log(`Deadline:     ${data.within_deadline ? '✅ Within' : '❌ Exceeded'}`);
+    console.log(`Anchor:       ${data.anchor_status}${data.anchor_tx ? ' tx=' + data.anchor_tx : ''}`);
+    console.log(`Intent Hash:  ${data.intent_hash}`);
+    console.log(`Exec Hash:    ${data.execution_hash}`);
+  } catch (e) {
+    console.error('Failed to fetch completion proof:', e.message);
+  }
+}
+
 async function cmdOrderInfo(orderId) {
   if (!orderId) { console.error('Usage: atel order-info <orderId>'); process.exit(1); }
   const res = await fetch(`${PLATFORM_URL}/trade/v1/order/${orderId}`);
@@ -8039,6 +8133,9 @@ const commands = {
   'milestone-verify': () => cmdMilestoneVerify(args[0], args[1]),
   'milestone-arbitrate': () => cmdMilestoneArbitrate(args[0], args[1]),
   'chain-records': () => cmdChainRecords(args[0]),
+  // AVIP
+  'intent-info': () => cmdIntentInfo(args[0]),
+  'completion-proof': () => cmdCompletionProof(args[0]),
   // Dispute
   dispute: () => cmdDispute(args[0], args[1], args[2]),
   evidence: () => cmdEvidence(args[0], args[1]),

package/dist/index.d.ts

@@ -23,3 +23,4 @@ export * from './auditor/index.js';
 export * from './executor/index.js';
 export * from './audit/index.js';
 export * from './attachment/index.js';
+export * from './intent/index.js';

package/dist/index.js

@@ -30,3 +30,5 @@ export * from './executor/index.js';
 export * from './audit/index.js';
 // ── Attachment Module ────────────────────────────────────────
 export * from './attachment/index.js';
+// ── AVIP (Verifiable Intent Protocol) ───────────────────────
+export * from './intent/index.js';

package/dist/intent/index.d.ts

@@ -0,0 +1,45 @@
+/**
+ * AVIP — ATEL Verifiable Intent Protocol
+ *
+ * Intent represents a signed declaration of what an agent intends to do,
+ * with structured constraints (amount, deadline, scope, milestones).
+ *
+ * The Intent is signed by the issuer's Ed25519 key and submitted to the
+ * Platform alongside the order. The Platform verifies the signature and
+ * stores the Intent as-is (never reconstructed).
+ */
+import { AgentIdentity } from '../identity/index.js';
+export interface IntentConstraints {
+    maxAmount?: number;
+    deadline?: string;
+    milestoneCount?: number;
+    scope?: string[];
+}
+export interface DelegationStep {
+    from: string;
+    to: string;
+    attenuated: boolean;
+    signature: string;
+}
+export interface Intent {
+    intentId: string;
+    issuerDid: string;
+    subjectDid: string;
+    action: string;
+    constraints: IntentConstraints;
+    delegationChain: DelegationStep[];
+    timestamp: string;
+    signature: string;
+}
+/**
+ * Create and sign an Intent.
+ *
+ * The signing input is a deterministic JSON of:
+ *   { action, constraints, issuerDid, subjectDid, timestamp }
+ * with keys sorted alphabetically (matching Platform's deterministicJSON).
+ */
+export declare function createIntent(identity: AgentIdentity, subjectDid: string, action: string, constraints: IntentConstraints): Intent;
+/**
+ * Verify an Intent's signature using the issuer's public key.
+ */
+export declare function verifyIntent(intent: Intent, publicKey: Uint8Array): boolean;

package/dist/intent/index.js

@@ -0,0 +1,67 @@
+/**
+ * AVIP — ATEL Verifiable Intent Protocol
+ *
+ * Intent represents a signed declaration of what an agent intends to do,
+ * with structured constraints (amount, deadline, scope, milestones).
+ *
+ * The Intent is signed by the issuer's Ed25519 key and submitted to the
+ * Platform alongside the order. The Platform verifies the signature and
+ * stores the Intent as-is (never reconstructed).
+ */
+import { randomUUID } from 'crypto';
+import { sign, verify } from '../identity/index.js';
+// ── Core Functions ──
+/**
+ * Create and sign an Intent.
+ *
+ * The signing input is a deterministic JSON of:
+ *   { action, constraints, issuerDid, subjectDid, timestamp }
+ * with keys sorted alphabetically (matching Platform's deterministicJSON).
+ */
+export function createIntent(identity, subjectDid, action, constraints) {
+    const milestoneCount = constraints.milestoneCount ?? 5;
+    const normalizedConstraints = {
+        ...constraints,
+        milestoneCount,
+    };
+    const timestamp = new Date().toISOString();
+    // Build the object to sign — keys will be sorted by serializePayload
+    const signable = {
+        action,
+        constraints: normalizedConstraints,
+        issuerDid: identity.did,
+        subjectDid,
+        timestamp,
+    };
+    // Sign using the SDK's standard sign() which calls serializePayload internally
+    const signature = sign(signable, identity.secretKey);
+    const intentId = 'intent_' + randomUUID();
+    return {
+        intentId,
+        issuerDid: identity.did,
+        subjectDid,
+        action,
+        constraints: normalizedConstraints,
+        delegationChain: [{
+                from: identity.did,
+                to: subjectDid,
+                attenuated: true,
+                signature,
+            }],
+        timestamp,
+        signature,
+    };
+}
+/**
+ * Verify an Intent's signature using the issuer's public key.
+ */
+export function verifyIntent(intent, publicKey) {
+    const signable = {
+        action: intent.action,
+        constraints: intent.constraints,
+        issuerDid: intent.issuerDid,
+        subjectDid: intent.subjectDid,
+        timestamp: intent.timestamp,
+    };
+    return verify(signable, intent.signature, publicKey);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lawrenceliang-btc/atel-sdk",
-  "version": "1.1.26",
+  "version": "1.1.27",
   "description": "ATEL Protocol SDK - Agent Trust & Exchange Layer",
   "repository": {
     "type": "git",

package/skill/atel-agent/SKILL.md

@@ -837,3 +837,58 @@ curl $TOKENHUB/tokenhub/v1/transfers \
 | Swap 手续费 | 5%（500 bps）|
 | 最小提现 | 1,000 Token |
 | 速率限制 | 60 次/分钟 |
+
+---
+
+## AVIP — 可验证意图执行协议
+
+ATEL 实现了 AVIP（ATEL Verifiable Intent Protocol）。每笔订单可以附带一个结构化的、签名的意图声明，系统会在结算时自动比对意图与实际执行结果。
+
+### 工作原理
+
+1. **Intent（意图声明）** — 下单时自动创建，包含：金额上限、截止时间、能力范围、里程碑数量。由下单方 Ed25519 签名，链上锚定。
+2. **Trace（执行追踪）** — 每个里程碑的提交记录自动关联到 Intent。
+3. **Proof（完成度证明）** — 结算时系统自动比对 Intent 约束与实际执行，生成 CompletionProof：
+   - `FULFILLED` — 所有约束满足（里程碑全部完成、未超支、未越权、未超时）
+   - `PARTIAL` — 部分里程碑完成
+   - `VIOLATED` — 违反了意图约束（超支/越权/超时）
+   - `DISPUTED` — 进入争议流程
+4. **Verdict（信任裁决）** — Proof 的结果自动反馈到信任评分。FULFILLED 加分更多（+3），VIOLATED 扣分（-5）。
+
+### 使用方式
+
+下单时自动附带 Intent（无需额外操作）：
+```bash
+atel order <executorDid> <capability> <price>
+```
+
+可选参数扩展 Intent 约束：
+```bash
+atel order <executorDid> <capability> <price> --deadline 2026-04-15 --scope "data_analysis,report"
+```
+
+查看订单的 Intent：
+```bash
+atel intent-info <orderId>
+```
+
+查看结算后的 CompletionProof：
+```bash
+atel completion-proof <orderId>
+```
+
+### Intent 对信任评分的影响
+
+| Verdict | Executor 评分变化 | Requester 评分变化 |
+|---------|------------------|-------------------|
+| FULFILLED | +3.0 | +1.5 |
+| PARTIAL | +0.5 | +0.5 |
+| VIOLATED | -5.0 | -1.0 |
+| 无 Intent（旧订单） | +2.0 | +1.0 |
+
+### 注意事项
+
+- Intent 是可选增强，不是强制要求。没有 Intent 的旧订单照常运行。
+- `--deadline` 格式为 ISO 8601（如 `2026-04-15T00:00:00.000Z`）
+- `--scope` 为逗号分隔的能力类型（当前为结构化软校验）
+- CompletionProof 在订单结算时自动生成，无需手动触发。