feat(runtime): mock-L1 auction MVP round 3 on-chain settle

Archive can post MockDleAuctionSettlement.settle after list escrow; add mock-auction-e2e, settle helper, and RULES/docs honesty for demo vs real txHash.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: CoNETProject

docs/mock-l1-auction-mvp.md

@@ -28,19 +28,28 @@ CoNET mainnet may already host `DLEChainRegistry1155V1`; this MVP still uses **l
 | Local deploy script | `scripts/dle/deployMockL1AuctionLocal.ts` (`npm run dle:deploy:mock-auction-local`) |
 | Registration wire | `runtime/src/shared/mockL1.ts` |
 | Custody (Archive) | `runtime/src/shared/mockL1Custody.ts` (`MOCK_L1_RPC_URL` + `MOCK_L1_SETTLEMENT`) |
+| On-chain settle | `runtime/src/shared/mockL1Settle.ts` (`MOCK_L1_AUTHORITY_PRIVATE_KEY` + `MOCK_L1_SETTLE_ONCHAIN` / `executeOnChain`) |
 | Orders / cert wire | `runtime/src/shared/tradeMatch.ts` |
 | HTTP engines | `runtime/src/archive/mockL1/engine.ts`, `…/trade/engine.ts` |
 | Mode A | `runtime/src/archive/bft/modeA.ts` → `replayTradeMatchModeA` |
-| CLI / demo | `runtime/src/daemon/mock-l1-auction-cli.ts`, `mock-l1-auction-demo.ts` |
+| CLI / demo / e2e | `runtime/src/daemon/mock-l1-auction-cli.ts`, `mock-l1-auction-demo.ts`, `mock-l1-auction-e2e.ts` |
+| One-shot local | Root `scripts/dle/mockAuctionE2eLocal.sh` → `npm run dle:mock-auction-e2e` |
 | Web | Explorer `/mock-auction` (session keys may sign; Archive-side custody when RPC set) |
 
 ## MVP round 2 (2026-08)
 
 1. Archive `POST /trade/check` verifies NFT `ownerOf` + `getApproved`/`isApprovedForAll` and ERC-20 `balanceOf` + `allowance` against the mock settlement when RPC env is set (client custody flags ignored).
-2. `npm run mock-auction-demo` runs submit→scan→candidate→check→attest→settle in-process.
+2. `npm run mock-auction-demo` runs submit→scan→candidate→check→attest→settle in-process (**lab / optional custody**; settle may use a demo txHash when on-chain settle is off).
 3. Explorer can sign sell/buy with memory-only session keys (no disk persistence).
 4. Root `dle:deploy:mock-auction-local` prints `MOCK_L1_*` for Archive.
 
