Skip to content

feat(chain): Introduce the octo-chain adapter trait and refactor Stellar behind it - #228

Open
Manuel1234477 wants to merge 1 commit into
Octo-Protocol-org:mainfrom
Manuel1234477:feat/chain-abstraction-trait
Open

feat(chain): Introduce the octo-chain adapter trait and refactor Stellar behind it#228
Manuel1234477 wants to merge 1 commit into
Octo-Protocol-org:mainfrom
Manuel1234477:feat/chain-abstraction-trait

Conversation

@Manuel1234477

Copy link
Copy Markdown

Summary

Adds a new octo-chain crate 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 + 'static and object-safe (Arc<dyn ChainAdapter>, via async_trait) since AppState is 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 (generalises deposit_address), and explain_failure (generalises explain_code in crates/api/src/routes/submit.rs).
  • StellarAdapter: a thin forwarding layer over octo-wallet-core — zero reimplementation of Stellar address/muxed-address logic.
  • ChainRegistry: HashMap<ChainId, Arc<dyn ChainAdapter>> with lookup returning ChainError::UnsupportedChain rather 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 AppState or octo-ingest through the new registry — octo-api/octo-ingest still call octo-wallet-core directly, exactly as before. That wiring is follow-up work once a second adapter exists to prove the boundary is right. Security: octo-chain has no dependency on octo-crypto and 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-core checks, and the conformance suite run against StellarAdapter).
  • cargo test --workspace --locked against 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.

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
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

feat(chain): Introduce the octo-chain adapter trait and refactor Stellar behind it

1 participant