RFC-002: Nexus UCP Payment Standard (NUPS)

Metadata	Value
Title	Nexus UCP Payment Standard (NUPS)
Version	2.0.0
Status	Final Draft
Author	Cipher & Nexus Architect Team
Created	2026-01-20
Updated	2026-04-01
Integrations	Google UCP, AP2 Agent Protocol, EVM Chains, ISO 20022 Financial Rails

1. Architecture Overview (架构总览)

本协议采用 "Quote-to-Transaction" (报价-交易) 模型。数据流分为两个严格阶段，确保商户接入的轻量化与结算逻辑的严谨性。

Quote Phase (商户侧): 商户生成包含业务单号和 ISO 元数据的”报价”。商户不生成 Nexus ID，也不生成链上 Calldata。
Orchestration Phase (核心侧): Nexus Core 接收报价，分配 nexus_payment_id，解析 DID 路由，生成结算指令。
Settlement Phase (链上): Escrow 合约锁定资金，商户履约后释放，并抛出兼容 ISO 20022 语义的 Event。

v2.0.0 新增：

AP2 Protocol 支持: 作为 Credential Provider 接收 CartMandate / IntentMandate VC，签发 PaymentMandate VC
Multi-Token: 支持 XSGD、USDC 等 ERC-3009 兼容代币
Gasless Settlement: 用户仅签名，Relayer 代付全部 Gas

2. Phase I: Merchant Quote Payload (商户报价载荷)

这是 Merchant Agent 通过 UCP 返回的标准 JSON。

生成工具: @nexus/ucp-adapter SDK。
设计目标: 极简接入，同时携带金融机构所需的 ISO 元数据。

2.1 JSON Schema

json

{
"payment_methods": [
{
"type": "urn:ucp:payment:nexus_v1",
"display_name": "Nexus (USDC)",
"payload": {
// --- A. 商业意图 (Business Intent) ---
"merchant_did": "did:nexus:20250407:trip_com",
"merchant_order_ref": "TRIP-2026-888", // [关键] 商户ERP中的唯一单号
"amount": "530000000", // 整数 (6位精度)
"currency": "USDC", // Nexus 内部资产标识
"chain_id": 20250407,
"expiry": 1768809600,
// --- B. 业务上下文 (Context - User View) ---
// 用于 User Agent 向用户展示明细
"context": {
"summary": "Flight SQ638 (SIN-NRT)",
"ucp_offer_id": "OFFER-XYZ-999",
"line_items": [
{ "name": "Flight Ticket", "qty": 1, "amount": "500000000" },
{ "name": "Tax", "qty": 1, "amount": "30000000" }
]
},
// --- C. ISO 金融元数据 (ISO Metadata - Bank View) --- [OPTIONAL]
// 用于银行系统/ERP 自动对账的语义映射
// MVP 阶段此字段为可选，未来企业版强制要求
"iso_metadata": {  // OPTIONAL in MVP
// 价值锚定层 (Value Layer): 映射到 ISO 4217 (如 USD)
// 目的: 让 SAP/Oracle ERP 能识别这是"美元"业务
"account_currency": "USD",
// 结算资产层 (Settlement Layer): 映射到 ISO 24165 (DTI)
// 目的: 明确具体的数字资产 ID
"asset_identifier": {
"scheme": "ISO24165",
"dti_code": "4H95J0R2X", // USDC DTI Code
"contract": "0xA0b8..."
},
// 债权人信息 (ISO 20022 )
"creditor": {
"name": "Trip.com International",
"bic": "TRIPCNBJ" // 如果有 SWIFT BIC 码
}
},
// --- D. 安全凭证 ---
// 签名覆盖以上所有字段 (含 context hash 和 iso hash)
"signature": "0xMerchantSig..."
}
}
]
}

3. Phase II: Settlement Manifest (结算清单)

当 User Agent 执行聚合支付 (nexus/orchestrateBatch) 时，Nexus Core 返回此对象。这是 User Agent 最终签名的内容。

3.1 JSON Schema

json

{
"type": "urn:ucp:payment:nexus_batch_v1",
"batch_id": "BATCH-ROOT-20260120-001",
"total_amount": "630000000",
// --- A. ID 映射与聚合清单 (The Manifest) ---
// 用于 UI 渲染和用户核对
"manifest": [
{
"index": 0,
"merchant_name": "Trip.com",
// [ID 桥接] Nexus 资金号 <---> 商户业务号
"nexus_payment_id": "NEX-UUID-001", // [NEW] 核心生成的端到端ID
"merchant_order_ref": "TRIP-2026-888", // [OLD] 来自商户Quote
"amount": "530000000",
"summary": "Flight SQ638",
"iso_currency": "USD" // UI显示: $530.00 USD (USDC Settlement)
},
{
"index": 1,
"merchant_name": "Nexus OTC",
"nexus_payment_id": "NEX-UUID-002",
"merchant_order_ref": "OTC-BTC-05",
"amount": "100000000",
"summary": "0.03 ETH"
}
],
// --- B. 链上交互数据 (Transaction Data) ---
"tx_data": {
"to": "0xNexusRouter...",
"chain_id": 20250407,
"data": "0x...", // Encoded batchPay
"value": "0"
}
}

