FerroCore Technicals

Definition

Mission: Build an inspectable path from a coherently converted indicator suite to account-sized crypto portfolio decisions through a dynamic, multi-timeframe, crypto-native rebalancer that treats execution and risk as part of the result.

Vision

Market observation, indicator logic, sector classification, portfolio policy, execution replay, accounting, runtime authority, and presentation should be independently testable and replaceable. The interface should follow verified models and records instead of defining them.

First real minimum viable product

The first real MVP is a dynamic multi-timeframe crypto-native rebalancer, done right.

Minimum universe

BTC and ETH.

Equivalence

Include ETH-equivalent assets while preserving their individual identity and added risk.

Yield

Account for the trade-off between additional yield and the additional risk required to obtain it.

Exposure boundary

Avoid unreasonable exposure such as leverage.

Time structure

Use multiple timeframes dynamically; the timeframe set, interaction rules, and rebalance triggers remain to be specified.

Portfolio posture

Zero direct stablecoin exposure is being taken seriously; the exact accounting and execution consequences remain to be specified.

ETH equivalence describes a portfolio role, not equality of risk. “Crypto-native” establishes the intended asset posture here; it does not yet select a chain, venue, custody model, wrapper, or accounting reference. The broader mostly Etherian sector/TAM model may extend the MVP; the exact initial universe beyond the BTC/ETH floor remains open.

Goals and sequence

Now

Define the architecture and its contracts; continue converting the indicator suite coherently; specify the multi-timeframe rebalancer, BTC/ETH floor, ETH-equivalence model, yield/risk treatment, and exposure limits without reviving the SynthCore frontend.

Research path

Publish the original Pine indicators over the next season while working toward parity or better with relevant open-source indicators.

System path

Separate observed markets from account-sized executable claims; add explicit intent, submission-policy, ledger, and reconciliation boundaries above the current block-pinned foundation.

Later

Extend into the broader sector/TAM model and harden strategies only after their inputs, portfolio decisions, execution assumptions, and accounting can be inspected independently. Signing remains beyond replay, forward shadow execution, and bounded-canary reconciliation.

This sequence does not establish a release date, approved strategy, or live-trading commitment.

MVP decision ledger

This separates the product definition already stated from decisions that still require human authorship.

Compartmental architecture

The table below separates system responsibilities. Names describe zones, not implemented Rust types.

market observation ──▶ multi-timeframe research ──┐
asset / equivalence / yield model ────────────────┼─▶ portfolio policy ─▶ targets
sector / universe model (extension) ──────────────┘

targets ─▶ intent + submission policy ─▶ replay / shadow / bounded canary
chain archive + pinned state ─────────────────────▲              │
                                                                  ▼
                                                               ledger ─▶ views

signing / broadcasting: absent; later isolated behind runtime authority

Independence rules

1. Observation records do not contain strategy or portfolio decisions.
2. Indicator logic does not own the asset universe, wallet state, execution route, or interface.
3. Timeframe identity remains explicit; combining timeframes is a portfolio-policy decision rather than an ingestion side effect.
4. ETH and ETH-equivalent assets retain separate identities. Portfolio equivalence cannot silently erase different yield sources or risks.
5. The asset/universe models and portfolio policy are versioned separately so an eligibility change is not silently a strategy change.
6. Portfolio policy emits targets; it does not invent fills, apply leverage, or mutate balances.
7. Execution evaluates declared intents; it does not decide which assets deserve capital.
8. The ledger consumes explicit results and remains independent from candle construction and display formatting.
9. Signing and custody remain isolated behind a later authority boundary rather than becoming ambient library capability.
10. The frontend reads system state; it is not the canonical store for research, policy, execution, or accounting.

Current code boundary

The question declared by the project is narrower than a candle backtest: what would an account-sized transaction have done under a declared submission policy at a specific Ethereum state?

The repository assigns broad market collection and candle construction to SynthCandles. It assigns block-pinned execution state, intent acceptance, and a reproducible cash ledger to FerroCore. That second statement is architectural direction, not the present implementation: version 0.1.0 contains archive and quote foundations but no general submission-policy type, portfolio ledger, or transaction executor.

The current crate is not the MVP rebalancer. It does not combine timeframes, define BTC/ETH weights, classify ETH equivalents, measure risk-adjusted yield, or emit rebalance decisions.

crate

ferrocore 0.1.0 · Rust 2021

archive schema

1

programs

ferro-backfill · ferro-quote

implemented scope

one-pool V3 archive · one-hop V3 quote · pure stable assessment

local verification

11 unit tests passed · 2026-07-17

external verification

none established by the available source record

Command-line interface

ferro-backfill <pool> <from-block> <to-block> <output.jsonl>
  [--rpc URL] [--chunk BLOCKS]

ferro-quote <block> <token-in> <token-out> <fee> <amount-in-raw>
  [--rpc URL] [--quoter ADDRESS]

Both commands accept the endpoint through ETH_RPC_URL or --rpc. The backfill chunk defaults to 2,000 blocks. The quote amount is an unsigned base-10 integer in the token's smallest units. ferro-quote prints one JSON result; ferro-backfill writes JSONL plus a manifest and prints a completion summary to standard error.

Historical swap archive

ferro-backfill requests logs matching the Uniswap V3 Swap signature for one declared pool and inclusive block range.

Write path

1. Canonicalize the pool address; reject a reversed range or zero block chunk.
2. Read the chain ID and complete starting and ending block references.
3. Request logs in ascending block chunks, then sort each response by block number, transaction index, and log index.
4. Fetch only the headers referenced by returned logs, in JSON-RPC batches of at most 100.
5. Decode and validate each event, reject duplicate event identities, and append exact serialized bytes to a process-specific temporary JSONL file while computing SHA-256.
6. Flush and sync the temporary file. Fetch the ending block again and reject the run if its hash changed.
7. Rename the JSONL into place, then write and rename a separate manifest file.

