区块与交易

本页是区块 / 交易信封 / 检索 相关接口：JSON-RPC 读方法（getBlock 等）与历史 REST（/api/v1/blocks、/api/v1/envelopes、/api/v1/tx/{hash}、/api/v1/search）。

getBlock

查询单个块。不传 height 返回最新块。

参数	类型	必填	说明
`height`	u64	否	块高度，默认 tip

响应 data：

字段	类型	说明
`parent`	Hex32	父块哈希
`height`	u64	块高度
`timestamp_ms`	u64	块时间戳（毫秒）
`digest`	Hex32	块 SHA-256 哈希
`envelope_count`	usize	块内交易数
`event_count`	usize	块内事件数
`state_root`	Hex32	状态根哈希
`envelopes`	BlockEnvelopeView[]	交易列表

BlockEnvelopeView：

字段	类型	说明
`tx_hash`	TxHash	交易哈希（`0x` hex）
`envelope_idx`	u32	块内序号
`signer`	Address20	签名者地址
`nonce`	u64	账户 nonce
`action`	Value	Action JSON
`status`	TxStatus	`"accepted"` · `"kept-reject"`
`reason`	RejectReason?	仅 kept-reject 时出现

响应示例：

{
  "jsonrpc": "2.0", "id": 1,
  "result": {
    "height": 12345,
    "data": {
      "parent": "0xabc...def",
      "height": 12345,
      "timestamp_ms": 1717200000000,
      "digest": "0x123...789",
      "envelope_count": 15,
      "event_count": 42,
      "state_root": "0xdef...abc",
      "envelopes": [{
        "tx_hash": "0xa1b2...c3d4",
        "envelope_idx": 0,
        "signer": "0x1111222233334444555566667777888899990000",
        "nonce": 42,
        "action": { "PlaceOrder": { ... } },
        "status": "accepted"
      }]
    }
  }
}

getBlockEvents

按高度查块内事件（分页）。事件格式见事件投影。

参数	类型	必填	说明
`height`	u64	是	块高度
`offset`	usize	否	默认 0
`limit`	usize	否	默认 500，最大 2000

请求：

{ "jsonrpc": "2.0", "id": 1, "method": "getBlockEvents", "params": { "height": 12345, "offset": 0, "limit": 10 } }

响应 data： EventValue[] — 每项为 {"seq": u64, "block_height": u64, "envelope_idx": u32, "kind": {"DomainTag": {"Variant": {...}}}}，数值字段已投影为 decimal string。

响应示例：

{
  "jsonrpc": "2.0", "id": 1,
  "result": {
    "height": 12345,
    "data": [{
      "seq": 3,
      "block_height": 12345,
      "envelope_idx": 1,
      "kind": {
        "Exec": {
          "Filled": {
            "taker_order_id": 1001,
            "maker_order_id": 1002,
            "market_id": 1,
            "price": "97234.50",
            "qty": "0.50000",
            "notional": "48617.250000",
            "taker_fee": "24.308625",
            "maker_fee": "-4.861725",
            "aggressor_side": "Bid"
          }
        }
      }
    }],
    "page": { "offset": 0, "limit": 10, "total": 42 }
  }
}

getTx

按交易哈希查回执。

参数	类型	必填	说明
`hash`	TxHash	是	32 字节 hex（`0x` 前缀）

响应 data：

字段	类型	说明
`tx_hash`	TxHash	交易哈希
`height`	u64	所在块高
`envelope_idx`	u32	块内序号
`signer`	Address20	签名者地址
`nonce`	u64	账户 nonce
`action`	Value	Action JSON
`status`	TxStatus	`"accepted"` · `"kept-reject"`
`reason`	RejectReason?	仅 kept-reject 时出现
`events`	Value[]	本笔交易事件（decimal string 投影）

result.reason vs events[]： 与写操作响应相同——reason 内数值为 raw i128；events[] 中对应 Rejected 已投影为 decimal string。

请求：

{ "jsonrpc": "2.0", "id": 1, "method": "getTx", "params": { "hash": "0xa1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456" } }

响应示例：