+## MVP round 3 (2026-08)
+
+1. Seller `list`s NFT into `MockDleAuctionSettlement` escrow before Archive settle.
+2. Archive `POST /trade/settle` with `executeOnChain` / env → `certificateAuthority` calls `settle` on local RPC; phases `match_certified` → `settlement_submitted` → `settled` | `settlement_failed`.
+3. `npm run mock-auction-e2e` (DLE) or root `npm run dle:mock-auction-e2e` (hardhat node → deploy → e2e) produces a **real** `settlementTxHash`.
+4. `/health` may expose `tradeOnChainSettleConfigured` / `tradeOnChainSettleMode`.
+
 ## Fee
 
 ```

explorer/RULES.md

@@ -106,10 +106,12 @@ Detail page (footer hidden). Local mock-L1 `/mockl1/*` + `/trade/*` against the
 
 **MVP round 2:** session-only lab private keys may **sign** sell/buy/attest in the browser (`ethers`); keys are **never** written to localStorage / IndexedDB. Order / candidate hashing is mirrored in `explorer/src/lib/mockAuctionWire.ts` (no runtime import). Archive legality remains Archive-side when RPC custody is configured — the page may pass lab flags only for Archive without `MOCK_L1_*`.
 
+**MVP round 3:** when Archive has on-chain settle configured, match timeline may show a **real** `settlementTxHash` from `MockDleAuctionSettlement.settle` (local Hardhat/Anvil). Do **not** paint lab demo fake hashes as mainnet settles. UI still does **not** call `settle` from the browser — Archive posts the authority tx.
+
 | Rule | Detail |
 |---|---|
 | Scope | Local Hardhat/Anvil mock network only |
-| UI | May sign client orders/attests with session keys; does **not** self-claim Archive legality / quorum |
+| UI | May sign client orders/attests with session keys; does **not** self-claim Archive legality / quorum; does **not** submit settlement txs |
 | Labels | Always show `mockL1Only` / `notProductionDepin` pills |
 | Forbidden | Painting as CoNET mainnet, production DePIN, or live CL RANDAO; persisting private keys |
 

package.json

@@ -54,7 +54,8 @@
     "lab:keep-p11-joiner": "npm run runtime:build && npm --prefix pilot run lab:keep-p11-joiner",
     "lab:deploy-p11-joiner": "npm run runtime:build && npm --prefix pilot run lab:deploy-p11-joiner",
     "lab:accept-p11-join": "npm --prefix pilot run lab:accept-p11-join",
-    "lab:p11-full-open-join": "npm run runtime:build && npm --prefix pilot run lab:p11-full-open-join"
+    "lab:p11-full-open-join": "npm run runtime:build && npm --prefix pilot run lab:p11-full-open-join",
+    "mock-auction-e2e": "tsx runtime/src/daemon/mock-l1-auction-e2e.ts"
   },
   "dependencies": {
     "ethers": "^6.15.0"

runtime/README.md

@@ -61,6 +61,6 @@ P1 联网 BFT（独立包 `runtime/src/archive/bft`）：5 个 active 对冻结
 - `POST /bft/message` / `GET /bft/status` — 实验室 prevote/precommit 交换（复用 27101）
 - `GET /ondemand/pool` / `GET /ondemand/selection` / `POST /ondemand/hook` / `POST /ondemand/freeze` / `POST /ondemand/message` — 实验室等待池与 SelectionLog（复用 27101）
 - `POST /newchain/request` / `GET /newchain/chains` — 实验室 Mode A 三类新链创世；新 \(Q_V\) 为 EIP-712 `ArchiveValidatorQuorumAttest`（**P18**；**不是** 生产 secp256k1 / L1 NFT / 30 天资格）。随机用户：`70.35.205.77:/home/peter/dle-newchain-user`（`npm run lab:deploy-newchain-user`）
-- `POST /mockl1/register` / `GET /mockl1/chains` + `POST /trade/*` — **Mock-L1 拍卖 MVP**（本地 Hardhat/Anvil ERC-1155 真实 `tokenId`；**禁止**把 lab `notL1Nft` 升格；**禁止**用 WaitingPool / `POST /ondemand/hook` 当 trade ingress）。CLI：`npm run mock-auction-cli`；一键演示：`npm run mock-auction-demo`。Archive 可选 RPC custody：`MOCK_L1_RPC_URL` + `MOCK_L1_SETTLEMENT`。设计 / wire：`docs/mock-l1-auction-mvp.md`、`docs/mock-l1-auction-wire.md`。Explorer：`/mock-auction`（会话密钥可签名，不落盘）。**不是** CoNET 主网接线，**不是** 生产 CL RANDAO / DePIN。
+- `POST /mockl1/register` / `GET /mockl1/chains` + `POST /trade/*` — **Mock-L1 拍卖 MVP**（本地 Hardhat/Anvil ERC-1155 真实 `tokenId`；**禁止**把 lab `notL1Nft` 升格；**禁止**用 WaitingPool / `POST /ondemand/hook` 当 trade ingress）。CLI：`npm run mock-auction-cli`；演示：`npm run mock-auction-demo`；真上链 settle：`npm run mock-auction-e2e`（需 `MOCK_L1_*`；根仓一键 `npm run dle:mock-auction-e2e`）。Archive 可选 RPC custody：`MOCK_L1_RPC_URL` + `MOCK_L1_SETTLEMENT`；on-chain settle：`MOCK_L1_AUTHORITY_PRIVATE_KEY` + `MOCK_L1_SETTLE_ONCHAIN`。设计 / wire：`docs/mock-l1-auction-mvp.md`、`docs/mock-l1-auction-wire.md`。Explorer：`/mock-auction`（会话密钥可签名，不落盘；不代签 settle）。**不是** CoNET 主网接线，**不是** 生产 CL RANDAO / DePIN。
 
 本地 UI：`npm run explorer:dev`（见 `explorer/README.md`）。Home / Certificates 展示 waiting pool、`poolRoot`、7+2、`endorsed`；首屏 seed 七主机 P3 验收，仅可信 live 覆盖。`eth_chainId` 仍是 CoNET-DLE Testnet `0x44c45`，不是 L1 `224422`。`liveGroupIds` 含引导组 L1 登记交易 hash；实验室 M6 另含 G2 L1 `registerLiveGroup` tx（Home Clusters 下打开 Blockscout `/tx/`；实验室 keccak 仅为别名）。`dle_locateHash` 在 \(G_e \ge 2\) 走 `locatePlane`；全平面 JSON-RPC `null` 仅当每个活跃组都返回可信本组 `notFound`。一组超时是 `unavailable`，不是 `null`。实验室 M7：`tipStateRoot` / `membershipRoot` 为一等 `HashObjectKind`，命中返回 typed 对象而不是 AC；同 hash 后一 height 为 first-write-wins；`ZERO32` 不编目。这 **不是** 30 天资格。

runtime/RULES.md

@@ -111,12 +111,12 @@ Independent of NFT 42 Tendermint / `bft-state.json`. **Not** an L1 birth certifi
 | `POST /trade/scan` / `POST /trade/candidate` | Scanner proposes `MockL1MatchCandidateV1` only |
 | `POST /trade/check` | Archive legality: when `MOCK_L1_RPC_URL` + `MOCK_L1_SETTLEMENT` (or `verifyL1Custody` hook) are set, **eth_call / hook custody** — client `l1EscrowCustody` flags are **ignored**. Otherwise lab flags fallback. Then freeze-then-draw → propose `TradeMatchCertificateV1` |
 | `POST /trade/attest` | Committee signatures (lab keccak beacon; `notProductionBeacon`) |
-| `POST /trade/settle` | Mode A settlement states; mock L1 atomic settle is separate |
+| `POST /trade/settle` | Mode A settlement states. **MVP round 3:** `executeOnChain: true` / `MOCK_L1_SETTLE_ONCHAIN` / `submitL1SettlementTx` hook → authority calls `MockDleAuctionSettlement.settle` (seller must have `list`ed first). Success → `settlement_submitted` → `settled` with real `settlementTxHash`; failure → `settlement_failed` |
 | `GET /trade/orders` / `/trade/matches` / `/trade/timeline` | Read-only status |
 
 Fee: **1 bps** of clearing price; **50% scanner / 50% committee**. Mode A events `0x1302–0x1306` (MatchProposed → … → Settled / SettlementFailed); keep `TradeOpened` (`0x1301`) replay compatible.
 
-`/health` may expose `tradeRpcCustodyConfigured` / `tradeRpcCustodyMode` (`rpc` | `hook` | `clientFlags`). **MVP round 2 (2026-08):** Archive-side custody via `shared/mockL1Custody.ts`; in-process demo `npm run mock-auction-demo`.
+`/health` may expose `tradeRpcCustodyConfigured` / `tradeRpcCustodyMode` (`rpc` | `hook` | `clientFlags`) and `tradeOnChainSettleConfigured` / `tradeOnChainSettleMode`. **MVP round 2 (2026-08):** Archive-side custody via `shared/mockL1Custody.ts`; in-process demo `npm run mock-auction-demo`. **MVP round 3 (2026-08):** on-chain settle via `shared/mockL1Settle.ts`; E2E `npm run mock-auction-e2e` (needs `MOCK_L1_*`); root one-shot `npm run dle:mock-auction-e2e` (hardhat node → deploy → e2e).
 
 Live keep evidence (2026-08-16): `pilot/evidence/conet-dle-p6-genesis-2026-08/p6-live-accept.json` — trade `chainNftId=326990096`, 7/7 `DleLabArchiveCertificateV1` in ~10s, NFT 42 `eth_blockNumber` stayed `0x1`, `liveGroupCount=2`. Completing P6 is **not** 30-day qualification.
 

runtime/src/archive/trade/engine.ts

@@ -15,6 +15,7 @@ import {
 import type { Hex } from '../../shared/bytes.js'
 import { mockL1FeePolicyHash } from '../../shared/mockL1.js'
 import { mockL1CustodyEnv, verifyMockL1Custody } from '../../shared/mockL1Custody.js'
+import { mockL1SettleEnv, settleMockL1Auction } from '../../shared/mockL1Settle.js'
 import {
   MATCH_CANDIDATE_SCHEMA,
   ORDER_SIDE_BUY,
@@ -107,6 +108,20 @@ export interface TradeEngineOptions {
     buy: MockL1TradeOrderV1
     clearingPrice: string
   }) => Promise<{ ok: true } | { ok: false; reason: string }>
+  /**
+   * When set (or via MOCK_L1_AUTHORITY_PRIVATE_KEY + MOCK_L1_SETTLE_ONCHAIN),
+   * Archive may broadcast MockDleAuctionSettlement.settle as certificateAuthority.
+   */
+  l1AuthorityPrivateKey?: string
+  /** Test hook — overrides on-chain settle broadcast. */
+  submitL1SettlementTx?: (args: {
+    certificateHash: Hex
+    sellerOrderHash: Hex
+    buyer: Hex
+    clearingAmount: string
+    scanner: Hex
+    committee: readonly Hex[]
+  }) => Promise<{ ok: true; txHash: Hex } | { ok: false; reason: string }>
 }
 
 export type TradePostResult = { status: number; body: unknown }
