feat(chain): Introduce the octo-chain adapter trait and refactor Stellar behind it - #228
Open
Manuel1234477 wants to merge 1 commit into
Open
Conversation
Introduces octo-chain as the boundary between business logic and chain-specific behaviour, with CAIP-2 chain identity and a capability model rather than a union-of-chains interface. Stellar becomes the first adapter, forwarding to octo-wallet-core with no behaviour change; the existing suite passes unmodified. Refs Octo-Protocol-org#213
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds a new
octo-chaincrate defining the boundary between Octo's business logic and any specific chain, and makes Stellar the first adapter behind it. Pure refactor: no existing crate's behaviour changes, and the pre-existing test suite passes unmodified.ChainId: a validated CAIP-2 chain identifier (namespace:reference, e.g.stellar:pubnet,eip155:1) per AD-1, with parsing/validation tested against the CAIP-2 spec's own examples plus explicit rejection cases (empty namespace, over-length reference, invalid characters).ChainKind/ChainCapabilities: a small required core plus a capability model (supports_memo,supports_muxed_addresses,has_reorgs,native_decimals) instead of a union of every field Stellar and EVM need — the trait shouldn't rot as new chains are added.ChainAdapter:Send + Sync + 'staticand object-safe (Arc<dyn ChainAdapter>, viaasync_trait) sinceAppStateis cloned across Axum handlers and the ingest supervisor spawns one task per wallet. Minimal surface:chain_id,capabilities,validate_address,normalize_address,derive_deposit_address(generalisesdeposit_address), andexplain_failure(generalisesexplain_codeincrates/api/src/routes/submit.rs).StellarAdapter: a thin forwarding layer overocto-wallet-core— zero reimplementation of Stellar address/muxed-address logic.ChainRegistry:HashMap<ChainId, Arc<dyn ChainAdapter>>with lookup returningChainError::UnsupportedChainrather than panicking.chain_conformance_suite: a reusable adapter-honesty test harness (deterministic derivation, idempotent normalization, no panics on garbage input) that feat(evm-core): secp256k1 keys, BIP-44 derivation, and EIP-55 addresses #217's EVM adapter will also be required to pass.docs/architecture.md: new section documenting the trait boundary, including an explicit split of what belongs in an adapter vs. in business logic.This issue intentionally does not wire
AppStateorocto-ingestthrough the new registry —octo-api/octo-ingeststill callocto-wallet-coredirectly, exactly as before. That wiring is follow-up work once a second adapter exists to prove the boundary is right. Security:octo-chainhas no dependency onocto-cryptoand never touches raw key material — adapters hold secrets exactly like business logic already does (by delegating to a chain's own signing crate).Closes #213
Test plan
cargo test -p octo-chain— 22 new tests (CAIP-2 parsing incl. rejection cases, registry lookup/replace, Stellar adapter byte-identical-to-wallet-corechecks, and the conformance suite run againstStellarAdapter).cargo test --workspace --lockedagainst a local Postgres 17 (matching CI's service container) — full existing suite passes unmodified.cargo fmt --all -- --check— clean.cargo clippy --workspace --all-targets --locked -- -D warnings— zero warnings.cargo build --workspace --locked— clean.