mirror of
https://github.com/logos-co/logos-verified-proxy-module.git
synced 2026-08-27 04:51:08 +00:00
master
9
Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
 Dario Gabriel LipicarandClaude Opus 5
|
35fc0365ce |
feat: the full eth*/op* mirror, generated — and CI to gate it
Grows the typed surface from 8 methods to 60: all 30 eth_* the library dispatches, plus the 30 op_* mirrors. Everything was already reachable through rpc(); what was missing was discoverability — `lm methods`, the LIDL contract, and a caller's type checker. Generated, not hand-written. Each wrapper is three lines over the same shared path, so sixty-one of them by hand is sixty-one chances to transpose an argument; the table is extracted from the library's OWN dispatch table (the `case $name` in c_frontend.nim), including each parameter's real type — which is how ethGetBlockByNumber gets a bool, ethFeeHistory a uint64 and a list, and eth_call an object rather than everything being a string. They are still committed as literal text: the module's code generator parses verified_proxy_impl.h as TEXT to build the LIDL contract, so anything hidden behind a macro would simply not exist to it. `--check` proves the committed blocks still match, and fails on a one-character edit (verified). eth_syncing is deliberately excluded from the typed surface — the runtime issues it as its own keep-alive and a wrapper would invite callers to fight it. Still reachable through rpc(). CI is new for this repo, which had none: build on Linux and macOS, unit tests (the check derivation runs the suite as part of building it), and the codegen drift check. Named explicitly rather than via `nix flake check`, which would also evaluate the x86_64-windows pseudo-system. Verified live on sepolia through a real logoscore daemon: ethGasPrice, ethMaxPriorityFeePerGas, ethBlobBaseFee, ethGetBlockTransactionCountByNumber, ethGetUncleCountByBlockNumber and ethGetBlockByNumber all answer. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> |
||
|
Dario Gabriel LipicarandClaude Opus 5
|
3d08debc57 |
fix: status() reported a default network before the first start
ProxyRuntime is only handed a config by start(), so until then its snapshot describes a DEFAULT-constructed one — network "mainnet", chainId 1 — regardless of what configure() was given. A module restored from its persisted sepolia config therefore reported mainnet, and a panel comparing that against its own selector warned the operator about a mismatch that did not exist. The impl's config is the authority whenever it has one, so status() now overrides network and chainId from it. A test pins both halves: the runtime's own default before start, and the real config after. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> |
||
|
Dario Gabriel LipicarandClaude Opus 5
|
244437b449 |
fix: defaultConfig returned {} for every network, and persist what ran
defaultConfig() seeded only `network` and ran it through fromJson, which
REQUIRES a trusted root — so validation failed and it returned an empty object
for every network, silently. Verified over the CLI, where it is meant to be
used. It now seeds a placeholder root to get past validation and blanks it in
the result, keeping the round trip that makes the template exactly what
configure() would produce. A test pins the whole workflow: the template is
complete, its empty root is still rejected, and filling one in is accepted.
configure() also now persists the RESOLVED config rather than the caller's
input. Persisting {"network":…, "trustedBlockRoot":…} verbatim meant the
endpoints were re-derived on every load, so a later change to the default table
would silently move a running deployment onto different providers. Not a trust
problem — providers are untrusted by construction — but it decides whether
eth_getProof works at all: an archive endpoint answers proofs at the finalized
header, a pruning one does not.
Verified end to end against a real logoscore daemon: defaultConfig returns a
full mainnet template, configure with only network + root fills the endpoints
in, the resolved config lands on disk, and it survives a daemon restart.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
|
||
|
Dario Gabriel LipicarandClaude Opus 5
|
e0a2f591d1 |
feat: default the endpoints in configure(), and expose the stored config
Two additions that let the module be driven from a CLI and let a UI restore a
form from the module rather than keeping its own copy.
configure() now fills either endpoint list from the network table when the
caller omits it, so the smallest useful config is two fields:
{"network": "mainnet", "trustedBlockRoot": "0x…"}
Only when the key is ABSENT. An explicit [] is the caller saying "no
endpoints", which stays an error — substituting a default for a value someone
deliberately wrote would hide their mistake rather than fix it. An existing
test caught exactly that distinction when the first version got it wrong.
trustedBlockRoot is never defaulted: it anchors the whole trust model, so it
has to be chosen rather than inherited.
defaultConfig(network) returns a complete template, built by round-tripping a
default config through fromJson so it is exactly what configure() would produce
rather than a second, drifting copy of the same defaults.
getConfigUnredacted() returns the stored config with URLs intact. The module
already persisted its config and reloaded it on load; what was missing was a
way to read it back, because getConfig() masks provider URLs — correctly, since
they can carry API keys — and a masked URL cannot repopulate a field. redacted()
and raw() are now one serialiser with a flag, so the two views cannot drift.
Also raises the shared test callTimeoutMs from 1500ms to 15s. Tests that
exercise a timeout set their own short value; the rest only need the call to
complete, and 1500ms made them fail under a parallel nix build rather than
merely run slower — observed once here as a spurious red.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
|
||
|
Dario Gabriel LipicarandClaude Opus 5
|
3f22acec91 |
feat: one network table, with live-verified default endpoints per chain
The supported-network set was written out in three places — the configure() whitelist, expectedChainId(), and the panel's hardcoded dropdown model — and adding per-chain defaults would have made four. They are now one table, exposed as supportedNetworks() so a UI builds its selector from the module's own whitelist. That is a safety property, not tidiness: `network` is one of two config fields whose value reaches a quit() inside Nim when upstream does not recognise it, so a UI list that drifts from the whitelist kills the host. The defaults are live-verified, not sourced from documentation. A beacon URL is only listed if /eth/v1/beacon/light_client/bootstrap/<root> answered 200, and an execution URL only if eth_getProof returned a result. Both filters matter: several hosts serve the standard beacon API but 404 the light_client namespace (Checkpointz instances especially, which answer /eth/v1/node/version and look healthy), and several long-published RPC URLs are now dead, key-gated or intermittent. mainnet and hoodi take drpc for execution because it answered eth_getProof deep in history where the pruning free tiers refuse anything past ~head-1024. That distinction is load-bearing here rather than cosmetic: the light client verifies against its FINALIZED header, which lags the head, so a pruning provider fails proofs for precisely the blocks this module asks about — and it surfaces as "distance to target block exceeds maximum proof window" long after start() reported success. Sepolia stays on publicnode because dRPC gates that chain behind a paid plan. Six tests pin the table's invariants: it covers exactly the three networks upstream compiles in, every entry is accepted by configure(), every chain id is non-zero (0 is the sentinel that would silently disable the post-start chain check), lookup rejects a plausible typo, non-empty defaults are well formed and all-or-nothing, and a profile's defaults are accepted as a real config. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> |
||
|
Dario Gabriel LipicarandClaude Opus 5
|
074c2e099c |
fix: one proxy thread for the module's lifetime, not one per start()
Stop-then-start segfaulted the module process (signal 11), taking the panel with it. Reported from live use after switching network, but the network was a red herring: reproduced deterministically against the real archive with the config and network held IDENTICAL across both runs — new thread per run exits 139, one persistent thread exits 0 and returns a fresh Context. NimMain() binds the Nim runtime to the thread that calls it, and this build compiles NEITHER setupForeignThreadGc NOR tearDownForeignThreadGc: both sites in verifproxy.nim sit behind `when defined(setupForeignThreadGc)` and nothing defines it. start() created a std::thread per run and NimMain ran under std::call_once, so every run after the first executed on a thread with no GC state at all and died inside startVerifProxy, before it could even return. The thread is now created lazily on the first start() and ends only in the destructor; start() and stop() are commands posted to it. stop() waits for the RUN to finish rather than joining the thread, bounded by drainTimeoutMs plus headroom. teardown() releases that wait after freeContext, so a following start() cannot race a half-released Context. Each run also resets the head and heartbeat-streak state, which otherwise reported the previous chain's head after a network change. Three tests: restart reuses the same thread (the invariant that keeps the Nim runtime alive), four restarts in a row with the lifecycle guards asserted, and a restart not inheriting the previous run's head. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> |
||
|
Dario Gabriel LipicarandClaude Opus 5
|
a1a17acbc5 |
feat: wire the heartbeat's health signal, and add fetchFinalizedRoot
Three fields — head.blockNumber, head.updatedAt and heartbeatFailures — were read by statusSnapshot() and never assigned, and State::Degraded appeared only in stateName(). The heartbeat was fire-and-forget with a comment pointing at a pollHeartbeat() that does not exist, so nothing ever observed its outcome: status().head stayed "" for the life of the process and a proxy whose sync had died still reported "running". CallSlot now carries a Kind, so the trampoline can tell a user call from a heartbeat or a head probe. Three consecutive heartbeat failures degrade the proxy and one success clears it; head is refreshed by a separate eth_blockNumber probe every fifth beat, since eth_syncing answers a hardcoded `false` and cannot report it. live() joins Running and Degraded for callers making lifecycle decisions, leaving running() strict for health. fetchFinalizedRoot() is new, and lives here rather than in the panel because Basecamp sandboxes ui_qml plugins away from the network: an XMLHttpRequest from a view is refused outright. It is a convenience, not a trust anchor, and says so. Adds libcurl, used for that one request and nothing else. Tests spin on the condition rather than sleeping a fixed interval — the first draft was green on an idle machine and red under a parallel build. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> |
||
|
Dario Gabriel LipicarandClaude Opus 5
|
8400bd7d36 |
feat: serve a verified JSON-RPC endpoint over HTTP
libverifproxy ships no server: library/verifproxy.nim imports json_rpc_backend
(the client it calls providers with) and the in-process engine/rpc_frontend, but
never json_rpc_frontend — the HTTP/WS server exists only in the standalone
binary, and nm on the archive we link finds zero of its symbols. So the endpoint
is ours.
Opt-in via `httpServer: { enabled, host, port }`, bound to loopback by default
and refusing anything but POST — this answers state queries, so an accidental
0.0.0.0 bind is a different order of mistake than it is for a metrics port.
Uses libmicrohttpd, matching openmetrics-module. Every request is forwarded
through the same proxyCall path the typed methods use, so there is one
verification path and one error shape rather than a second implementation.
Two adaptations are what make "point ethers at it" true rather than nearly true,
and both are measured rather than assumed:
* eth_call / eth_estimateGas / eth_createAccessList (and the op_ twins) take a
THIRD positional parameter upstream, optimisticStateFetch, which the spec does
not have. Stock clients send two and the library answers "parameters missing".
The endpoint appends the default and leaves an explicit third alone. Verified
against sepolia: a 2-param eth_call now reaches the engine and comes back with
a *verification* error, not a parameter one.
* eth_blockNumber answers a bare JSON number where every client expects a hex
QUANTITY (chainId and gasPrice do return hex — upstream is not uniform).
Promoted to hex here only; rpc() and the typed methods still return what the
library produced, so this cannot hide an upstream change from a direct caller.
handleBody() is pure apart from its dispatch callback, so the whole protocol
surface is unit-tested without binding a socket: envelopes, id-type
preservation, batches, notifications, the reserved error codes, and both
adaptations. 44 tests pass.
Verified end to end against sepolia: the endpoint answers
{"id":1,"jsonrpc":"2.0","result":"0xb02f64"} where the upstream provider says
"0xb02f65" — same shape, one block behind, which is what a verifying light
client should look like.
This also re-opens the eth_rpc_module integration the plan had ruled out on the
grounds that no port existed: ChainConfig.endpoint can now point here.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
|
||
|
Dario Gabriel LipicarandClaude Opus 5
|
421624641a |
feat: wrap nimbus libverifproxy as a Logos module
Adds `verified_proxy_module`, a universal C++ core module over status-im's
`libverifproxy` — the C library form of nimbus_verified_proxy. Where
`eth_rpc_module` forwards JSON-RPC to a provider and trusts the answer, this
verifies every response against the beacon-chain light client's attested
execution state, so a lying provider produces an error rather than a wrong
value.
Nobody had packaged libverifproxy with Nix before: upstream's flake builds the
verified-proxy *binary* but not the library, and a global code search for
`libverifproxy` in nix files returns nothing. Rather than write a derivation,
flake.nix re-targets upstream's own — `.override { targets = ["libverifproxy"]; }`
composes because callPackage's makeOverridable merges previously-applied args,
so their pinned Nim survives — and then fixes the three things that break:
* installPhase installs only `-type f -executable` into $out/bin, so a .a and
a .h yield an EMPTY $out (and installCheckPhase then runs the literal
string "$out/bin/* --version");
* env.NIMFLAGS is ASSIGNED, not appended, so ours have to extend it;
* preBuild builds vendored RocksDB unconditionally although `make
libverifproxy` never reaches that target. `nm -u` on the result confirms
zero rocksdb references, so it is dropped rather than swapped for
dynamicRocksDB (which on Windows would demand a *cross* RocksDB).
Three NIMFLAGS additions are load-bearing rather than tuning:
* `-d:noSignalHandler` — library/nim.cfg omits it, so NimMain() would install
Nim's SIGINT/SIGSEGV/SIGABRT handlers over the HOST's. Verified by dlopen'ing
a probe and comparing sigaction before/after: the host's handler survives.
* `--passC:-fPIC` — Nim only adds it when optGenDynLib is set, which
--app:staticlib does not; upstream's dist script adds it for linux-arm64
only. The archive is linked into a SHARED plugin.
* `-d:release --debugger:off` — upstream ships debug info, which dominates
the artifact (~99MB uncompressed in the release tarballs vs 31MB here).
The library can also take the host process down, which a plugin cannot tolerate,
so ProxyConfig whitelists the two fields that reach a Nim `quit()`: an
unrecognised `eth2Network` reaches getMetadataForNetwork's `fatal` + `quit 1`,
and any `logLevel` Nim's updateLogLevel rejects reaches setupLogging's `quit 1`.
Neither is validated upstream. Everything else (bad JSON, missing
trustedBlockRoot, malformed URL) is already caught and turned into a NULL
return, so validating it only improves the message.
ProxyRuntime owns the one thread that may touch the C ABI at all: the library
spawns none, startVerifProxy blocks through an unbounded prologue, and
setupForeignThreadGc/tearDownForeignThreadGc are bound to start/stop. Notable
consequences encoded here:
* processVerifProxyTasks only poll()s while pendingCalls > 0, so an IDLE PROXY
DOES NOT ADVANCE ITS LIGHT CLIENT. The heartbeat is
proxyCall("eth_syncing","[]"), which drives beaconSync() and touches no
execution backend. Its return value is a hardcoded `false` and useless; its
error string is the only machine-readable sync-health signal the ABI has.
* Drain BEFORE stopVerifProxy: it sets ctx.stop, which processVerifProxyTasks
checks before polling, so afterwards no callback can ever fire.
* Call slots use joint ownership (waiter + heap CallBox) rather than
storage-module's `abandoned` flag, so a late callback after a timeout is
safe by construction. There is no per-call cancel in the C API.
* concurrency:"multi" spawns a QThread per call rather than using a bounded
pool, so admission control is mandatory, not a nicety.
All ~60 eth_*/op_* entry points can route through one FFI path, because
proxyCall is a string `case` over the same procs the typed C exports call.
This commit lands 8 representative methods covering every wire type; the rest
are mechanical.
Verified on aarch64-darwin: the archive links into a .dylib; NimMain initialises
under dlopen; a bad config returns NULL rather than quitting; the plugin builds
at 15MB with the archive absorbed (hence `include: []`); and 28/28 unit tests
pass against a mocked C library that — unlike mock_libstorage — queues
completions and drains them only from the pump, so the cross-thread design is
actually exercised.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
|