4. ISO 20022 Data Mapping (数据映射标准)

为了兼容金融机构系统，我们将 JSON 字段映射到 ISO 20022 XML 标签 (pacs.008 / pain.001)。

Nexus JSON Field	ISO 20022 XML Tag	业务含义
`nexus_payment_id`	`<EndToEndId>`	端到端标识符。贯穿全链路的唯一流水号。
`merchant_order_ref`	`<RmtInf>/<Ustrd>`	汇款附言。商户 ERP 用于自动销账的单号。
`amount` (converted)	`<InstdAmt>`	入账金额。使用 `iso_metadata.account_currency`。
`iso_metadata.dti`	`<SplmtryData>/<Envlp>`	备注。如 "Settled via DTI:4H95J0R2X"。
`merchant_did`	`<Cdtr>/<Id>/<OrgId>/<Othr>`	债权人 ID。

5. Reconciliation & Events (对账与事件)

智能合约在执行成功后，必须抛出符合 ISO 语义的 Event。

5.1 Solidity Event Definition

solidity

event PaymentProcessed(
// 索引字段 (用于快速过滤)
string indexed merchant_did,
string indexed nexus_payment_id, // 对应 ISO
// 数据字段 (用于业务处理)
string merchant_order_ref, // 对应 ISO
uint256 amount,
address token_address, // 对应 DTI/Contract
string iso_currency_code // e.g. "USD"
);

5.2 商户/银行对账逻辑

监听: 监听 PaymentProcessed。
转换: (可选) 将 Event 数据转换为 ISO 20022 XML 格式导入 ERP。
匹配: * 匹配 merchant_did。

使用 merchant_order_ref 在 ERP 中查找应收账款。
核对 amount。

核销: 标记订单为 PAID。

6. Security Specification (安全规范)

6.1 EIP-712 TypedData

商户 SDK 必须对 Quote 进行签名。

javascript

const types = {
NexusQuote: [
{ name: 'merchant_did', type: 'string' },
{ name: 'merchant_order_ref', type: 'string' },
{ name: 'amount', type: 'uint256' },
{ name: 'currency', type: 'string' },
{ name: 'expiry', type: 'uint256' },
{ name: 'context_hash', type: 'bytes32' }, // Hash(context)
// iso_hash is OPTIONAL — omit when iso_metadata is not provided (MVP)
// { name: 'iso_hash', type: 'bytes32' } // Hash(iso_metadata) [Enterprise only]
]
};

6.2 DID Resolution

Nexus Core 严禁信任前端传入的收款地址。必须使用 merchant_did 调用链上 Registry 合约（或可信缓存）获取真实的 payment_address。

7. AP2 Protocol Extension (v2.0.0 新增)

7.1 概述

Nexus 同时支持原生 NUPS 协议和 Google AP2 (Agent Protocol 2)。当检测到 AP2 请求时，Core 作为 Credential Provider 运行，处理 W3C Verifiable Credential 格式的支付凭证。

7.2 Protocol Detection

typescript

function detectProtocol(body): "ap2" | "nups" {
  if (body.protocol === "ap2") return "ap2";
  if (body.cart_mandates) return "ap2";
  return "nups";  // default: native NUPS
}

7.3 AP2 Verifiable Credential Types

CartMandate VC (Merchant Agent → Nexus)

商户 Agent 签发的购物车授权凭证，包含商品清单和金额：

json

{
  "@context": ["https://www.w3.org/ns/credentials/v2"],
  "type": ["VerifiableCredential", "CartMandate"],
  "issuer": "did:nexus:20250407:demo_flight",
  "credentialSubject": {
    "merchant_did": "did:nexus:20250407:demo_flight",
    "cart_id": "CART-001",
    "total": "530000000",
    "currency": "XSGD",
    "line_items": [
      { "name": "Flight SQ638", "qty": 1, "amount": "500000000" },
      { "name": "Tax", "qty": 1, "amount": "30000000" }
    ],
    "expires_at": "2026-04-01T12:00:00Z",
    "payment_request": {
      "method_data": [
        {
          "supported_methods": "urn:ucp:payment:nexus_v1",
          "data": {
            "credential_provider_did": "did:nexus:20250407:nexuspay-core",
            "display_name": "Nexus (XSGD)"
          }
        }
      ]
    }
  },
  "proof": { "type": "DataIntegrityProof", "cryptosuite": "ecdsa-jcs-2022", "..." : "..." }
}

payment_request.method_data: 遵循 AP2 CartMandate 的 supported_methods 模式。商户通过与 UCP Checkout Session（Section 2.1）相同的 urn:ucp:payment:nexus_v1 标识符声明接受 Nexus 支付。data.credential_provider_did 指明 Nexus Core 作为处理此 CartMandate 的 Credential Provider。

IntentMandate VC (User Agent → Nexus)

用户 Agent 签发的支付意向凭证，包含预算和商户白名单：

json

