x-e-cute

x-e-cute is a Python trading runtime that can run in two ways:

• as a local CLI/runtime container via the root Dockerfile
• inside a Flare FCC extension container via external/fce-sign/python

The FCC path now uses the same swap execution code that powers the local runtime.

Criteria Coverage

• Flare FCC local container: external/fce-sign/docker-compose.yaml
• Cloudflare tunnel option: cloudflared compose profile in the same stack
• Uniswap swap flow from inside FCC: XECUTE_RUNTIME_MODE=swap-once or integrated
• Shared execution path: src/flare_uniswap_strategy/execution/service.py

Demo Positioning

This repository is intended to be a reproducible local demo of:

• Flare FCC local TEE-style deployment, proxying, and optional tunnel exposure
• application code running inside the FCC extension container
• real Uniswap API quote/swap execution from inside that container

The canonical demo is not "testnet alpha." Coston2 and Sepolia are useful for proving the end-to-end architecture, but their prices, liquidity, and gas conditions are not a meaningful environment for judging strategy quality or PnL.

For that reason, the submission is framed as:

• a real local FCC/TEE proof on Flare
• a real Uniswap API integration with real testnet transaction hashes
• a reviewer-friendly demo flow that is easy to reproduce from a fresh clone

The full strategy loop is included in the repo, but it should be treated as an optional testnet exercise rather than the main proof of value.

FCC Runtime Modes

Set XECUTE_RUNTIME_MODE in external/fce-sign/.env to one of:

• smoke: heartbeat-only FCC bring-up
• swap-once: one hardcoded Sepolia ETH -> USDC swap
• integrated: FCC-hosted retry loop around the same hardcoded swap
• strategy: live FTSOv2-driven strategy loop; included for completeness, but not the canonical testnet demo
• demo: reviewer-friendly periodic buy/sell loop inside FCC for easy reproduction

Quick Start

1. Copy external/fce-sign/.env.example to external/fce-sign/.env and fill in both the Coston2 registration values and the Sepolia/Uniswap runtime values.
2. Start the FCC stack:

cd external/fce-sign
docker compose build
docker compose up -d

3. Start the Cloudflare tunnel if you want it in the same stack:

docker compose --profile cloudflare up -d cloudflared

4. Follow docs/fcc_runtime_runbook.md for the full local-container, tunnel, registration, and validation flow.

For reviewers, the easiest path is usually:

1. prove the Flare local FCC path with go run ./cmd/run-test -p http://localhost:6676
2. run XECUTE_RUNTIME_MODE=demo for a reproducible periodic in-container demo
3. run XECUTE_RUNTIME_MODE=swap-once when you want a single easy-to-audit Sepolia transaction hash

When you register a new extension, always deploy a fresh InstructionSender first. Reusing an older sender contract can pin updateKey and sign to a stale extension ID.

Important Files

• external/fce-sign/python/app/xecute_runtime.py: boots x-e-cute inside the Flare extension container
• external/fce-sign/docker-compose.yaml: local FCC stack, optional Cloudflare tunnel, persisted logs
• src/flare_uniswap_strategy/execution/service.py: Uniswap quote/swap orchestration
• src/flare_uniswap_strategy/runtime/worker.py: integrated retry loop and live runtime worker