{
  "jsonrpc": "2.0", "id": 1,
  "result": {
    "height": 12346,
    "data": {
      "tx_hash": "0xa1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456",
      "height": 12346,
      "envelope_idx": 3,
      "signer": "0x1111222233334444555566667777888899990000",
      "nonce": 42,
      "action": {
        "PlaceOrder": {
          "owner": "0x1111222233334444555566667777888899990000",
          "symbol": "BTC-USDT",
          "side": "Bid",
          "limit_price": "97100.00",
          "qty": "1.00000",
          "tif": "Gtc",
          "client_order_id": "my-cloid-1",
          "reduce_only": false
        }
      },
      "status": "accepted",
      "events": [{
        "seq": 0,
        "block_height": 12346,
        "envelope_idx": 3,
        "kind": {
          "Exec": {
            "OrderAccepted": {
              "order_id": 1001,
              "market_id": 1,
              "owner": "0x1111222233334444555566667777888899990000",
              "side": "Bid",
              "limit_price": "97100.00",
              "qty": "1.00000"
            }
          }
        }
      }]
    }
  }
}

区块（REST）

`GET /api/v1/blocks`

分页区块头列表，新→旧。

Query

Param	Default	Max
`offset`	`0`	—
`limit`	`50`	`200`

Response 200

{
  "data": [
    {
      "parent": "0x…",
      "height": 12345,
      "timestamp_ms": 1717000000000,
      "digest": "0x…",
      "envelope_count": 5,
      "event_count": 42,
      "state_root": "0x…",
      "envelopes": []
    }
  ],
  "page": { "offset": 0, "limit": 50, "total": 12346 }
}

