[Internal RFP] LEZ Node API

[fryorcraken]

Draft PR: logos-co/rfp#200

RFP-027. One of five LEZ deliverables split out from #214 ("Review API
reference and requirements for Blockchain and LEZ integration"), the LEZ
counterpart to the L1 API work in #219.

Scope

Defines the LEZ node API as exported functions on the node FFI — the
equivalent of Ethereum's eth namespace. Answers what happened and what the
current state is; signs nothing. Internal deliverable.

The draft specifies 24 functions across ten groups and 56 requirements
covering effects, per-transaction status, batch and pinned account reads,
commitment membership proofs, transaction submission, the pending set,
subscriptions, pagination, chain and network identity, and error semantics.
Functions that already work are specified too rather than assumed, so a
proposer can build and a reviewer can accept against the document alone.

Two positions carried by the draft

• The LEZ node API is the only API a consumer sees. The sequencer is an
  internal component of LEZ, not a transitional API target, so the node serves
  every read as a cache and proxy. Consequently the wallet's private account
  sync and its commitment membership proofs are required of the node, and
  transaction submission sits on this surface — a wallet that has signed a
  transaction otherwise has nowhere sanctioned to send it.
• Simulation is not here. On LEZ a privacy-preserving transaction is
  executed by the wallet, which runs the program locally over notes only it can
  decrypt and submits a proof that execution was correct. The proof is an input
  rather than a result, so there is nothing for the node to simulate. It
  belongs to the LEZ wallet API.

Source material

• appendix/blockchain-api-sdk-ecosystem.md — 34 API functions across nine
  chains, with transports, SDK languages, response shapes, and per-function gap
  notes for Logos L1 and LEZ.
• appendix/logos-api-surfaces.md — as-built inventory of the LEZ indexer FFI
  and RPC, the sequencer RPC, the wallet FFI and lez_core module. (The
  indexer names there are as-built component names, which this RFP's node API
  is exposed over.)

Known gap

The L1 chain identifier query_network_identity returns is inscribed in the
Logos Blockchain genesis block and read at ledger initialisation, but no L1
route serves it. Reaching it is work outside the node, recorded under
Platform Dependencies; the surface stays deliverable meanwhile by reporting the
value as unavailable rather than guessing.

Dependencies

None — this is a root surface. The JSON-RPC proxy and its client library, and
the LEZ-DK, consume it.

Related

• Review API reference and requirements for Blockchain and LEZ integration #214 — parent tracking issue
• L1 counterpart: [Internal RFP] Blockchain API — FFI Bindings #219 (Blockchain API — FFI Bindings)
• Sibling LEZ RFPs: LEZ Wallet API ([Internal RFP] LEZ Wallet API: key handling, derivation, proving, and signing #236), JSON-RPC Proxy & Client Library
  ([RFP] LEZ JSON-RPC Proxy Module & Client Library #237), LEZ-DK ([RFP] LEZ-DK: The LEZ Development Kit #238). The separate Indexer Client Library issue ([RFP] LEZ Indexer Client Library #239) was
  folded into [RFP] LEZ JSON-RPC Proxy Module & Client Library #237.
• [RFP] Additional Interface Modules & External SDKs (gRPC, GraphQL, Mesh, Rust) #222 — additional interface modules, cross-chain, binds to this surface