BUFX

BUFX is the FX trading venue built on top of Forex de la Arana/Telarana liquidity. It provides the user-facing spot, RFQ, and future perp-liquidity request layer while Telarana owns cross-hub liquidity movement, Circle Gateway execution, Morpho markets, and destination-hub settlement.

The current target is:

BUFX venue intent
  -> BUFX request + fee routers
  -> Telarana Gateway context
  -> Forex de la Arana hub execution
  -> Circle Gateway USDC rail between Avalanche Fuji and Arc
  -> destination hub FX / Morpho action

BUFX never calls Circle Gateway directly and does not custody Telarana liquidity, trader margin, insurance funds, or Morpho collateral.

Customer routing is hub-local: Avalanche customers use Avalanche spokes and Arc customers use Arc spokes. Cross-hub Gateway movement is internal Telarana liquidity logistics, not a BUFX user bridge flow.

Live Testnet Deployment

Avalanche Fuji, deployed from the live Telarana hook integration:

Contract	Address
BuFxTelaranaRequestRouter	0x46cC11feD4F497C0C091b7bE5a1A21af133c26f1
BuFxVenueRequestRouter	0x84EE03C52B89B01315C9572520192274b570D2c3
BuFxFeeConfig	0xa589040434735710aEF173e31e421a2d0a20Dd17
BuFxFeeCollector	0x1894C8c84F3a8DD1e17B237008a197feD2E299B6

Arc testnet, deployed as the Arc-origin BUFX request stack:

Contract	Address
BuFxTelaranaRequestRouter	0xea11AfDc70eD0489346AC9d488C17155384B459c
BuFxVenueRequestRouter	0xa73208b62AF9a87fb5e2b694B27f510D70e17746
BuFxFeeConfig	0x746e727E3aa25050c24a80E27E3bAEd9Ec6DdF6C
BuFxFeeCollector	0x27dBDA42Adb904115CadE37C949BBF670e0Ff09D

Smoke request tx:

0xa5880a065ac428ffb43ee1d32462eda5f5289ce23798dbec33aacf1c61514281

Generated deployment metadata:

deployments/testnet/bufx-telarana-router.generated.json

Telarana Integration

Live Forex de la Arana V2 / Stage-6 destination hooks:

Route	Destination Hook (V2)
Avalanche Fuji -> Arc	0x2931C50745334d6DFf9eC4E3106fE05b49717DF1
Arc -> Avalanche Fuji	0x7dA191bfB85D9F14069228cf618519BFb41f371E

Live Telarana hub receivers:

Chain	FxHubMessageReceiver (V2)
Avalanche Fuji	0x7eAdfD0c08dd6544f763285bBD31be14179d594B
Arc Testnet	0x44B50E93eCC7775aF99bcd04c30e1A00da80F63C

BUFX integrates against Telarana's shipped Stage-6 hub relay surface:

interface IFxHubMessageReceiverRelay {
    function relayToRemoteHub(uint256 amount) external;
    function relayMintFromRemote(bytes calldata attestationPayload, bytes calldata signature)
        external returns (uint256 minted);
}

Authority model: Path A (passive). BUFX contracts never call relayToRemoteHub themselves. A BUFX-controlled keeper EOA is whitelisted on Telarana via setRelayCaller(keeper, true), watches BUFX TelaranaRequestSubmitted events, and executes the relay off the BUFX surface. Keeps BUFX strictly off the Gateway custody path. See docs/TELARANA_INTEGRATION.md.

Hub-aware venue routing is documented in docs/HUB_ROUTING.md.

Modules

• BuFxTelaranaRequestRouter: records Gateway-backed BUFX intent and exposes Telarana GatewayMintContext payloads.
• BuFxVenueRequestRouter: typed request surface for spot, RFQ Pasillo, and capped future perp-liquidity intent.
• BuFxFeeConfig: market-specific BUFX fee/referral quote config.
• BuFxFeeCollector: BUFX venue fee settlement, isolated from Telarana liquidity.
• IFxHubMessageReceiverRelay: BUFX-side interface scaffold for Telarana’s hub relay shim.
• packages/sdk: calldata, typed-data, deployment, fee preview, RFQ, relay, and indexing helpers.

Markets

Initial BUFX markets route through Avalanche Fuji -> Arc USDC:

• FX-USD-JPY
• FX-USD-MXN
• FX-USD-CHF

These are request-layer market IDs. Telarana’s live Morpho market IDs and hub addresses are documented in docs/TELARANA_INTEGRATION.md.

Commands

bun install
bun run test
bun run security:check
bun run live:verify:foundry
bun run deploy:forex-local:testnet
bun run deploy:ready:testnet
bun run deploy:validate:testnet

# Stage 12 operator commands (Path A — passive keeper)
bun run stage12:rewire:dry-run    # plan the rewire onto Telarana V2 hooks
bun run stage12:rewire            # broadcast — requires BUFX_PRIVATE_KEY
bun run stage12:smoke -- --action=bufx-request --from=fuji --amount=1000000
bun run stage12:smoke -- --action=relay-source --from=fuji --amount=1000000
bun run stage12:smoke -- --action=relay-mint --chain=arc \
  --attestation-payload=0x... --signature=0x...

Stage 12 runbook: docs/STAGE12_OPERATOR_RUNBOOK.md.

Build safe no-broadcast request payloads:

bun run deploy:smoke-request:testnet

Dry-run a deployment plan:

bun run deploy:bufx:testnet:dry-run
BUFX_DEPLOY_HUB=arc-testnet bun run deploy:bufx:testnet:dry-run

Broadcast deployment/configuration only after deploy:forex-local:testnet and deploy:ready:testnet pass:

forge build --root contracts
bun run deploy:bufx:testnet
BUFX_DEPLOY_HUB=arc-testnet bun run deploy:bufx:testnet

SDK

The SDK exports helpers for:

• building direct trader and relayer-submitted requests;
• signing EIP-712 spot/RFQ/perp-liquidity intent;
• parsing Telarana Phase B-E perp manifests and building keeper match handoff JSON;
• previewing BUFX venue fees;
• decoding BUFX and Telarana request events;
• indexing request lifecycle logs by requestId;
• encoding Telarana hub relay calldata.

See docs/SDK_USAGE.md and docs/INDEXING.md.

Security Boundary

BUFX v1 is a venue/request layer. It does not implement:

• Circle Gateway burn/mint execution;
• Telarana hub liquidity accounting;
• Morpho credit-market accounting;
• perp margin, PnL, funding, or liquidation logic.

Security notes and the v1 interface freeze are in docs/SECURITY.md and docs/V1_INTERFACE_FREEZE.md.

Docs

• Deployment
• Telarana Integration
• Hub Routing
• SDK Usage
• Indexing
• Security
• V1 Interface Freeze
• Completion Checklist