Schema-v1 event

Each event records schema version, chain ID, canonical log address, complete block reference, transaction hash and index, log index, sender, recipient, signed raw amount0 and amount1, sqrtPriceX96, active liquidity, tick, and the original five-word ABI data field. Amount and price-state values are serialized as decimal strings rather than floating-point numbers.

The event identity is block hash : transaction hash : log index. The record does not contain token addresses, token decimals, pool fee tier, human display amounts, or a derived execution price.

Manifest

The manifest records schema version, product name, chain ID, declared pool, starting and ending block references, event count, SHA-256 of the exact JSONL byte stream, and generation time. The digest detects a changed byte stream after generation. It does not authenticate the RPC provider or prove that the returned logs were complete.

Block-pinned quote

ferro-quote fetches a block reference by number, constructs calldata for quoteExactInputSingle((address,address,uint256,uint24,uint160)), and calls the configured QuoterV2 address using that block hash with requireCanonical: true. The CLI defaults to the mainnet QuoterV2 address defined by the crate and sets sqrtPriceLimitX96 to zero.

The intent records chain ID, complete block reference, quoter, token addresses, fee, raw input amount, and price limit. Validation canonicalizes addresses; rejects identical tokens, zero input, an input wider than uint256, a fee wider than uint24, and a price limit wider than uint160; and never converts through floating point.

The decoder requires exactly four ABI words and returns raw amount out, post-swap sqrtPriceX96, initialized ticks crossed, and QuoterV2's pool-swap gas estimate.

Interpretation boundary

• This is a one-hop, exact-input-single quote for one fee tier—not route discovery or order splitting.
• The result is an eth_call against QuoterV2, not a router transaction, submitted order, or observed fill.
• Router overhead, calldata gas, priority fee, base-fee payment, inclusion delay, MEV, and submission policy are absent.
• The code does not verify token bytecode, pool existence, enabled fee tiers, quoter bytecode, or liquidity before the call.
• The default quoter constant is mainnet-specific; selecting another chain requires the operator to supply the correct address.
• The CLI obtains chain ID and block reference from its RPC client, but the reusable intent type does not itself prove that its chain ID, block fields, and provider all agree.
• requireCanonical asks the provider to reject a noncanonical hash; it does not remove provider trust.

RPC transport and failure behavior

transport

HTTP or HTTPS · rustls for TLS

request IDs

monotonic process-local integers

header batches

maximum 100 requests

HTTP retries

429 and 5xx · up to 8 retries after the first attempt

retry delay

integer Retry-After seconds, or 250 ms exponential backoff · clamped to 15 s

not retried

transport failures, JSON-RPC errors in HTTP 200 responses, decode failures

The client has no explicit request timeout. Transport errors are reduced to method plus a general failure class so the endpoint URL is not echoed. Non-success HTTP bodies are whitespace-compacted and capped at 500 characters. JSON-RPC error messages returned inside a successful HTTP response are preserved as supplied by the provider.

Failures remain typed: invalid arguments or hex, invalid swap data, transport/HTTP/JSON-RPC failures, missing results, reorganization, duplicates, removed logs, filesystem errors, and JSON errors stop the operation rather than being converted into a plausible quote or partial success.

StableGuard module

StableGuard is a pure assessment function from an earlier stable-asset accounting design. It does not fetch oracle, Curve, depth, or token data. A caller supplies token identity, direct and optional Curve-derived prices, optional Curve imbalance, executable depth, and oracle age.

Prices use integer parts per million, where 1,000,000 equals one dollar. Valuation takes the lowest supplied observation and caps it at one dollar. Default thresholds are a 50-basis-point soft deviation, 200-basis-point hard deviation, 2,500-basis-point maximum Curve imbalance, $100,000 minimum caller-reported executable depth, and 300-second maximum oracle age. Price deviation is absolute, so a sufficiently large over-peg observation can also halt eligibility even though valuation never exceeds one dollar.

A soft deviation returns Haircut while leaving the asset eligible as a quote. A hard deviation, stale oracle, insufficient depth, or excessive supplied imbalance returns Halted. Curve data is optional; its absence does not itself halt an assessment.

This module is implemented but is not wired to either CLI. Its presence does not establish portfolio exposure or override the current design direction taking zero direct stablecoin exposure seriously.

Verification record

cargo test --offline passed locally on 2026-07-17: 11 passed, 0 failed, 0 ignored.

Not established by those tests

• No archive filesystem, digest, manifest, reorganization, or atomic-replacement integration test.
• No RPC batch, retry, timeout, provider-divergence, or error-sanitization test.
• No live or recorded mainnet quote fixture and no comparison with an executed router transaction.
• No CLI tests, fuzz tests, property tests, or external audit.
• No evidence yet for a submission policy, cash ledger, forward shadow executor, bounded canary, or live reconciliation.

Open engineering review targets

1. Decide and test the exact archive commit protocol, including JSONL/manifest pairing and crash recovery.
2. Decide whether pool-address equality, ABI integer widths, protocol tick limits, token metadata, and fee tier belong in schema 1 or a later schema.
3. Define provider provenance and the level of independent verification required before an archive is accepted.
4. Define a quote record that binds network, provider state, quoter identity, assumptions, and any later cost model.
5. Specify intent acceptance, submission policy, ledger transitions, and reconciliation before describing FerroCore as an execution engine rather than an execution-replay foundation.