feat: all the things

.docs/ADR-009-Port-Proof-API-Attestor-to-Go.md

@@ -0,0 +1,98 @@
+Here is the result of "view" for the Page with URL https://app.notion.com/p/3898c17818cb8030bcece5a4d3b55849 as of 2026-06-24T16:37:44.507Z:
+<page url="https://app.notion.com/p/3898c17818cb8030bcece5a4d3b55849">
+<ancestor-path>
+<parent-page url="https://app.notion.com/p/3828c17818cb807fb5fce4b93c1a415a" title="ADRs (Architecture Decision Records)"/>
+<ancestor-2-page url="https://app.notion.com/p/3828c17818cb80998a62d040b2acb5cd" title="Engineering"/>
+<ancestor-3-page url="https://app.notion.com/p/3378c17818cb808cbbd2cebe4de9bac3" title="Foundations Team Hub"/>
+</ancestor-path>
+<properties>
+{"title":"ADR-009 Port Proof API + Attestor to Go"}
+</properties>
+<content>
+<empty-block/>
+## ADR-009: Port Proof API + Attestor to Go (vs keep Rust binary)
+**Status:** `Proposed`
+**Date:** 2026-06-23
+**Deciders:** <mention-user url="user://773fef25-cd11-48a6-a5f3-bb95667f7c6c"/>  <mention-user url="user://15dd872b-594c-810d-aeea-00025475a498"/> <mention-user url="user://2e1d872b-594c-814c-8191-000286abd10c"/> 
+---
+### Context
+We need to decide whether we should port the relevant V1 functionality of the rust Proof API + `ibc-attestor` binary into Go or whether IBC Link should execute parts of it in a rust subprocess.
+A PoC exists that runs the Rust attestor under a Go host (via `go-plugin`) to explore how usable it is, whether we can achieve our goals of a unified YAML config surface and whether it meets our operational needs. It does not materially change the underlying reality that we are still shipping and executing a Rust binary.
+### PoC
+[GitHub - cosmos/ibc-attestor at go-plugin-poc](https://github.com/cosmos/ibc-attestor/tree/go-plugin-poc)
+The PoC runs the rust ibc attestor as a go-plugin under a Go host and then fetches an attestation from the attestor, verifies logs are surfaced on the host, scrapes metrics, and intentionally kills and restarts the attestor subprocess.
+**Configuration Surface**
+The PoC demonstrates how we can still achieve the goals of providing a unified yaml configuration file for the ibc-link binary. The host program in the PoC takes the given yaml config and writes the attestor config values to a temp toml file in the form the attestor binary expects. The spawned attestor subprocess references the temp <span color="purple_bg">toml config file.</span> The temporary file may present some friction in read-only deployment environments.
+**Logging**
+The PoC demonstrates that attestor logs are surfaced in the host process. Considerations here are:
+- that go-plugin relies on stdout to perform a handshake between between the plugin and host and so the attestor routes all application logs to stderr in plugin mode. 
+- go-plugin relies on hclog for logging, so there would be a bit of additional work to make logs consistent if the host relies on a different logging library.
+**Standalone Attestor Considerations**
+One of the primary value props of go-plugin is the negotiation of a private connection between the plugin and the host. This benefit is moot when the attestor is run standalone as the attestor needs to bind on a fixed port that external traffic can be routed to.
+**Attestor Binary**
+The host process needs a reference to the attestor rust binary. The PoC assumes the attestor binary is in the same directory as the attestor binary. This is a detail we can hide in any containerized release artifact, but it still doesn’t change the underlying fact that we are shipping a rust binary in addition to the ibc-link binary.
+**Attestor Code Additions**
+Non-go plugins requires a bit more overhead to integrate than go plugins. The PoC adds \~150 LoC that:
+- Adds a plugin mode
+- Serves a grpc health service that go-plugin requires every gRPC plugin to serve
+- Routes logs to stderr in plugin mode
+- Binds to a free port
+- Performs the plugin handshake with the host over stdout that announces what port it’s running on.
+**Metrics**
+The host process and subprocess will have different metrics registries which are scraped from different endpoints. Work would need to be done if wanting to provide a unified metrics endpoint.
+**Takeaways**
+- It’s pretty simple to run the attestor as a plugin and it serves our needs with some rough edges.
+- It’s not some huge unlock. We can do something similar with standard libraries and some lightweight subprocess management logic. Given that running the attestor as sub-process alongside the relayer should only be used in PoC or testing environments, we have no need for some of the production oriented functionality that go-plugin provides like AutoMTLS, plugin host connection privacy, version negotation.
+- Obvious but single binary is an illusion. There is still a rust binary that we must compile into any artifact we release and we will have toolchains for both rust and go. Local testing using the ibc-link binary will also rely on the attestor rust binary being compiled and we should provide make commands that handle this.
+### Options Considered
+### Option A: Run Rust logic in subprocess
+- **Pros:** 
+	- Minimal engineering investment
+	- Reuses audited code
+- **Cons:** 
+	- Still requires compiling and distributing a Rust artifact
+	- go-plugin adds constraints (stdout handshake, log routing to stderr, disjoint metrics registries, dependency on `hclog`)
+	- Increases debugging complexity
+	- Config surface must be bridged (YAML → temp TOML) and kept in sync
+	- Operational integration remains more complex than a native implementation.
+	- Requires both rust and go toolchain
+### Option B: Port the relevant V1 Proof API + attestor logic to Go
+- **Pros:** 
+	- Aligns mission-critical code with Go (our preferred language)
+	- Eliminates Rust binary distribution and cross-language integration glue
+	- Simplifies debugging/ops
+	- Likely easiest to do now while scope is constrained
+	- Can use cosmos/kms signing libraries in attestor
+- **Cons:** 
+	- Higher upfront cost
+	- Must re-establish correctness, test coverage
+	- Requires internal audit of attestor
+	- Risk of regressions during port
+### Decision
+<span discussion-urls="discussion://3898c178-18cb-8030-bcec-e5a4d3b55849/3898c178-18cb-80cd-8b3d-f27c63fe57ae/3898c178-18cb-80c0-b6cf-001c815e32f4">We should port the relevant parts of the Proof API and the attestor to Go for V1.</span>
+Primary justification: The V1 scope is limited (excluding Cosmos- and Solana-specific logic), and it will never be easier to do than it is now. Our previous discussion around language uncovered compelling reasons why we would want mission critical code to be in golang and I think if we don’t port it now it is unlikely to happen. The longer the rust logic is used in production the worse the tradeoff becomes as we will be trading production-tested code reviewed under the bug bounty program for brand new code.
+Rough sizing estimate: Proof API port in \< 1.5 fte weeks; attestor port in \< 3 fte weeks. 
+Fallback: I don’t expect the port to be difficult, but if we run into unanticipated issues we can always fallback to the more minimal effort rust as subprocess route.
+### Scope of Port
+Proof-Api
+- \~1.5k LoC
+Aggregator (attestor fan-out / quorum)
+- [mod.rs](http://mod.rs)
+- [quorum.rs](http://quorum.rs)
+- [attestor_](https://github.com/cosmos/solidity-ibc-eureka/blob/main/packages/proof-api/lib/src/aggregator/attestor_data.rs)[data.rs](https://github.com/cosmos/solidity-ibc-eureka/blob/main/packages/proof-api/lib/src/aggregator/attestor_data.rs)
+- [config.rs](http://config.rs)
+Attested EVM proof building<br>[https://github.com/cosmos/solidity-ibc-eureka/blob/main/packages/proof-api/lib/src/utils/eth_attested.rs](https://github.com/cosmos/solidity-ibc-eureka/blob/main/packages/proof-api/lib/src/utils/eth_attested.rs) <br>[https://github.com/cosmos/solidity-ibc-eureka/blob/main/packages/proof-api/lib/src/utils/attestor.rs](https://github.com/cosmos/solidity-ibc-eureka/blob/main/packages/proof-api/lib/src/utils/attestor.rs) <br>[https://github.com/cosmos/solidity-ibc-eureka/blob/main/packages/proof-api/lib/src/utils/eth_eureka.rs](https://github.com/cosmos/solidity-ibc-eureka/blob/main/packages/proof-api/lib/src/utils/eth_eureka.rs) 
+Attestor
+We are relying on everything except the cosmos and solana related logic in the V1. The complexity is concentrated in the files below with the rest of the service being pretty standard grpc service plumbing, configuration, and signer logic which we will be relying on cosmos/kms for. \~1.4k LoC total for the files below<br><br>[https://github.com/cosmos/ibc-attestor/blob/main/apps/ibc-attestor/src/rpc/attestor.rs](https://github.com/cosmos/ibc-attestor/blob/main/apps/ibc-attestor/src/rpc/attestor.rs) <br>[https://github.com/cosmos/ibc-attestor/blob/main/apps/ibc-attestor/src/attestation.rs](https://github.com/cosmos/ibc-attestor/blob/main/apps/ibc-attestor/src/attestation.rs) <br>[https://github.com/cosmos/ibc-attestor/blob/main/apps/ibc-attestor/src/attestation_payload.rs](https://github.com/cosmos/ibc-attestor/blob/main/apps/ibc-attestor/src/attestation_payload.rs) <br>[https://github.com/cosmos/ibc-attestor/blob/main/apps/ibc-attestor/src/adapter/evm.rs](https://github.com/cosmos/ibc-attestor/blob/main/apps/ibc-attestor/src/adapter/evm.rs)
+### Tradeoffs Accepted
+- We accept short-term delivery risk and increased testing/review work in exchange for a cleaner long-term architecture and lower operational complexity.
+- We accept losing some immediate benefit of upstream Rust maturity in favor of consolidating language/runtime for mission-critical services.
+### Consequences
+- Engineering work: implement Go equivalents for the V1-required Proof API + attestor components; add compatibility tests against current behavior; audit.
+---
+*Links: *
+[GitHub - cosmos/ibc-attestor at go-plugin-poc](https://github.com/cosmos/ibc-attestor/tree/go-plugin-poc)
+---
+<empty-block/>
+</content>
+</page>