AegisLink

AegisLink is an Ethereum-to-Cosmos bridge systems project that proves wallet-driven bridge settlement from Ethereum into a Cosmos-style bridge zone and onward to Osmosis testnet.

It is designed like bridge infrastructure, not a token-transfer toy: Ethereum emits canonical bridge events, AegisLink owns verification, accounting, policy, and route state, and the relayer stack drives delivery into Osmosis through an IBC-shaped path.

Current position

The project now demonstrates a full Sepolia -> AegisLink -> Osmosis flow for fresh frontend-driven runs:

• A connected Sepolia wallet can submit an ETH bridge deposit from the web/ frontend.
• The public bridge relayer observes Ethereum events, waits for configured confirmations, and submits the claim into AegisLink.
• AegisLink verifies threshold attestations, mints a canonical bridged denom such as ueth, updates bridge accounting, and registers local wallet balances.
• The backend can auto-initiate the AegisLink-to-Osmosis leg, open or reuse the live rly path, and deliver over ICS20 to an Osmosis testnet wallet.
• The frontend follows the bridge state and resolves the completed Osmosis receipt into a direct destination transaction link.

The current repo is still honest about its boundary: this is a security-conscious bridge prototype and demo network harness, not a production public bridge or fully trustless Ethereum light-client bridge.

Why it stands out

Area	What is implemented
Source chain	Ethereum gateway contracts for native ETH and ERC-20 custody, deposit events, release execution, pause controls, and verifier-bound release proofs
Verification	Narrow verifier interface, single-attester verifier, threshold verifier, EIP-712-style digests, low-s signature enforcement, signer-set versioning, and signer rotation
Bridge zone	Store-backed AegisLink runtime with bridge, bank, registry, limits, pauser, governance, route, metrics, status, and wallet-balance surfaces
Safety controls	Replay protection, asset registry checks, rolling-window rate limits, pause controls, governance authority checks, supply-accounting invariant, and persistent circuit breaker
Relayers	Public bridge relayer and route relayer with replay persistence, loop mode, retry/backoff behavior, structured run summaries, and recovery-drill coverage
IBC delivery	Real Osmosis testnet delivery through rly, ICS20 transfer handling, acknowledgement, timeout, refund, and stale timeout-height lifting
Frontend	Wallet-connected Sepolia transfer flow, live status polling, bridge-stage progress UI, Osmosis receipt state, and destination transaction link
Operations	One-command public backend launcher, Prometheus-style metrics, Grafana scaffold, incident drills, pause/recovery runbooks, and upgrade/rollback notes

What is real today

• Ethereum deposit observation and release execution run through the live local Anvil path.
• The real-wallet bridge path distinguishes native ETH from ERC-20 custody, supports native ETH deposit and release, and mints canonical bridged denoms such as ueth and uethusdc.
• The public AegisLink testnet scaffold can boot a reproducible single-validator SDK-store home through scripts/testnet/bootstrap_aegislink_testnet.sh, with operator and network config artifacts under deploy/testnet/aegislink/.
• The Sepolia wallet bridge scripts can take a deployment from contract addresses to a deposit-ready AegisLink home, and public-bridge-relayer can deliver native ETH and ERC-20 deposits into real AegisLink wallet balances or redeem them back to Sepolia through the live RPC log path.
• The live AegisLink-to-Osmosis IBC leg is proven: the single-validator demo node can connect to Osmosis testnet through rly, open a real connection and channel, send ueth over ICS20, and credit a real osmo1... wallet with the resulting ibc/... denom.
• The repository has a real frontend surface in web/: users can connect a Sepolia wallet, choose a Cosmos destination, submit an ETH bridge deposit, watch a live bridge-status timeline, and finish on the Osmosis receipt state with a direct destination transaction link.
• The public-wallet operator flow has a one-command backend launcher: scripts/testnet/start_public_bridge_backend.sh can stand up a seeded demo node, a live Osmosis path, the public bridge relayer, and automatic lifting of stale IBC timeout heights against the live Osmosis LCD height.
• Ethereum now has both the original narrow single-attester verifier and a threshold-verifier path with signer-set rotation support.
• Ethereum verifiers now build EIP-712-style attestation digests, reject non-low-s signatures, and the gateway release path is guarded against reentrant token callbacks.
• AegisLink owns bridge, bank, registry, limits, pauser, and route state in a persistent runtime with init, start, query status, and wallet balance queries.
• AegisLink now also has a daemon-style single-node block loop shim in aegislinkd start --daemon that advances height automatically and drains queued deposit submissions through the application boundary.
• AegisLink bridge attestations now bind to an explicit signer-set version, carry cryptographic signer proofs, and the bridge keeper can activate, expire, and reject mismatched or invalid signer sets.
• AegisLink rate limits now track rolling-window usage instead of only comparing a single transfer amount to a static ceiling.
• The bridge runtime now exposes a supply-accounting circuit breaker, so corrupted supply state can trip the bridge into an explicit reject-only mode instead of failing silently.
• AegisLink SDK-store persistence now uses prefix-keyed per-record state instead of whole-module JSON blobs, and the app runtime serializes mutations through a single access boundary with focused race-smoke coverage.
• The bridge-relayer and route-relayer are real services with replay persistence and route lifecycle handling.
• The bridge-relayer and route-relayer now also support --loop daemon mode with poll intervals, temporary-failure backoff, and repeated run summaries for long-running local operation.
• The Phase 6 route path now boots a dedicated destination runtime through osmo-locald, and route-relayer can move a transfer from an AegisLink home into that destination home without the old HTTP mock-target entrypoint.
• The Phase E route path now also uses Hermes-shaped local packet verbs: route-relayer relays recv-packet and later acknowledge-packet, while bootstrap_ibc.sh writes explicit local IBC link metadata into both runtime homes.
• Routed transfers go through packet-shaped delivery, destination-side execution, later acknowledgement, and explicit completion, failure, timeout, or refund handling.
• The destination target tracks packets, execution receipts, balances, pools, swaps, and acknowledgement state through public inspection endpoints.
• Route profiles can now constrain allowed action types, and the live routed path supports both swap and stake actions with recipient and path overrides.