列表中 envelopes 恒为空数组。完整列表见 [GET /api/v1/blocks/{id}/envelopes#get-apiv1blocksidenvelopes。

`GET /api/v1/blocks/{id}`

按高度或 digest 查询单个区块头。

Response 200

{ "data": { /* BlockHeader — 字段同列表项 */ } }

Response 404 — 区块不存在。

`GET /api/v1/blocks/{id}/events`

区块内链上事件，分页返回。

Path： {id} 必须为数字高度（不支持 digest）。非数字 {id} 返回 404。

高度合法但区块尚未 ingest、或区块内无 event 时，返回 200 + 空 data（非 404）。

Query

Param	Default	Max
`offset`	`0`	—
`limit`	`500`	`2000`

Response 200

{
  "data": [
    {
      "height": 12345,
      "seq": 0,
      "envelope_idx": 0,
      "kind": "Exec",
      "sub_kind": "Filled",
      "market_id": 1,
      "symbol": "BTC-USDT",
      "tx_hash": "0x…",
      "account": "0x…",
      "timestamp_ms": 1717000000000,
      "body": { "price": "50000.00", "qty": "1.5" }
    }
  ],
  "page": { "offset": 0, "limit": 500, "total": 42 }
}

Field	Type	Description
`kind`	`string`	事件大类：`Exec`、`Core`、`Oco`、`Liquidation`、`Trigger`、`Bridge`、`Ops`、`Unknown`
`sub_kind`	`string`	子类型，如 `Filled`、`OrderAccepted`、`OrderResting`、`PositionUpdated`、`OrderDone`
`market_id`	`number \| null`	ingest 时提取的市场 ID
`symbol`	`string \| null`	读取时从 market cache 解析
`tx_hash`	`string \| null`	产生该 event 的 L2 交易 hash（见 [事件溯源../system/index.md#事件溯源event-provenance）
`timestamp_ms`	`number`	区块时间戳（ms）
`account`	`string \| null`	关联账户（尽力提取）
`body`	`object`	节点原始事件 JSON（decimal 字符串）

`GET /api/v1/blocks/{id}/envelopes`

区块内全部 envelope（已签名交易）。

Path： {id} 必须为数字高度。非数字 {id} 返回 404。

区块不存在或无 envelope 时，返回 200 + 空 data 数组（非 404）。

Response 200

{
  "data": [
    {
      "height": 12345,
      "envelope_idx": 0,
      "tx_hash": "0x…",
      "signer": "0x…",
      "nonce": 5,
      "status": "accepted",
      "action_kind": "PlaceOrder",
      "market_id": 1,
      "symbol": "BTC-USDT",
      "action": { "PlaceOrder": { "market_id": 1, "side": "Bid" } },
      "reason": null,
      "timestamp_ms": 1717000000000
    }
  ]
}

Field	Type	Description
`status`	`string`	执行结果，如 `accepted`、`kept-reject`
`action_kind`	`string`	`action` JSON 顶层 key，如 `PlaceOrder`、`AmendOrder`、`AmendTriggerOrder`、`CancelOrder`
`reason`	`object \| null`	`status == "kept-reject"` 时的拒绝详情
`timestamp_ms`	`number`	区块时间戳（ms，读取时 join）

交易与信封（REST）

`GET /api/v1/envelopes`

全局 envelope 索引，支持过滤，新→旧。

Query

Param	Type	Default	Max	Description
`signer`	`string`	—	—	按签名者过滤
`action_kind`	`string`	—	—	按 action 类型过滤
`market_id`	`number`	—	—	按市场过滤
`from_block`	`number`	—	—	最小区块高度（含）
`to_block`	`number`	—	—	最大区块高度（含）
`offset`	`number`	`0`	—	分页偏移
`limit`	`number`	`25`	`200`	页大小

Response 200

{
  "data": [ /* EnvelopeView[] */ ],
  "page": { "offset": 0, "limit": 25, "total": 1000 }
}

`GET /api/v1/tx/{hash}`

按 hash 查交易。先查本地索引，未命中则回退链节点 getTx。

Path： {hash} — 交易 hash（0x…）

Response 200（本地）

{
  "data": {
    "height": 12345,
    "envelope_idx": 0,
    "tx_hash": "0x…",
    "signer": "0x…",
    "nonce": 5,
    "status": "accepted",
    "action_kind": "PlaceOrder",
    "market_id": 1,
    "symbol": "BTC-USDT",
    "action": { "PlaceOrder": { "market_id": 1, "side": "Bid" } },
    "reason": null,
    "timestamp_ms": 1717000000000,
    "events": [
      {
        "height": 12345,
        "seq": 0,
        "envelope_idx": 0,
        "kind": "Exec",
        "sub_kind": "OrderAccepted",
        "market_id": 1,
        "symbol": "BTC-USDT",
        "tx_hash": "0x…",
        "account": "0x…",
        "timestamp_ms": 1717000000000,
        "body": {}
      }
    ]
  },
  "source": "local"
}

Field	Description
`source`	`"local"` — 本地索引；`"node"` — 链节点实时查询

source == "node" 时，data 遵循节点 getTx 结构，可能与 EnvelopeView 略有差异。

Response 404 — 本地和节点均未找到。

统一检索（REST）

`GET /api/v1/search`

一个查询串自动分派到区块 / 交易 / 账户（合并后新增端点）。

Query

Param	Type	Required	Description
`q`	`string`	yes	纯数字 → 区块高度；64 hex → 交易 hash（未命中回退区块 digest）；40 hex → 账户地址；其它 → `type: null`

Response 200（区块）

{
  "data": { "type": "block", "height": 12345, "digest": "0x…", "found": true },
  "query": "12345"
}

Response 200（交易）

{
  "data": {
    "type": "tx",
    "tx_hash": "0xabc…",
    "height": 12345,
    "envelope_idx": 0,
    "found": true
  },
  "query": "0xabc…"
}

Response 200（账户）

{
  "data": { "type": "account", "address": "0x1111222233334444555566667777888899990000" },
  "query": "0x1111…"
}

Response 400：缺少 q。未命中时 found: false（非 404）。

getBlock​

getBlockEvents​

getTx​

区块（REST）​

GET /api/v1/blocks​

GET /api/v1/blocks/{id}​

GET /api/v1/blocks/{id}/events​

GET /api/v1/blocks/{id}/envelopes​

交易与信封（REST）​

GET /api/v1/envelopes​

GET /api/v1/tx/{hash}​

统一检索（REST）​

GET /api/v1/search​

getBlock

getBlockEvents

getTx

区块（REST）

`GET /api/v1/blocks`

`GET /api/v1/blocks/{id}`

`GET /api/v1/blocks/{id}/events`

`GET /api/v1/blocks/{id}/envelopes`

交易与信封（REST）

`GET /api/v1/envelopes`

`GET /api/v1/tx/{hash}`

统一检索（REST）

`GET /api/v1/search`