@@ -160,9 +175,14 @@ export function createTradeEngine(options: TradeEngineOptions): TradeEngine {
     ('0x0000000000000000000000000000000000000001' as Hex)).toLowerCase() as Hex
   const nowSec = options.nowSec ?? (() => BigInt(Math.floor(Date.now() / 1000)))
   const envCustody = mockL1CustodyEnv()
-  const l1RpcUrl = options.l1RpcUrl ?? envCustody.rpcUrl
-  const l1Settlement = options.l1SettlementAddress ?? envCustody.settlement
+  const envSettle = mockL1SettleEnv()
+  const l1RpcUrl = options.l1RpcUrl ?? envCustody.rpcUrl ?? envSettle.rpcUrl
+  const l1Settlement = options.l1SettlementAddress ?? envCustody.settlement ?? envSettle.settlement
+  const l1AuthorityPk = options.l1AuthorityPrivateKey ?? envSettle.authorityPrivateKey
   const rpcCustodyConfigured = Boolean(l1RpcUrl && l1Settlement) || options.verifyL1Custody !== undefined
+  const onChainSettleConfigured =
+    options.submitL1SettlementTx !== undefined ||
+    Boolean(l1RpcUrl && l1Settlement && l1AuthorityPk)
 
   function persist(): void {
     const state: PersistedState = {
@@ -227,6 +247,12 @@ export function createTradeEngine(options: TradeEngineOptions): TradeEngine {
         : l1RpcUrl && l1Settlement
           ? 'eth_call'
           : 'client_assert_fallback',
+      tradeOnChainSettleConfigured: onChainSettleConfigured,
+      tradeOnChainSettleMode: options.submitL1SettlementTx !== undefined
+        ? 'hook'
+        : onChainSettleConfigured
+          ? 'rpc'
+          : 'off',
       tradeOrderCount: orders.size,
       tradeMatchCount: matches.size,
       tradeByPhase: byPhase,
@@ -615,7 +641,7 @@ export function createTradeEngine(options: TradeEngineOptions): TradeEngine {
     return { status: 200, body: { ok: true, match: record } }
   }
 
-  function settleStatus(body: unknown): { status: number; body: Record<string, unknown> } {
+  async function settleStatus(body: unknown): Promise<{ status: number; body: Record<string, unknown> }> {
     if (!isRecord(body) || typeof body.candidateHash !== 'string') {
       return { status: 400, body: { ok: false, error: 'candidateHash required' } }
     }
@@ -625,16 +651,98 @@ export function createTradeEngine(options: TradeEngineOptions): TradeEngine {
       return { status: 400, body: { ok: false, error: 'certificate not ready for settlement' } }
     }
     const outcome = typeof body.outcome === 'string' ? body.outcome : 'submitted'
-    let eventType: number
-    if (outcome === 'submitted') {
-      eventType = EVENT_TRADE_SETTLEMENT_SUBMITTED
-    } else if (outcome === 'settled') {
-      eventType = EVENT_TRADE_SETTLED
-    } else if (outcome === 'failed') {
-      eventType = EVENT_TRADE_SETTLEMENT_FAILED
-    } else {
+    if (outcome !== 'submitted' && outcome !== 'settled' && outcome !== 'failed') {
       return { status: 400, body: { ok: false, error: 'outcome must be submitted|settled|failed' } }
     }
+
+    const executeOnChain =
+      body.executeOnChain === true || envSettle.settleOnChain || options.submitL1SettlementTx !== undefined
+
+    if (
+      executeOnChain &&
+      outcome !== 'failed' &&
+      record.phase === 'match_certified' &&
+      record.certificate !== undefined
+    ) {
+      const cert = record.certificate
+      const committee =
+        cert.signers.length > 0
+          ? cert.signers
+          : (cert.committee ?? record.committee ?? [])
+      const onChain =
+        options.submitL1SettlementTx !== undefined
+          ? await options.submitL1SettlementTx({
+              certificateHash: cert.certificateHash,
+              sellerOrderHash: record.sell.orderHash,
+              buyer: record.buy.maker,
+              clearingAmount: record.candidate.clearingPrice,
+              scanner: record.candidate.scanner,
+              committee,
+            })
+          : l1RpcUrl && l1Settlement && l1AuthorityPk
+            ? await settleMockL1Auction({
+                rpcUrl: l1RpcUrl,
+                settlement: l1Settlement,
+                authorityPrivateKey: l1AuthorityPk,
+                certificateHash: cert.certificateHash,
+                sellerOrderHash: record.sell.orderHash,
+                buyer: record.buy.maker,
+                clearingAmount: record.candidate.clearingPrice,
+                scanner: record.candidate.scanner,
+                committee,
+              })
+            : { ok: false as const, reason: 'on-chain settle not configured (need MOCK_L1_RPC_URL + MOCK_L1_SETTLEMENT + MOCK_L1_AUTHORITY_PRIVATE_KEY)' }
+
+      if (!onChain.ok) {
+        const failTransition = applyMatchTransition(record, EVENT_TRADE_SETTLEMENT_FAILED)
+        if (failTransition.ok) {
+          record.phase = 'settlement_failed'
+          record.settlementError = onChain.reason
+          record.updatedAt = new Date().toISOString()
+          persist()
+          options.store.appendWal({
+            type: 'trade-settlement',
+            candidateHash: record.candidateHash,
+            phase: record.phase,
+            tipStateRoot: record.tipStateRoot,
+            valueHash: record.valueHash,
+          })
+        }
+        return { status: 400, body: { ok: false, error: onChain.reason, match: record } }
+      }
+      record.settlementTxHash = onChain.txHash
+      // Mode A: certified → submitted → settled when caller asked for settled.
+      const submitted = applyMatchTransition(record, EVENT_TRADE_SETTLEMENT_SUBMITTED)
+      if (!submitted.ok) return { status: 400, body: { ok: false, error: submitted.error } }
+      record.phase = 'settlement_submitted'
+      if (outcome === 'settled') {
+        const settled = applyMatchTransition(record, EVENT_TRADE_SETTLED)
+        if (!settled.ok) return { status: 400, body: { ok: false, error: settled.error } }
+        record.phase = 'settled'
+        record.sell.cancelled = true
+        record.buy.cancelled = true
+        orders.set(record.sell.orderHash.toLowerCase(), record.sell)
+        orders.set(record.buy.orderHash.toLowerCase(), record.buy)
+      }
+      record.updatedAt = new Date().toISOString()
+      persist()
+      options.store.appendWal({
+        type: 'trade-settlement',
+        candidateHash: record.candidateHash,
+        phase: record.phase,
+        tipStateRoot: record.tipStateRoot,
+        valueHash: record.valueHash,
+        settlementTxHash: record.settlementTxHash,
+      })
+      return { status: 200, body: { ok: true, match: record, onChain: true, mockL1Only: true } }
+    }
+
+    const eventType =
+      outcome === 'submitted'
+        ? EVENT_TRADE_SETTLEMENT_SUBMITTED
+        : outcome === 'settled'
+          ? EVENT_TRADE_SETTLED
+          : EVENT_TRADE_SETTLEMENT_FAILED
     const transition = applyMatchTransition(record, eventType)
     if (!transition.ok) return { status: 400, body: { ok: false, error: transition.error } }
     if (outcome === 'submitted') {

runtime/src/daemon/RULES.md

@@ -44,7 +44,9 @@ Local Hardhat/Anvil MVP only. **Not** CoNET 224422 mainnet, **not** production D
 
 ```bash
 npm run mock-auction-cli -- --archive http://127.0.0.1:27101 <command> …
-npm run mock-auction-demo   # in-process submit→scan→candidate→check→attest→settle
+npm run mock-auction-demo   # in-process submit→scan→candidate→check→attest→settle (lab / optional custody)
+npm run mock-auction-e2e    # list → match → Archive settle() on live local RPC (MOCK_L1_*)
+# monorepo root: npm run dle:mock-auction-e2e  # hardhat node + deploy + e2e
 ```
 
 | Command | Role |
@@ -53,6 +55,7 @@ npm run mock-auction-demo   # in-process submit→scan→candidate→check→att
 | `submit` / `cancel` | EIP-191 signed sell/buy orders → `POST /trade/submit` / `/trade/cancel` |
 | `scan` / `candidate` | Scanner proposes `MockL1MatchCandidateV1` only — **cannot** settle |
 | `check` / `attest` | Archive legality + freeze-then-draw committee attest → `TradeMatchCertificateV1`. With Archive `MOCK_L1_RPC_URL` + `MOCK_L1_SETTLEMENT`, client custody flags are **ignored** |
+| `settle` (round 3) | With `MOCK_L1_SETTLE_ONCHAIN` / authority key / `executeOnChain`, Archive posts real `settle` tx; seller must `list` first |
 | `settle` | Report mock L1 settlement outcome (`submitted` / `settled` / `failed`) |
 | `status` | `GET /mockl1/chains` + `/trade/orders` + `/trade/matches` |