Integration Guide

The right mental model is simple:

• use compute for state-sensitive reads, search, optimization, or selected external lookups

• use execute for the minimal on-chain action and safety checks

• keep the boundary between them explicit

1. Split your flow into compute and execute

A good BEX integration starts by deciding what belongs in each phase.

Use compute for work that is expensive, dynamic, or builder-specific:

• live reads against mid-block state

• route search

• trade sizing

• quote selection

• external lookups where supported

• any other heavy preprocessing

Use execute for the final on-chain action:

• consume the precomputed result

• verify bounds and invariants

• transfer value

• pay coinbase if your strategy requires it

• succeed or revert atomically

As a rule of thumb: if the work is hard to do on-chain or only makes sense in the current block context, it probably belongs in compute.

2. Call built-in methods from compute

Inside your compute function, call built-in methods through the reserved builder host. The exact host constant and helper shape can vary by SDK, but the conceptual interface is always the same:

outputBytes = builtInCall(selector, inputBytes);

Illustrative helper:

library BexBuiltin {
    // Illustrative only. The reserved host address is builder-defined.
    address constant BEX_HOST = /* reserved builder host */;

    function callBuiltin(string memory method, bytes memory input)
        internal
        view
        returns (bytes memory out)
    {
        bytes32 selector = keccak256(bytes(method));

        (bool ok, bytes memory result) =
            BEX_HOST.staticcall(abi.encode(selector, input));

        require(ok, "builtin call failed");
        return result;
    }
}

Illustrative compute function using three different kinds of built-ins:

• a live state read

• an external market lookup

• an optimization step

contract Strategy {
    struct Precomputed {
        uint256 maxInput;
        uint256 minOutput;
    }

    function compute(address pool, string calldata symbol)
        external
        view
        returns (Precomputed memory pre)
    {
        bytes memory reservesOut = BexBuiltin.callBuiltin(
            "builtin:dex.poolReserves@1",
            abi.encode(pool)
        );
        (uint256 reserve0, uint256 reserve1) =
            abi.decode(reservesOut, (uint256, uint256));

        bytes memory orderbookOut = BexBuiltin.callBuiltin(
            "builtin:cex.binance.orderbook@1",
            abi.encode(symbol)
        );
        (uint256 bestBid, uint256 bestAsk) =
            abi.decode(orderbookOut, (uint256, uint256));

        bytes memory solverOut = BexBuiltin.callBuiltin(
            "builtin:math.solve@1",
            abi.encode(reserve0, reserve1, bestBid, bestAsk)
        );
        (uint256 maxInput, uint256 minOutput) =
            abi.decode(solverOut, (uint256, uint256));

        return Precomputed({
            maxInput: maxInput,
            minOutput: minOutput
        });
    }

    function execute(address pool, Precomputed calldata pre) external {
        require(pre.maxInput > 0, "no opportunity");

        _swap(pool, pre.maxInput, pre.minOutput);
    }

    function _swap(
        address pool,
        uint256 amountIn,
        uint256 minAmountOut
    ) internal {
        // Strategy-specific execution logic.
    }
}

The method names above are illustrative. The exact built-in catalog can expand over time, but the integration pattern stays the same.

3. Return exactly the bytes that execute expects

The compute result is not wrapped again by the builder. It is appended directly to the execute prefix.

That means the bytes returned by compute must already be the exact ABI encoding expected for the final parameter of execute.

Conceptually:

finalExecuteCalldata = executePrefixCalldata || computeReturnBytes

This makes the builder result-agnostic. It does not need to decode or reinterpret the value. It only concatenates bytes.

In practice, this means you should design compute and execute together:

• keep the final argument layout simple

• avoid unnecessary dynamic encoding complexity

• return exactly what the last execute argument expects

• test the wiring early with simulation

4. Keep the safety boundary on-chain

Builder Execution Oracle makes more inputs available during compute, but it does not remove the need for on-chain safety checks.

Your execute function should still enforce:

• slippage bounds

• replay protection where needed

• payment conditions

• max input / min output constraints

• any protocol-specific invariants

This is especially important when a built-in uses external resources. For example, a Binance orderbook built-in may help choose whether to attempt a trade, but the on-chain path should still be safe even if the external view has moved. The execute path should rely on verifiable on-chain constraints, not blind trust in the precomputed value.

A good pattern is:

• let compute decide whether an opportunity exists and how to structure it

• let execute enforce what must be true on-chain for the action to succeed safely

5. Simulate before you submit

Use bex_simulate whenever you change:

• the compute logic

• the execute prefix

• the built-ins used during compute

• the shape of the returned bytes

Simulation is the fastest way to verify that:

• built-in calls resolve as expected

• the compute output is correctly encoded

• the execute calldata is wired correctly

• the final execution path succeeds

• failure reasons are legible before you send a live request

For resource-heavy strategies, simulation is also where you will catch builder-side limits early.

6. Submit and trace through the normal BEX flow

Once simulation looks good, submit through bex_sendBundle just as you would for any other BEX strategy.

After submission:

• use replacementUuid and related bundle semantics if you need to update or cancel

• use eureka_getBundleStats to trace the request lifecycle

• use the normal BEX debugging flow to understand whether the request was rejected, failed simulation, was not profitable, or was simply not selected

There is no separate lifecycle for the oracle layer. It inherits the same submission and tracing model as BEX.

7. Start small, then expand

A strong first integration usually starts with one narrow built-in and one simple execute path.

Good early patterns include:

• reading a live reserve or balance and using it in execution

• computing a best trade size and passing it as the last argument

• compressing a storage-heavy read into a small struct

• using an external market input only as an advisory signal, while keeping all hard safety checks on-chain

Once that works, it is natural to expand into multi-step strategies that combine:

• live state reads

• heavy compute

• and selected external inputs

without changing the underlying BEX model.

Design tips

• Keep compute results compact Return the smallest structure your execute path actually needs.

• Prefer deterministic, bounded built-ins They are easier to reason about and easier for the builder to evaluate reliably.

• Use external inputs carefully Treat them as a strategy input, not as something the chain can independently verify.

• Assume no privacy Do not rely on confidentiality as a security property.

• Design for best-effort evaluation The builder may skip work under load or near deadlines.

• Keep execute easy to validate The more clearly the execute path enforces safety and payment conditions, the easier the whole strategy is to reason about.

Summary

Builder Execution Oracle makes BEX much more expressive by exposing builder-side capabilities through a single built-in method interface.

You still write a normal BEX strategy:

1. compute resolves the information you need,

2. the builder splices the compute result into execute,

3. execute validates and applies the result atomically on-chain.

That simple model is what gives the feature its power. You can use builder-side state, heavy computation, and selected external inputs to make better decisions in the block being built, while keeping the on-chain path minimal, explicit, and safe.