twocrypto-cpp

Standalone C++17 TwoCrypto pool checkout, exact-integer adapter, and pinned Vyper parity fixtures. This repository owns the pool state machine and its policy ABI/safety envelope. It does not own event feeds, market scenarios, evaluator execution, optimization, plotting, or concrete experimental policy profiles; those belong to curve-fx-arb-harness and curve-fx-optimization.

The checkout provides the header-only CMake target twocrypto::pool (alias twocrypto_pool). The twocrypto_parity environment and exact harness are private validation utilities used by the sibling checkouts.

Repository split

• twocrypto-cpp — C++ Twocrypto pool implementation and Vyper parity; no market simulation or experiment orchestration.
• fx-arb-harness — C++ arbitrage simulation and evaluator protocol; owns market-event execution and raw metrics.
• fx-optimization — cluster orchestration, parameter grids, scoring, result storage, robustness analysis, heatmaps, and replay.

Checkout-local setup

Requirements: Python 3.12, uv, CMake 3.14+, a C++17 compiler, and Boost 1.79+ headers. Run Python and CMake setup independently; Python is only needed for parity utilities.

cd /path/to/twocrypto-cpp
uv sync --frozen --extra test
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --parallel

The standalone CMake build enables pool-local tests by default. The cmake --install step below writes a disposable checkout-local prefix for the sibling harness; it is not a system installation or a published SDK. Policy implementations remain private parity fixtures and are not installed. The staged target retains the native pool policy, policy ABI, and compiled-policy passthrough.

cmake --install build --prefix "$PWD/_install"

An installed consumer needs only Boost and the exported pool target:

find_package(twocrypto_pool CONFIG REQUIRED)
add_executable(pool_consumer main.cpp)
target_link_libraries(pool_consumer PRIVATE twocrypto::pool)

Use -DCMAKE_PREFIX_PATH=/path/to/twocrypto-cpp/_install when configuring the consumer. The package config contains no checkout revision, dirty-state, or concrete-policy metadata and has no source-relative dependencies.

C++ API and transaction snapshots

The pool owns a value-semantic mutable transaction snapshot:

namespace tc = arb::pools::twocrypto_fx;
using Pool = tc::TwoCryptoPool<tc::uint256>;

Pool::MutableSnapshot before = pool.mutable_snapshot();
// speculative transaction
pool.restore_mutable(before);
bool native_fee = pool.uses_native_fee_model();

MutableSnapshot covers mutable pool, policy, research, and hook-metric fields changed by a transaction while excluding immutable configuration. It is allocation-free. uses_native_fee_model() is true for native pools and for compiled policies that explicitly declare zero-return native-fee fallback.

Private compiled-policy extension

PolicyKind::Compiled is a final-executable extension point. The harness (or another private executable) may define TWOCRYPTO_POLICY_HEADER to a regular header that provides the source contract's ChallengeFeePolicy<T> in arb::pools::twocrypto_fx. The pool retains clamping, step limiting, LP protection, rollback, and actuator authority. Without a selected header, pools/twocrypto_fx/policies/compiled_passthrough.hpp delegates to native surfaces. Concrete policy selection is intentionally owned by that executable, not by the installed pool package. The pool checkout exposes TWOCRYPTO_PARITY_POLICY_PATH only for private parity test/benchmark targets; that value is never exported with twocrypto::pool.

The checked-in include/pools/twocrypto_fx/policies/yieldbasis.hpp is the exact uint256 translation of the pinned YBTwocryptoPolicy.vy. Build the private policy evaluator and pool harness, then run the 59 upstream policy cases and the pool-integrated state comparison:

cmake -S . -B build/yb-parity -DCMAKE_BUILD_TYPE=Release \
  -DTWOCRYPTO_POOL_BUILD_TESTS=ON \
  -DTWOCRYPTO_POOL_BUILD_BENCHMARKS=ON \
  -DTWOCRYPTO_PARITY_POLICY_PATH="$PWD/include/pools/twocrypto_fx/policies/yieldbasis.hpp"
cmake --build build/yb-parity \
  --target yb_policy_evaluator_i benchmark_harness_i --parallel
TWOCRYPTO_YB_EVALUATOR="$PWD/build/yb-parity/yb_policy_evaluator_i" \
  TWOCRYPTO_HARNESS_I="$PWD/build/yb-parity/benchmark_harness_i" \
  uv run --frozen --no-sync pytest -q -o addopts='' \
  tests/test_yb_policy_parity.py \
  tests/test_boa_parity_fxswap_ext_fee.py::test_boa_cpp_pool_integrated_yb_policy_parity

The installed pool package does not select or hash a concrete policy. Policy macros and any evaluator identity fields remain private to parity executables.

Python parity

Sync the pinned Python environment with uv sync --frozen --extra test. The lockfile pins Vyper 0.4.3, titanoboa 0.2.8, snekmate 0.1.2, and pytest 8.4.1.

The checkout exposes one exact parity route through twocrypto_parity.cpp_pool_runner; it invokes an already-built benchmark_harness_i and never configures or writes into the source tree. The Boa adapter is used by the authority test to compare the same deterministic action sequence against the pinned reference. The action domain has one persistent LP caller. Per-account sender/receiver fields fail closed; snapshots compare that caller's LP balance as well as pool state.

cmake -S . -B build/parity -DCMAKE_BUILD_TYPE=Release \
  -DTWOCRYPTO_POOL_BUILD_BENCHMARKS=ON
cmake --build build/parity --target benchmark_harness_i --parallel
TWOCRYPTO_BUILD_ROOT="$PWD/build/parity" \
  uv run --frozen --no-sync twocrypto-parity \
  /path/to/pools.json /path/to/sequences.json --out /tmp/cpp.json

benchmark_harness_i emits exact decimal state snapshots. Authority tests create all pool and action inputs in temporary directories.

Provenance, audit, and data posture

The Vyper authority is the reference/twocrypto-ng Git submodule. Its tracked gitlink commit is the revision record; .gitmodules records the upstream URL and invariant-change branch. Private parity reports may retain the pool revision, submodule revision, compiler/build mode, harness identity, selected-policy ID, and explicit input paths. These details are not part of the installed pool package; the pool CMake does not inspect Git or policy headers.

This private repository does not grant redistribution rights for its source or pinned reference. Obtain maintainer authorization before sharing either; never substitute an unpinned checkout for an unavailable reference.

The pool boundary is deliberately narrow: build this checkout first; the harness consumes its staged target, and the orchestrator supplies concrete profiles and all workflows. Do not use historical checkout names or source-relative include paths as runtime dependencies.