What is a local harness today

• AegisLink is a persistent Cosmos-inspired runtime, not yet a full networked CometBFT or ABCI chain.
• The node lifecycle shim is real enough for the targeted scope, but it is still not a full CometBFT / ABCI / BaseApp runtime.
• The original Osmosis-lite harness is still present as a dedicated local destination runtime with its own home, config, state, and local IBC link metadata.
• The new public IBC path is now real enough to prove a fresh frontend-driven Sepolia deposit -> AegisLink -> Osmosis testnet wallet run, but the repo still treats that path as demo-grade. Repeat-run hardening on the long-lived backend, especially around automatic delivery bookkeeping and status resolution, is still ongoing.
• The verifier model is still a v1 verifiable-relayer plus threshold-attestation path, not a light client.

Why this project is not a toy

• It uses a dedicated Cosmos bridge zone instead of wiring Ethereum directly into a single destination app.
• It separates observation, verification, policy enforcement, settlement, and routing.
• It proves inbound minting, redeem-back-to-Ethereum, and routed delivery instead of stopping at a single deposit event.
• It treats destination execution as first-class state, including async acknowledgements, swap failures, and refund-safe timeout handling.
• It documents security practices, audit boundaries, recovery drills, and roadmap limits in the repo instead of leaving them implicit.
• It is honest about the trust model and runtime limits instead of pretending the local harness is a production chain.

Architecture snapshot

flowchart LR
    W["Wallet / Frontend"] --> E["Ethereum Gateway"]
    E --> BR["Public Bridge Relayer"]
    BR --> A["AegisLink Runtime"]
    A --> IBC["IBC / rly path"]
    IBC --> O["Osmosis Testnet Wallet"]
    O --> IBC
    IBC --> A
    A --> BR
    BR --> E

Loading

Use Current flow diagrams for the fuller end-to-end view and the route lifecycle diagram.

Documentation map

Start here if you want the basics:

• Bridge basics
• Ethereum, Cosmos, IBC, and Osmosis primer

Read these for the protocol design:

• System architecture
• Current flow diagrams
• Security and trust model
• Security practices
• Verifier evolution
• Project positioning
• Architecture spec

Use these to build or review the project step by step:

• Step-by-step roadmap
• Tech stack and repo plan
• 0-to-100 execution plan
• Final stretch plan
• Future realism plan
• Gap remediation plan
• Real wallet asset bridge plan
• Initial implementation plan, historical

Use these for operational and launch thinking:

• Security model summary
• Security practices
• Observability plan
• Demo walkthrough
• Public bridge ops runbook
• Pause and recovery runbook
• Incident drills
• Upgrade and rollback runbook

For a fresh public-wallet demo bring-up, start with the public bridge ops runbook and the one-command backend launcher in scripts/testnet/start_public_bridge_backend.sh.

What AegisLink v1 should say publicly

Use phrasing like:

• "AegisLink v1 is a verifiable-relayer bridge with threshold attestations."
• "AegisLink enforces replay protection, asset registration, rolling-window rate limits, and pause controls."
• "AegisLink has a roadmap toward stronger Ethereum verification."

Do not describe v1 as fully trustless or fully light-client verified.

Five-minute demo

If you want the fastest way to show the project working locally, run:

make demo

If you want the inspection-focused path that exercises the public target surfaces:

make inspect-demo

If you want the newer dual-runtime route path that boots both AegisLink and the destination runtime through their own homes:

make real-demo
make inspect-real-demo

That demo exercises:

• a live local Ethereum deposit
• relayer submission into AegisLink
• outbound routing into the Osmosis-style target
• destination-side packet receipt, execution, and swap lifecycle
• public target queries for packets, executions, pools, balances, and swaps

The real Phase 6 route demo exercises:

• destination runtime bootstrap through scripts/localnet/bootstrap_destination_chain.sh
• command-backed route delivery into osmo-locald
• destination-side balance and packet inspection from the destination home
• source-side completion on the AegisLink SDK-store runtime

For the full walkthrough, use Demo walkthrough. For the honest reviewer framing, use Project positioning.

Runtime commands

aegislinkd now has a more node-like local runtime surface:

go run ./chain/aegislink/cmd/aegislinkd init --home /tmp/aegislink-home --chain-id aegislink-devnet-1 --runtime-mode sdk-store-runtime
go run ./chain/aegislink/cmd/aegislinkd start --home /tmp/aegislink-home
go run ./chain/aegislink/cmd/aegislinkd query status --home /tmp/aegislink-home
go run ./chain/aegislink/cmd/aegislinkd query metrics --home /tmp/aegislink-home
go run ./chain/aegislink/cmd/aegislinkd query signer-set --home /tmp/aegislink-home
go run ./chain/aegislink/cmd/aegislinkd query signer-sets --home /tmp/aegislink-home
make test-real-chain
make test-real-abci
make test-real-ibc
make monitor

That flow creates and uses:

• a runtime config file
• a runtime genesis file
• a Cosmos KV-store-backed runtime store
• service-backed tx and query command paths

Current checkpoint

As of April 28, 2026:

• the live local Ethereum bridge loop and fresh public Sepolia -> AegisLink -> Osmosis frontend flow are proven end to end
• Phase 5 is now complete as a single-node SDK-store runtime milestone: AegisLink has store-backed keeper persistence, generated bridge or route proto surfaces, service-backed CLI responses, and a real-chain bootstrap or e2e proof through aegislinkd init, start, tx, and query
• Phase 6 is now complete for the current repo scope as a dual-runtime local route milestone: a destination runtime can be bootstrapped through osmo-locald, AegisLink can initiate routed transfers through the ibcrouter packet lifecycle, and route-relayer can drive acknowledgement completion against the destination home without the old HTTP target
• Phase 7 is now complete for the current repo scope: the Ethereum side has a real threshold-verifier path with signer rotation, AegisLink attestations bind to versioned signer sets with activation and expiry rules, and the runtime exposes query signer-set, query signer-sets, and signer-set status summaries
• the verifier evolution path is now documented explicitly, so the trust-model story is inspectable instead of buried in keeper logic or contract code
• Phase 8 is now complete for the current repo scope: the binaries expose Prometheus-style metrics, the repo ships a local monitoring scaffold, and the main operator recovery drills are codified in runbooks and e2e coverage
• the local monitoring scaffold now exists too: Prometheus scrape config, Grafana provisioning, an initial destination-ops dashboard, and make monitor
• Phase 9 is now complete for the current repo scope: the ibcrouter can register multiple destination route profiles with allowed assets, memo-policy guardrails, and allowed action types, the governance module can apply asset, limit, and route-policy changes through a recorded proposal path, and the routed execution layer now supports both swap and stake
• Phase A of the gap-remediation plan is now complete for the current repo scope: Go-side bridge verification now requires cryptographic signer proofs instead of signer-name lists, and governance policy changes now require an explicit configured authority
• Phase B of the gap-remediation plan is now complete for the current repo scope: bridge volume controls now use persisted rolling-window usage tracking, and the bridge runtime now trips a visible circuit breaker when accounting invariants are violated
• Phase C of the gap-remediation plan is now complete for the current repo scope: chain state is persisted as prefix-keyed SDK-store records instead of whole-module JSON blobs, disk-backed runtime reloads are covered, and the app exposes a serialized runtime boundary with race-smoke coverage
• Phase D of the gap-remediation plan is now complete for the current repo scope: bridge and route relayers can run as loop-based daemons with graceful shutdown and temporary-failure backoff, and the repo now has focused Foundry invariant coverage plus Go fuzz coverage for bridge supply and route-refund safety
• Phase E of the gap-remediation plan is now complete for the current repo scope: AegisLink has a daemon-style single-node block loop with queued deposit delivery through the app boundary, and the dual-runtime route path now uses Hermes-shaped local packet relay and acknowledgement verbs plus explicit ibc-link.json metadata in both runtime homes
• Phase F of the gap-remediation plan is now complete for the current repo scope: the Ethereum verifier path now uses typed-data-style digests, rejects non-low-s signatures, the gateway release flow is reentrancy-guarded, and the v1 upgradeability stance is documented explicitly as immutable or non-proxy by design
• the gap-remediation plan is now complete for the current repo scope
• Phase 1 of the fuller route-harness plan is complete
• Phase 3 runtime and operator surfaces now include structured startup and run logs plus clearer runtime validation
• Phase 4 hardening now adds stronger replay and supply invariants, a narrow verifier interface, and demo-facing failure counters
• the routed side now has explicit packet, execution, and acknowledgement lifecycle state
• the next roadmap focus is deeper realism beyond the completed phase set: pushing AegisLink from the current daemon shim toward a fuller networked CometBFT or BaseApp runtime, replacing the current Hermes-shaped local bridge with fuller real IBC-Go or Hermes-backed networking, and validating the monitoring stack on a machine that has Docker installed
• the public-wallet bridge plan is now implemented through Phase J for the current repo scope: native ETH and ERC-20 custody are modeled explicitly, AegisLink can mint bridged balances into a real Bech32 wallet, the public-testnet scaffold and Sepolia deployment scripts are in place, and the public relayer now covers both deposit delivery and redeem-back-to-Sepolia flows
• Phase K now has a live public IBC proof for the current repo scope: .env.public-ibc.local.example, scripts/testnet/bootstrap_public_ibc.sh, and scripts/testnet/bootstrap_rly_path.sh can bootstrap the route metadata, and the single-validator AegisLink demo node has now opened a real Osmosis testnet channel and delivered ueth to a real osmo1... wallet over rly
• the repository now also has a premium black-and-white frontend in web/ plus a one-command public backend launcher, so the public demo path is no longer only a CLI exercise
• a fresh frontend-driven Sepolia -> AegisLink -> Osmosis run is now proven in the current repo scope
• the public frontend flow now also resolves the completed Osmosis receipt back into a direct destination transaction link, so the UI no longer stops at a status label alone
• the remaining public-wallet gap is now narrower and more operational: repeated frontend-driven runs on one long-lived backend still need more hardening around auto-delivery idempotency, receipt/status bookkeeping, and restart-free operator behavior

The current repo shape is:

• chain/aegislink: persistent runtime, bridge state machine, safety modules, and route lifecycle handling
• contracts/ethereum: Ethereum event source and release verification contracts
• relayer: observation, attestation, replay, live forward or reverse bridge pipeline, and route-target handoff services

Future scope

The remaining work is now concentrated in a smaller set of realism and hardening tracks rather than broad missing features:

1. Public-flow hardening: make repeated frontend-driven Sepolia -> AegisLink -> Osmosis runs reliable on one long-lived backend without restart workarounds, especially around auto-delivery idempotency and final receipt bookkeeping.
2. Networked chain realism: push AegisLink beyond the current single-node daemon shim toward a fuller networked CometBFT or BaseApp-style runtime with a cleaner validator and node lifecycle story.
3. Fuller IBC transport: replace the current Hermes-shaped local packet bridge with stricter real IBC-Go or Hermes-backed networking and more reproducible public testnet path automation.
4. Operator and deployment hardening: validate the monitoring stack on a Docker-capable machine, tighten alerts and runbooks, and make the public demo backend easier to stand up and keep healthy.
5. Destination expansion only after the above: add more routes, assets, or destination-side actions only once the current Sepolia-backed Osmosis path is boringly reliable.

Use Project positioning for the short reviewer-facing version and Future realism plan for the longer engineering roadmap.

Fresh verification checkpoints that already pass in this repo:

• go test ./chain/aegislink/...
• forge test --offline
• go test ./relayer/...
• cd tests/e2e && go test ./...

The local route-harness, operator-surface, SDK-store runtime, dual-runtime route, threshold-verifier, recovery-drill, and protocol-expansion milestones are now in place. The next realism work from here is deeper networked chain and IBC integration rather than more local-harness breadth.