{
  "@context": ["https://www.w3.org/ns/credentials/v2"],
  "type": ["VerifiableCredential", "IntentMandate"],
  "issuer": "did:key:z6Mk...",
  "credentialSubject": {
    "agent_did": "did:key:z6Mk...",
    "budget": "600000000",
    "currency": "XSGD",
    "merchant_whitelist": ["did:nexus:20250407:demo_flight"],
    "ttl": 3600
  }
}

PaymentMandate VC (Nexus → All Agents)

Nexus 作为 Credential Provider 签发的支付证明，在资金进入 Escrow 后自动生成：

json

{
  "@context": ["https://www.w3.org/ns/credentials/v2"],
  "type": ["VerifiableCredential", "PaymentMandate"],
  "issuer": "did:nexus:20250407:nexuspay-core",
  "credentialSubject": {
    "credential_provider_did": "did:nexus:20250407:nexuspay-core",
    "nexus_payment_id": "PAY-01JAXYZ-0001",
    "group_id": "GRP-001",
    "payer": "0x1234...abcd",
    "total_amount": "530000000",
    "currency": "XSGD",
    "chain_id": 20250407,
    "escrow_contract": "0xeB33a9C2b4c7D3F44Fd5514F90C355AF6bb79236",
    "deposit_tx_hash": "0xabc123...def456"
  },
  "proof": {
    "type": "DataIntegrityProof",
    "cryptosuite": "ecdsa-jcs-2022",
    "verificationMethod": "did:nexus:20250407:nexuspay-core#key-1",
    "proofPurpose": "assertionMethod",
    "created": "2026-04-01T10:35:00Z",
    "proofValue": "..."
  }
}

7.4 NUPS 与 AP2 的关系

维度	NUPS (原生)	AP2
Quote 格式	NUPS JSON + EIP-712 签名	CartMandate VC + Data Integrity Proof
支付凭证	HTTP 402 + BatchDepositInstruction	PaymentMandate VC
链上结算	完全相同 (Escrow Contract)	完全相同
适用场景	MCP Tool 调用	Google Agent 生态

两种协议共享同一个 Escrow 合约和结算流程，仅在 quote 验证和凭证格式上有差异。

8. Multi-Token Support (v2.0.0 新增)

8.1 支持的代币

代币	合约地址	EIP-712 name	EIP-712 version	状态
XSGD	`0x0Fd437613dE3d14F4dDaB8331DC0f2C0C543BdD0`	"XSGD"	"2"	当前活跃
USDC	`0xFF8dEe9983768D0399673014cf77826896F97e4d`	"USD Coin"	"1"	Legacy

8.2 代币切换

Escrow 合约通过 setToken() 管理函数切换活跃代币。切换后：

新存入使用新代币
已有 escrow 不受影响 (使用原代币结算)

8.3 Quote 中的 currency 字段

商户 Quote 中的 currency 字段标识代币符号 (如 "XSGD", "USDC")。Core 根据 currency 查找对应的合约地址和 EIP-712 domain 参数。

RFC-002: Nexus UCP Payment Standard (NUPS) ​

1. Architecture Overview (架构总览) ​

2. Phase I: Merchant Quote Payload (商户报价载荷) ​

2.1 JSON Schema ​

3. Phase II: Settlement Manifest (结算清单) ​

3.1 JSON Schema ​

4. ISO 20022 Data Mapping (数据映射标准) ​

5. Reconciliation & Events (对账与事件) ​

5.1 Solidity Event Definition ​

5.2 商户/银行对账逻辑 ​

6. Security Specification (安全规范) ​

6.1 EIP-712 TypedData ​

6.2 DID Resolution ​

7. AP2 Protocol Extension (v2.0.0 新增) ​

7.1 概述 ​

7.2 Protocol Detection ​

7.3 AP2 Verifiable Credential Types ​

CartMandate VC (Merchant Agent → Nexus) ​

IntentMandate VC (User Agent → Nexus) ​

PaymentMandate VC (Nexus → All Agents) ​

7.4 NUPS 与 AP2 的关系 ​

8. Multi-Token Support (v2.0.0 新增) ​

8.1 支持的代币 ​

8.2 代币切换 ​

8.3 Quote 中的 currency 字段 ​

RFC-002: Nexus UCP Payment Standard (NUPS)

1. Architecture Overview (架构总览)

2. Phase I: Merchant Quote Payload (商户报价载荷)

2.1 JSON Schema

3. Phase II: Settlement Manifest (结算清单)

3.1 JSON Schema

4. ISO 20022 Data Mapping (数据映射标准)

5. Reconciliation & Events (对账与事件)

5.1 Solidity Event Definition

5.2 商户/银行对账逻辑

6. Security Specification (安全规范)

6.1 EIP-712 TypedData

6.2 DID Resolution

7. AP2 Protocol Extension (v2.0.0 新增)

7.1 概述

7.2 Protocol Detection

7.3 AP2 Verifiable Credential Types

CartMandate VC (Merchant Agent → Nexus)

IntentMandate VC (User Agent → Nexus)

PaymentMandate VC (Nexus → All Agents)

7.4 NUPS 与 AP2 的关系

8. Multi-Token Support (v2.0.0 新增)

8.1 支持的代币

8.2 代币切换

8.3 Quote 中的 currency 字段