[Internal RFP] Blockchain API — FFI Bindings

[fryorcraken]

Split out from #214 ("Review API reference and requirements for Blockchain integration") — one of three RFPs to write for blockchain API/SDK integration.

Scope

Define the expected API for blockchain integration, with enterprise integration in mind, delivered as FFI bindings. Expected to be documented (internal use).

Source material

• logos-api-sdk-research (local repo, see README.md) — comparative audit of 22 blockchain ecosystems (155 pinned repos, 2,083 evidence records) plus as-built audits of logos-blockchain and lez.
  • research/synthesis/logos-api-sdk-reference.md — the proposed ideal API + SDK: 16 operations, 7 SDK interfaces, 42 methods.
  • research/synthesis/logos-delta.md — gap map: what's provided/partial/missing per module vs. that ideal (58 symbols/module).
  • research/synthesis/logos-api-sdk-srs.md — 154 atomic requirements (102 P0), ISO 29148-style.
  • research/synthesis/coverage.md — why each ecosystem expectation is in/out of scope.

Notes

• This RFP defines the API surface itself; the transport/consumption layers (JSON-RPC proxy, SDKs, other interface modules) are separate RFPs that depend on this one.
• Internal deliverable — not an external-contributor-facing surface in itself, though it underpins the external RFPs below.

Related

• Review API reference and requirements for Blockchain and LEZ integration #214 — parent tracking issue
• Sibling RFPs from the same split: JSON-RPC proxy & TypeScript SDK ([Internal RFP] JSON-RPC Proxy Module & TypeScript SDK for Blockchain API #220, merged), additional interface modules & external SDKs ([RFP] Additional Interface Modules & External SDKs (gRPC, GraphQL, Mesh, Rust) #222).

[fryorcraken]

Draft RFP is up: logos-co/rfp#200 (draft), adding RFPs/RFP-021-lez-indexer-ffi.md plus three supporting appendices.

Scope, narrowed

This issue asked for the blockchain API as FFI bindings. RFP-021 scopes that to the LEZ indexer read surface specifically. Wallet and key management, transaction construction and signing, submission, the JSON-RPC transport, and the language SDKs are each separate deliverables, so they are out of scope here and named as such.

The RFP frames six deliverables and states which one it is. Item 2, the wallet FFI, has no issue yet.

What the RFP defines

The complete target read API: 21 functions across eight groups, each with a signature, its semantics, and requirements. 47 requirements in total, each carrying a readiness marker:

Marker	Meaning	Count
Ready	Exported today; a specification or documentation obligation remains	15
Ready, not exposed	Exists in the service, RPC, or store; the FFI does not export it	5
Computed, not persisted	Derived during ingestion, then discarded	5
New	No supporting code exists	22

Markers indicate effort, not priority. Functions that already work are specified too, rather than assumed, so a proposer can build and a reviewer can accept against the document alone.

Each group opens with the rough equivalent on Ethereum, Bitcoin, Solana, and Zcash. Zcash is included because it is the closest production analogue to LEZ: every transparent read is address-indexed and open to anyone, every shielded read is viewing-key scoped. ZIP 310 is worth a look regardless of this RFP, as it is a normative document enumerating exactly what a viewing key does and does not reveal, including that a viewing key yields a lower bound on a balance rather than a balance.

Two findings that may matter beyond this RFP

Events shipped, and the appendices were wrong about it. A program event system merged to dev on 2026-08-27: ProgramOutput.events, indexer capture, getEvents, subscribeToEvents, and query_events on the FFI. Corrected. Two limits are worth knowing: events are dropped for privacy-preserving transactions by design, and an indexer captures only what its configured event filter matches, so availability is a deployment property rather than a protocol guarantee.

Separately: lambda-prize LP-0012 awarded $1,200 for an event system in May 2026. That work was never upstreamed and the in-house implementation took a different design. The prize's headline requirement, that events survive transaction failure, does not appear in what shipped. Worth a look by whoever owns that programme.

Simulation cost is nearly free. LEZ caps public execution at 32M cycles and already runs execute-only, so the executor's user-cycle count is computed on every public transaction and then discarded. Returning it is plumbing, not new computation. The RFP requires it reported as cycles rather than as a fee, since there is no fee system on dev, and requires that exhausting the cycle budget be distinguishable from a program error: every executor failure currently collapses into ProgramExecutionFailed(String).

Note that branch erhant/fees/cycle-count-metering already changes Program::execute to return (ProgramOutput, Cycles) and adds a typed OutOfGas. It is unmerged and in no integration branch, so this RFP either depends on it or duplicates it. Worth deciding deliberately.

On the source material

The Source material section of this issue cites logos-api-sdk-research. That repository is AI generated and is not usable as a reference; spot-checking found figures its own lockfile contradicts. Three replacement appendices are in the PR, written from first-party sources with every URL fetched and every quotation checked against the original:

• blockchain-api-sdk-ecosystem.md, 34 API functions across eight chains, with transports, SDK languages, response shapes, and documented origin history.
• logos-api-surfaces.md, an as-built inventory of every Logos API layer at pinned commits.
• wallet-libraries-ecosystem.md, where wallet functionality lives per chain. This is input for the wallet FFI RFP rather than this one.

The research repo was used only to decide what to investigate, and is cited nowhere.

Open for review

• Five judgement calls are flagged in the PR description.
• The proposed names for functions that do not exist yet (query_transaction_effects, simulate_transaction, query_accounts) follow existing conventions but are not fixed by source. Worth deciding whether the RFP mandates them or treats them as illustrative.
• RFP-021 is not in the README table, since that table is headed "Open RFPs" with a Submit Proposal column and this is an internal RFP. Say if it should be listed anyway.