Weiroll Executor Guide

This guide explains how to use Weiroll to compose complex operation sequences in Flux Protocol, enabling managers and liquidators to execute sophisticated multi-step transactions efficiently.

Table of Contents

1. What is Weiroll?

2. Why Flux Uses Weiroll

3. WeirollExecutor Architecture

4. Getting Started

5. Manager Use Cases

6. Liquidator Use Cases

7. JavaScript API

8. Solidity Integration

9. Security Considerations

10. Debugging & Testing

11. Best Practices

---

What is Weiroll?

Weiroll is a scripting language and virtual machine (VM) for composing sequences of smart contract calls into a single atomic transaction. Think of it as a "programmable callback" that lets you encode complex operations off-chain and execute them on-chain in one transaction.

Key Concepts

• Commands: Encoded function calls represented as bytes32 values

• State: Array of variables (inputs/outputs) that commands can reference

• Planner: Off-chain tool (JavaScript library) for building command sequences

• VM: On-chain executor that interprets and executes command sequences

How Weiroll Works

Off-Chain (JavaScript)                    On-Chain (Solidity)
┌─────────────────────┐                  ┌──────────────────┐
│   Weiroll Planner   │                  │   Weiroll VM     │
│                     │                  │                  │
│  1. Add commands    │   encode         │  1. Decode       │
│  2. Build script    ├──────────────────►  2. Execute      │
│  3. Generate state  │   (commands,     │  3. Return state │
│                     │    state)        │                  │
└─────────────────────┘                  └──────────────────┘

Example Weiroll Script:

// Off-chain planning
planner.add(vault.locked_depositBond(25000));
planner.add(vault.locked_borrow(100000));
const {commands, state} = planner.plan();

// On-chain execution
vault.unlock(abi.encode(commands, state));
// → Vault calls executor.fluxUnlockCallback()
// → Executor runs VM to execute commands

---

Why Flux Uses Weiroll

Flux's unified callback architecture creates a unique opportunity for Weiroll:

1. Unified Callback Pattern

Both managers (unlock) and liquidators share the same callback interface:

interface IFluxUnlockCallback {
    function fluxUnlockCallback(bytes calldata data) external;
}

This means one Weiroll executor can handle both manager operations and liquidations.

2. Complex Operation Sequences

Manager workflows often require multiple steps:

• Borrow → Swap → Deposit collateral

• Withdraw → Repay → Rebalance

• Move funds between positions → Adjust leverage

Weiroll lets you compose these atomically without writing custom callback contracts.

3. Capital-Free Liquidations

Liquidators can use locked_borrow() during callbacks to access vault capital:

// Liquidation script
planner.add(vault.locked_withdrawFromWrapper(wrapper, posId, amount));
planner.add(vault.locked_borrow(capital));  // Borrow vault's own capital!
planner.add(dex.swap(tokenA, tokenB, amount));
planner.add(vault.locked_repay(capital));

No upfront capital needed—use the vault's liquidity during liquidation.

4. Flexibility Without Code Changes

Deploy one WeirollExecutor, then compose different operations by changing the script:

• No new contract deployments

• No contract upgrades

• Change strategies on the fly

---

WeirollExecutor Architecture

Contract Structure

contract WeirollExecutor is VM, IExecutor {
    address public immutable manager;           // Owner of this executor
    IFluxVaultFactory public immutable factory; // Verify caller is a vault

    function fluxUnlockCallback(bytes calldata data) external override {
        // 1. Verify caller is a factory-deployed vault
        if (!factory.isVault(msg.sender)) revert NotAVault();

        // 2. Decode weiroll script
        (bytes32[] memory commands, bytes[] memory state) =
            abi.decode(data, (bytes32[], bytes[]));

        // 3. Execute commands via VM
        bytes[] memory finalState = this.execute(commands, state);

        emit WeirollScriptExecuted(msg.sender, commands.length, finalState.length);
    }

    function execute(bytes32[] calldata commands, bytes[] memory state)
        public payable returns (bytes[] memory)
    {
        // SECURITY: Only callable by this contract or manager
        if (msg.sender != address(this) && msg.sender != manager) {
            revert Unauthorized();
        }
        return _execute(commands, state);
    }
}

Execution Flow

┌─────────────────────────────────────────────────────────────────┐
│ 1. Manager/Liquidator calls vault.unlock(weirollScript)        │
└────────────────────────┬────────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────────┐
│ 2. Vault sets lock and calls executor.fluxUnlockCallback()     │
└────────────────────────┬────────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────────┐
│ 3. Executor verifies vault via factory.isVault(msg.sender)     │
└────────────────────────┬────────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────────┐
│ 4. Executor decodes (commands, state) from calldata            │
└────────────────────────┬────────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────────┐
│ 5. Executor calls this.execute(commands, state)                │
│    (external call to convert memory → calldata for VM)         │
└────────────────────────┬────────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────────┐
│ 6. VM executes each command sequentially:                      │
│    - locked_depositBond(25000)                                 │
│    - locked_borrow(100000)                                     │
│    - locked_depositToWrapper(...)                              │
└────────────────────────┬────────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────────┐
│ 7. Vault validates solvency and releases lock                  │
└─────────────────────────────────────────────────────────────────┘

Access Control

The executor has two access modes:

1. Self-call during callback: msg.sender == address(this)

   • When vault calls fluxUnlockCallback(), executor uses this.execute()

   • This converts memory arrays to calldata for the VM

2. Direct manager call: msg.sender == manager

   • Manager can test scripts directly

   • Useful for debugging without involving the vault

---

Getting Started

Step 1: Deploy Your WeirollExecutor

Use the factory's deployment helper:

// Deploy executor for msg.sender
IFluxVaultFactory factory = IFluxVaultFactory(FACTORY_ADDRESS);
address executorAddr = factory.deployWeirollExecutor();

// Executor is automatically registered with the factory

Or deploy manually:

WeirollExecutor executor = new WeirollExecutor(
    msg.sender,           // manager
    address(factory)      // factory for vault verification
);

// Manually register
factory.registerExecutor(msg.sender, address(executor));

Step 2: Install Weiroll JavaScript Library

npm install @ensofinance/weiroll.js ethers@5

Note: Use ethers v5 (weiroll.js is not yet compatible with v6)

Step 3: Create Your First Script

const weiroll = require('@ensofinance/weiroll.js');
const { ethers } = require('ethers');

// Define vault ABI (only functions you need)
const VAULT_ABI = [
  'function locked_depositBond(uint256 amount)',
  'function locked_borrow(uint256 amount)',
];

// Create planner
const planner = new weiroll.Planner();

// Create contract wrapper
const vault = weiroll.Contract.createContract(
  new ethers.Contract(VAULT_ADDRESS, VAULT_ABI)
);

// Add commands
planner.add(vault.locked_depositBond(ethers.utils.parseEther('25000')));
planner.add(vault.locked_borrow(ethers.utils.parseEther('100000')));

// Generate script
const { commands, state } = planner.plan();

// Encode for Solidity
const script = ethers.utils.defaultAbiCoder.encode(
  ['bytes32[]', 'bytes[]'],
  [commands, state]
);

Step 4: Execute the Script

const vaultContract = new ethers.Contract(VAULT_ADDRESS, VAULT_ABI, signer);

// Execute via vault.unlock()
const tx = await vaultContract.unlock(script);
await tx.wait();

console.log('Weiroll script executed!');

---

Manager Use Cases

Use Case 1: Basic Borrow

Goal: Deposit bond and borrow funds

const planner = new weiroll.Planner();

// Create contract wrappers
const vault = weiroll.Contract.createContract(
  new ethers.Contract(VAULT_ADDRESS, VAULT_ABI)
);
const asset = weiroll.Contract.createContract(
  new ethers.Contract(ASSET_ADDRESS, ERC20_ABI)
);

// Amounts
const bondAmount = ethers.utils.parseEther('25000');
const borrowAmount = ethers.utils.parseEther('100000');

// Build script
// Note: Transfer bond to executor before calling unlock
planner.add(asset.approve(VAULT_ADDRESS, bondAmount));
planner.add(vault.locked_depositBond(bondAmount));
planner.add(vault.locked_borrow(borrowAmount));

const { commands, state } = planner.plan();

Pre-execution setup:

// Transfer bond to executor BEFORE calling unlock
asset.transfer(executorAddress, bondAmount);

// Execute script
vault.unlock(abi.encode(commands, state));

What happens:

1. Executor approves vault to spend bond

2. Vault locks the callback

3. Executor deposits bond via locked_depositBond()

4. Executor borrows funds via locked_borrow()

5. Vault validates solvency (bond ≥ minBondRatio * debt)

6. Vault releases lock

7. Borrowed funds are in executor's working capital

---

Use Case 2: Borrow → Swap → Deposit Collateral

Goal: Leverage trading—borrow USDC, swap to WETH, deposit as collateral

const planner = new weiroll.Planner();

// Contract wrappers
const vault = weiroll.Contract.createContract(
  new ethers.Contract(VAULT_ADDRESS, VAULT_ABI)
);
const usdc = weiroll.Contract.createContract(
  new ethers.Contract(USDC_ADDRESS, ERC20_ABI)
);
const weth = weiroll.Contract.createContract(
  new ethers.Contract(WETH_ADDRESS, ERC20_ABI)
);
const uniswapRouter = weiroll.Contract.createContract(
  new ethers.Contract(UNISWAP_ROUTER, UNISWAP_ABI)
);

const bondAmount = ethers.utils.parseUnits('25000', 6); // USDC has 6 decimals
const borrowAmount = ethers.utils.parseUnits('100000', 6);

// Build script
planner.add(usdc.approve(VAULT_ADDRESS, bondAmount));
planner.add(vault.locked_depositBond(bondAmount));
planner.add(vault.locked_borrow(borrowAmount));

// Withdraw borrowed USDC to executor
planner.add(vault.locked_withdrawFromWrapper(
  BASE_WRAPPER,
  WORKING_CAPITAL_POS_ID,
  borrowAmount
));

// Swap USDC → WETH via Uniswap
planner.add(usdc.approve(UNISWAP_ROUTER, borrowAmount));
planner.add(uniswapRouter.swapExactTokensForTokens(
  borrowAmount,
  minWethOut,
  [USDC_ADDRESS, WETH_ADDRESS],
  EXECUTOR_ADDRESS,
  deadline
));

// Deposit WETH as collateral
const wethAmount = weiroll.Library.wrap(WETH_RECEIVED); // Use return value from swap
planner.add(weth.approve(VAULT_ADDRESS, wethAmount));
planner.add(vault.locked_registerWrapper(WETH_WRAPPER));
planner.add(vault.locked_depositToWrapper(
  WETH_WRAPPER,
  ethers.constants.HashZero, // positionId
  wethAmount
));

const { commands, state } = planner.plan();

What happens:

1. Deposit bond and borrow USDC

2. Withdraw USDC from vault to executor

3. Swap USDC → WETH on Uniswap

4. Deposit WETH back into vault as collateral

5. Vault validates: collateral value ≥ debt / (1 - minBondRatio)

6. Position is now leveraged long WETH

---

Use Case 3: Full Repayment

Goal: Move bond funds to cover interest, repay all debt, withdraw remaining bond

const planner = new weiroll.Planner();

const vault = weiroll.Contract.createContract(
  new ethers.Contract(VAULT_ADDRESS, VAULT_ABI)
);

// Constants for position IDs
const BOND_POS_ID = ethers.utils.hexZeroPad('0x01', 32);
const WORKING_CAPITAL_POS_ID = ethers.constants.HashZero;

// Move 5k from bond to working capital (to cover accrued interest)
const moveAmount = ethers.utils.parseEther('5000');
planner.add(vault.locked_moveFunds(
  BOND_POS_ID,
  WORKING_CAPITAL_POS_ID,
  moveAmount
));

// Repay all debt (0 = full repayment)
planner.add(vault.locked_repay(0));

// Withdraw remaining bond (25k - 5k = 20k)
const withdrawAmount = ethers.utils.parseEther('20000');
planner.add(vault.locked_withdrawBond(withdrawAmount));

const { commands, state } = planner.plan();

What happens:

1. Move 5k from bond to working capital

2. Vault uses working capital to repay debt

3. Debt becomes 0

4. Withdraw remaining 20k bond to executor

5. Manager can withdraw from executor to their EOA

---

Use Case 4: Rebalancing Collateral

Goal: Withdraw some WETH, swap to USDC, deposit as working capital

const planner = new weiroll.Planner();

const vault = weiroll.Contract.createContract(
  new ethers.Contract(VAULT_ADDRESS, VAULT_ABI)
);
const weth = weiroll.Contract.createContract(
  new ethers.Contract(WETH_ADDRESS, ERC20_ABI)
);
const usdc = weiroll.Contract.createContract(
  new ethers.Contract(USDC_ADDRESS, ERC20_ABI)
);
const uniswapRouter = weiroll.Contract.createContract(
  new ethers.Contract(UNISWAP_ROUTER, UNISWAP_ABI)
);

const wethToWithdraw = ethers.utils.parseEther('10'); // 10 WETH

// Withdraw WETH from wrapper
planner.add(vault.locked_withdrawFromWrapper(
  WETH_WRAPPER,
  POSITION_ID,
  wethToWithdraw
));

// Swap WETH → USDC
planner.add(weth.approve(UNISWAP_ROUTER, wethToWithdraw));
planner.add(uniswapRouter.swapExactTokensForTokens(
  wethToWithdraw,
  minUsdcOut,
  [WETH_ADDRESS, USDC_ADDRESS],
  EXECUTOR_ADDRESS,
  deadline
));

// Deposit USDC to working capital
const usdcReceived = weiroll.Library.wrap(USDC_AMOUNT);
planner.add(usdc.approve(VAULT_ADDRESS, usdcReceived));
planner.add(vault.locked_depositToWrapper(
  BASE_WRAPPER,
  WORKING_CAPITAL_POS_ID,
  usdcReceived
));

const { commands, state } = planner.plan();

What happens:

1. Withdraw 10 WETH from collateral

2. Swap to USDC

3. Deposit USDC as working capital (reduces debt)

4. Vault validates solvency after rebalancing

---

Liquidator Use Cases

Use Case 1: Capital-Free Liquidation

Goal: Liquidate a manager without providing upfront capital

Strategy: Use seized working capital and bond to pay minPayment

// Manual callback (not using Weiroll for simplicity)
contract CapitalFreeLiquidator is IFluxUnlockCallback {
    address public vault;
    address public immutable liquidatorOwner;
    address public immutable baseAssetWrapper;
    IERC20 public asset;

    constructor(address _owner, address _vault, address _asset, address _baseWrapper) {
        liquidatorOwner = _owner;
        vault = _vault;
        asset = IERC20(_asset);
        baseAssetWrapper = _baseWrapper;
        asset.approve(_vault, type(uint256).max);
    }

    function fluxUnlockCallback(bytes calldata data) external override {
        require(msg.sender == vault, "Only vault");

        (uint256 minPayment,,) = abi.decode(data, (uint256, uint256, bytes));

        // 1. Withdraw seized working capital
        uint256 workingCapital = FluxVault(vault).getWorkingCapital(liquidatorOwner);
        if (workingCapital > 0) {
            FluxVault(vault).locked_withdrawFromWrapper(
                IAsset(baseAssetWrapper),
                WORKING_CAPITAL_POS_ID,
                workingCapital
            );
        }

        // 2. Withdraw seized bond if needed
        uint256 balance = asset.balanceOf(address(this));
        if (balance < minPayment) {
            uint256 needed = minPayment - balance;
            FluxVault(vault).locked_withdrawBond(needed);
        }

        // 3. Deposit minPayment to working capital
        FluxVault(vault).locked_depositToWrapper(
            IAsset(baseAssetWrapper),
            bytes32(0),
            minPayment
        );
    }
}

Using Weiroll for the same pattern:

const planner = new weiroll.Planner();

const vault = weiroll.Contract.createContract(
  new ethers.Contract(VAULT_ADDRESS, VAULT_ABI)
);
const asset = weiroll.Contract.createContract(
  new ethers.Contract(ASSET_ADDRESS, ERC20_ABI)
);

// Note: minPayment is provided in callback data
const minPayment = weiroll.State.fromSlot(0); // First state variable from callback

// 1. Withdraw seized working capital
planner.add(vault.locked_withdrawFromWrapper(
  BASE_WRAPPER,
  WORKING_CAPITAL_POS_ID,
  workingCapitalAmount // Query this beforehand
));

// 2. Withdraw seized bond (if needed)
planner.add(vault.locked_withdrawBond(bondNeeded));

// 3. Approve and deposit minPayment
planner.add(asset.approve(VAULT_ADDRESS, minPayment));
planner.add(vault.locked_depositToWrapper(
  BASE_WRAPPER,
  WORKING_CAPITAL_POS_ID,
  minPayment
));

const { commands, state } = planner.plan();

Triggering liquidation:

// Liquidate with Weiroll script
vault.liquidate(managerToLiquidate, new IAsset[](0), weirollScript);

What happens:

1. Vault transfers manager's positions to liquidator

2. Vault calls liquidator.fluxUnlockCallback(encodedMinPayment)

3. Liquidator withdraws seized assets

4. Liquidator deposits minPayment to vault

5. Vault validates payment and releases lock

6. Liquidator keeps remaining assets as profit

---

Use Case 2: Borrow-Based Liquidation

Goal: Use vault's own capital to liquidate (leveraged liquidation)

const planner = new weiroll.Planner();

const vault = weiroll.Contract.createContract(
  new ethers.Contract(VAULT_ADDRESS, VAULT_ABI)
);
const asset = weiroll.Contract.createContract(
  new ethers.Contract(ASSET_ADDRESS, ERC20_ABI)
);

const borrowAmount = ethers.utils.parseEther('50000'); // Borrow vault capital
const minPayment = weiroll.State.fromSlot(0);

// 1. Deposit small bond as liquidator
const liquidatorBond = ethers.utils.parseEther('5000');
planner.add(asset.approve(VAULT_ADDRESS, liquidatorBond));
planner.add(vault.locked_depositBond(liquidatorBond));

// 2. Borrow from vault
planner.add(vault.locked_borrow(borrowAmount));

// 3. Withdraw seized collateral
planner.add(vault.locked_withdrawFromWrapper(
  WETH_WRAPPER,
  seizedPositionId,
  seizedAmount
));

// 4. Sell seized collateral on DEX
planner.add(weth.approve(UNISWAP_ROUTER, seizedAmount));
planner.add(uniswapRouter.swapExactTokensForTokens(
  seizedAmount,
  minUsdcOut,
  [WETH_ADDRESS, USDC_ADDRESS],
  EXECUTOR_ADDRESS,
  deadline
));

// 5. Repay borrowed amount
planner.add(asset.approve(VAULT_ADDRESS, borrowAmount));
planner.add(vault.locked_repay(borrowAmount));

// 6. Deposit minPayment
planner.add(vault.locked_depositToWrapper(
  BASE_WRAPPER,
  WORKING_CAPITAL_POS_ID,
  minPayment
));

// 7. Withdraw liquidator bond (get it back)
planner.add(vault.locked_withdrawBond(liquidatorBond));

const { commands, state } = planner.plan();

What happens:

1. Liquidator deposits small bond (e.g., 5k)

2. Liquidator borrows 50k from vault (uses vault's LP capital!)

3. Liquidator withdraws and sells seized collateral

4. Repays 50k borrowed + deposits minPayment

5. Withdraws bond back

6. Profit = seized value - minPayment (no capital lockup)

---

Use Case 3: Swap-Optimized Liquidation

Goal: Route through multiple DEXs for best price

const planner = new weiroll.Planner();

const vault = weiroll.Contract.createContract(
  new ethers.Contract(VAULT_ADDRESS, VAULT_ABI)
);
const weth = weiroll.Contract.createContract(
  new ethers.Contract(WETH_ADDRESS, ERC20_ABI)
);
const usdc = weiroll.Contract.createContract(
  new ethers.Contract(USDC_ADDRESS, ERC20_ABI)
);
const aggregator = weiroll.Contract.createContract(
  new ethers.Contract(AGGREGATOR_ADDRESS, AGGREGATOR_ABI)
);

// 1. Withdraw seized WETH
planner.add(vault.locked_withdrawFromWrapper(
  WETH_WRAPPER,
  positionId,
  wethAmount
));

// 2. Use 1inch/Paraswap aggregator for best price
planner.add(weth.approve(AGGREGATOR_ADDRESS, wethAmount));
planner.add(aggregator.swap(
  WETH_ADDRESS,
  USDC_ADDRESS,
  wethAmount,
  minUsdcOut,
  routingData // Pre-calculated optimal route
));

// 3. Deposit proceeds to cover minPayment
const usdcReceived = weiroll.Library.wrap(SWAP_OUTPUT);
planner.add(usdc.approve(VAULT_ADDRESS, usdcReceived));
planner.add(vault.locked_depositToWrapper(
  BASE_WRAPPER,
  WORKING_CAPITAL_POS_ID,
  minPayment
));

const { commands, state } = planner.plan();

Advantages:

• Maximize profit by getting best swap prices

• Route through Uniswap, Sushiswap, Curve simultaneously

• Reduce slippage on large liquidations

---

JavaScript API

Core Objects

1. Planner

The Planner builds a sequence of commands:

const weiroll = require('@ensofinance/weiroll.js');
const planner = new weiroll.Planner();

Methods:

• add(command): Add a command to the sequence

• plan(): Generate {commands, state} for execution

• replace(oldCommand, newCommand): Replace a command

• precompile(address): Mark an address as precompiled

2. Contract

Wraps an ethers.js contract for Weiroll:

const vault = weiroll.Contract.createContract(
  new ethers.Contract(VAULT_ADDRESS, VAULT_ABI, provider)
);

// Now you can add vault function calls to the planner
planner.add(vault.locked_borrow(amount));

Methods:

• createContract(ethersContract): Wrap ethers contract

• createLibrary(ethersContract): Wrap as library (for return values)

3. State Variables

Reference dynamic values (return values, inputs):

// Use return value from previous command
const swapOutput = vault.locked_borrow(amount); // Returns amount borrowed
planner.add(asset.approve(spender, swapOutput)); // Use returned value

// Access callback data
const minPayment = weiroll.State.fromSlot(0); // First variable in state array

Complete JavaScript Example

const weiroll = require('@ensofinance/weiroll.js');
const { ethers } = require('ethers');

// ABIs
const VAULT_ABI = [
  'function locked_depositBond(uint256 amount)',
  'function locked_borrow(uint256 amount)',
  'function locked_depositToWrapper(address wrapper, bytes32 positionId, uint256 amount)',
];

const ERC20_ABI = [
  'function approve(address spender, uint256 amount) returns (bool)',
];

const UNISWAP_ABI = [
  'function swapExactTokensForTokens(uint256 amountIn, uint256 amountOutMin, address[] path, address to, uint256 deadline) returns (uint256[] amounts)',
];

async function createLeverageScript() {
  const planner = new weiroll.Planner();

  // Wrap contracts
  const vault = weiroll.Contract.createContract(
    new ethers.Contract(VAULT_ADDRESS, VAULT_ABI)
  );
  const usdc = weiroll.Contract.createContract(
    new ethers.Contract(USDC_ADDRESS, ERC20_ABI)
  );
  const weth = weiroll.Contract.createContract(
    new ethers.Contract(WETH_ADDRESS, ERC20_ABI)
  );
  const uniswap = weiroll.Contract.createContract(
    new ethers.Contract(UNISWAP_ROUTER, UNISWAP_ABI)
  );

  // Amounts
  const bondAmount = ethers.utils.parseUnits('25000', 6);
  const borrowAmount = ethers.utils.parseUnits('100000', 6);
  const minWethOut = ethers.utils.parseEther('30'); // Expect ~30 WETH
  const deadline = Math.floor(Date.now() / 1000) + 3600; // 1 hour

  // Build script
  planner.add(usdc.approve(VAULT_ADDRESS, bondAmount));
  planner.add(vault.locked_depositBond(bondAmount));
  planner.add(vault.locked_borrow(borrowAmount));

  // Withdraw to swap
  planner.add(vault.locked_withdrawFromWrapper(
    BASE_WRAPPER,
    ethers.constants.HashZero,
    borrowAmount
  ));

  // Swap USDC → WETH
  planner.add(usdc.approve(UNISWAP_ROUTER, borrowAmount));
  const swapReturn = planner.add(uniswap.swapExactTokensForTokens(
    borrowAmount,
    minWethOut,
    [USDC_ADDRESS, WETH_ADDRESS],
    EXECUTOR_ADDRESS,
    deadline
  ));

  // Deposit WETH as collateral
  // swapReturn is uint256[] amounts, extract amounts[1]
  const wethReceived = weiroll.Library.wrap(swapReturn.outputs[1]);
  planner.add(weth.approve(VAULT_ADDRESS, wethReceived));
  planner.add(vault.locked_depositToWrapper(
    WETH_WRAPPER,
    ethers.constants.HashZero,
    wethReceived
  ));

  // Generate commands and state
  const { commands, state } = planner.plan();

  return ethers.utils.defaultAbiCoder.encode(
    ['bytes32[]', 'bytes[]'],
    [commands, state]
  );
}

// Usage
async function main() {
  const script = await createLeverageScript();

  const provider = new ethers.providers.JsonRpcProvider(RPC_URL);
  const signer = new ethers.Wallet(PRIVATE_KEY, provider);

  const vault = new ethers.Contract(VAULT_ADDRESS, VAULT_ABI, signer);
  const tx = await vault.unlock(script);
  await tx.wait();

  console.log('Leverage position created!');
}

---

Solidity Integration

Deploying WeirollExecutor

import {WeirollExecutor} from "src/weiroll/WeirollExecutor.sol";
import {IFluxVaultFactory} from "src/interfaces/IFluxVaultFactory.sol";

contract MyManager {
    WeirollExecutor public executor;
    IFluxVaultFactory public factory;

    constructor(address _factory) {
        factory = IFluxVaultFactory(_factory);

        // Deploy executor
        executor = new WeirollExecutor(address(this), _factory);

        // Register with factory
        factory.registerExecutor(address(this), address(executor));
    }

    function executeScript(address vault, bytes memory weirollScript) external {
        IFluxVault(vault).unlock(weirollScript);
    }
}

Using Pre-Generated Scripts

If you generate scripts off-chain, you can hardcode them:

contract ManagerWithHardcodedScripts {
    function borrowStandardAmount(address vault) external {
        // Commands generated off-chain
        bytes32[] memory commands = new bytes32[](3);
        commands[0] = 0x095ea7b3010001ffffffffff0165878a594ca255338adfa4d48449f69242eb8f;
        commands[1] = 0x0d9633e80101ffffffffffffa15a1d3cebdc9246d5a6f421e7c1e2708e66e200;
        commands[2] = 0x76b9de090102ffffffffffffa15a1d3cebdc9246d5a6f421e7c1e2708e66e200;

        // State with runtime values
        bytes[] memory state = new bytes[](3);
        state[0] = abi.encode(vault);
        state[1] = abi.encode(25_000e18); // Bond amount
        state[2] = abi.encode(100_000e18); // Borrow amount

        bytes memory script = abi.encode(commands, state);
        IFluxVault(vault).unlock(script);
    }
}

Testing Scripts in Foundry

import {Test} from "forge-std/Test.sol";
import {WeirollExecutor} from "src/weiroll/WeirollExecutor.sol";

contract WeirollTest is Test {
    WeirollExecutor executor;
    FluxVault vault;

    function setUp() public {
        // Deploy vault and executor
        // ...

        executor = new WeirollExecutor(address(this), address(factory));
    }

    function testBorrowScript() public {
        // Build script (hardcoded from JavaScript output)
        bytes32[] memory commands = new bytes32[](2);
        commands[0] = 0x...; // locked_depositBond
        commands[1] = 0x...; // locked_borrow

        bytes[] memory state = new bytes[](2);
        state[0] = abi.encode(25_000e18);
        state[1] = abi.encode(100_000e18);

        bytes memory script = abi.encode(commands, state);

        // Execute
        vault.unlock(script);

        // Verify
        (uint256 debt, uint256 bond,) = vault.getManagerPosition(address(this));
        assertEq(debt, 100_000e18);
        assertEq(bond, 25_000e18);
    }
}

---

Security Considerations

1. Vault Verification

WeirollExecutor MUST verify the caller is a legitimate vault:

function fluxUnlockCallback(bytes calldata data) external override {
    // CRITICAL: Prevent malicious contracts from calling
    if (!factory.isVault(msg.sender)) revert FluxErrors.NotAVault();

    // ... execute script
}

Why: Without this check, an attacker could deploy a fake vault that calls your executor with malicious scripts.

2. Executor Access Control

Only the manager or executor itself can call execute():

function execute(bytes32[] calldata commands, bytes[] memory state)
    public payable returns (bytes[] memory)
{
    if (msg.sender != address(this) && msg.sender != manager) {
        revert FluxErrors.Unauthorized();
    }
    return _execute(commands, state);
}

Why: Prevents unauthorized parties from executing arbitrary commands.

3. Script Validation

Always validate scripts before execution:

// Off-chain validation BEFORE sending transaction
function validateScript(commands, state) {
  // Check command count
  if (commands.length === 0 || commands.length > 50) {
    throw new Error('Invalid command count');
  }

  // Check state size
  if (state.length > 100) {
    throw new Error('State too large');
  }

  // Decode and verify each command targets expected contracts
  for (const cmd of commands) {
    const target = extractTarget(cmd);
    if (!ALLOWED_CONTRACTS.includes(target)) {
      throw new Error(`Unexpected target: ${target}`);
    }
  }
}

4. Slippage Protection

Always include slippage protection in swap commands:

// BAD: No minimum output
planner.add(uniswap.swapExactTokensForTokens(
  amountIn,
  0, // ❌ Will accept any output
  path,
  recipient,
  deadline
));

// GOOD: Minimum output from price oracle
const expectedOut = await getExpectedOutput(amountIn, path);
const minOut = expectedOut.mul(95).div(100); // 5% slippage tolerance

planner.add(uniswap.swapExactTokensForTokens(
  amountIn,
  minOut, // ✅ Revert if slippage > 5%
  path,
  recipient,
  deadline
));

5. Gas Limits

Complex scripts can exceed block gas limits:

// Monitor gas usage
const gasEstimate = await vault.estimateGas.unlock(script);
if (gasEstimate > 8_000_000) { // Block gas limit on some chains
  console.warn('Script may exceed gas limit, consider splitting');
}

Best practice: Keep scripts under 20 commands for safety.

6. Reentrancy Protection

The vault's lock pattern prevents reentrancy:

// FluxVault.sol
function unlock(bytes calldata data) external nonReentrant {
    _lock = msg.sender;  // Set lock
    IFluxUnlockCallback(msg.sender).fluxUnlockCallback(data);
    _validateSolvency(msg.sender);
    _lock = address(0);  // Release lock
}

What this means:

• During callback, vault is "locked" to msg.sender

• No other operations can execute on that manager

• Script cannot call unlock() again (nested callbacks prevented)

Exception: Liquidation can trigger nested callbacks (e.g., recursive liquidation). This is safe because positions are transferred first.

7. Token Approval Management

Be careful with infinite approvals:

// Option 1: Approve exact amount (safer, more gas)
planner.add(usdc.approve(VAULT_ADDRESS, borrowAmount));

// Option 2: Approve max once (less safe, saves gas on subsequent calls)
planner.add(usdc.approve(VAULT_ADDRESS, ethers.constants.MaxUint256));

Recommendation: Use exact approvals in scripts, set up infinite approvals separately if needed.

---

Debugging & Testing

1. Generating Scripts

Create a script generation tool:

// scripts/weiroll/encodeScript.js
const weiroll = require('@ensofinance/weiroll.js');

function createBorrowScript() {
  const planner = new weiroll.Planner();

  // ... build script

  const { commands, state } = planner.plan();

  // Output for Solidity tests
  console.log('bytes32[] memory commands = new bytes32[](' + commands.length + ');');
  commands.forEach((cmd, i) => {
    console.log(`commands[${i}] = ${cmd};`);
  });

  console.log('\nbytes[] memory state = new bytes[](' + state.length + ');');
  state.forEach((s, i) => {
    console.log(`state[${i}] = hex"${s.slice(2)}";`);
  });
}

createBorrowScript();

Run:

node scripts/weiroll/encodeScript.js > test/fixtures/borrowScript.txt

2. Testing in Foundry

import {console2} from "forge-std/console2.sol";

function testWeirollScript() public {
    // Log each command
    console2.log("Executing Weiroll script with", commands.length, "commands");

    // Execute
    vm.prank(bob);
    vault.unlock(abi.encode(commands, state));

    // Verify each step
    (uint256 debt, uint256 bond,) = vault.getManagerPosition(bob);
    console2.log("Debt:", debt / 1e18);
    console2.log("Bond:", bond / 1e18);

    assertEq(debt, expectedDebt, "Debt mismatch");
}

3. Decoding Failed Scripts

When a script fails, decode the revert reason:

try {
  const tx = await vault.unlock(script);
  await tx.wait();
} catch (error) {
  console.error('Script failed:', error.message);

  // Decode revert data
  if (error.data) {
    const decoded = vault.interface.parseError(error.data);
    console.error('Revert reason:', decoded);
  }

  // Try simulating each command individually
  for (let i = 0; i < commands.length; i++) {
    console.log(`Testing command ${i}...`);
    const singleCommandScript = createScriptWithOneCommand(commands[i], state);
    try {
      await vault.callStatic.unlock(singleCommandScript);
      console.log(`  ✅ Command ${i} passed`);
    } catch (e) {
      console.log(`  ❌ Command ${i} failed:`, e.message);
    }
  }
}

4. Gas Profiling

function testScriptGasUsage() public {
    uint256 gasBefore = gasleft();
    vault.unlock(script);
    uint256 gasUsed = gasBefore - gasleft();

    console2.log("Gas used:", gasUsed);

    // Compare to manual callback
    uint256 gasBeforeManual = gasleft();
    vault.unlock(manualCallbackData);
    uint256 gasUsedManual = gasBeforeManual - gasleft();

    console2.log("Manual callback gas:", gasUsedManual);
    console2.log("Weiroll overhead:", gasUsed - gasUsedManual);
}

Expected overhead: ~5-10k gas per command.

5. Event Monitoring

const receipt = await tx.wait();

// Find WeirollScriptExecuted event
const event = receipt.events.find(e => e.event === 'WeirollScriptExecuted');
console.log('Commands executed:', event.args.commandCount);
console.log('Final state length:', event.args.stateLength);

// Also check vault events
const borrowEvent = receipt.events.find(e => e.event === 'Borrowed');
if (borrowEvent) {
  console.log('Borrowed:', ethers.utils.formatEther(borrowEvent.args.amount));
}

---

Best Practices

1. Keep Scripts Focused

Good: One script per operation type

// borrowScript.js - Just borrow
// repayScript.js - Just repay
// leverageScript.js - Borrow + swap + deposit

Bad: One giant script for everything

// megaScript.js - Tries to handle all cases with conditionals

2. Separate State from Commands

Commands should be static (reusable), state should be dynamic:

// Generate commands once
const BORROW_COMMANDS = [
  '0x095ea7b3010001ffffffffff0165878a594ca255338adfa4d48449f69242eb8f',
  '0x0d9633e80101ffffffffffffa15a1d3cebdc9246d5a6f421e7c1e2708e66e200',
  '0x76b9de090102ffffffffffffa15a1d3cebdc9246d5a6f421e7c1e2708e66e200',
];

// Build state at runtime
function buildBorrowScript(vaultAddr, bondAmt, borrowAmt) {
  const state = [
    ethers.utils.defaultAbiCoder.encode(['address'], [vaultAddr]),
    ethers.utils.defaultAbiCoder.encode(['uint256'], [bondAmt]),
    ethers.utils.defaultAbiCoder.encode(['uint256'], [borrowAmt]),
  ];
  return ethers.utils.defaultAbiCoder.encode(
    ['bytes32[]', 'bytes[]'],
    [BORROW_COMMANDS, state]
  );
}

3. Version Your Scripts

const SCRIPT_VERSION = '1.0.0';

const SCRIPTS = {
  'borrow-v1': {
    version: '1.0.0',
    commands: [...],
    description: 'Deposit bond and borrow',
  },
  'leverage-v1': {
    version: '1.0.0',
    commands: [...],
    description: 'Borrow, swap, deposit collateral',
  },
};

function getScript(name) {
  if (!SCRIPTS[name]) throw new Error(`Script ${name} not found`);
  return SCRIPTS[name];
}

4. Document Script Behavior

/**
 * Leverage Script v1.0
 *
 * Creates a leveraged long position by:
 * 1. Depositing bond collateral
 * 2. Borrowing base asset (e.g., USDC)
 * 3. Swapping to target asset (e.g., WETH)
 * 4. Depositing target asset as collateral
 *
 * Requirements:
 * - Executor must have `bondAmount` of base asset
 * - Uniswap pool must have sufficient liquidity
 * - Slippage must be within tolerance
 *
 * State Variables:
 * [0] address vault
 * [1] uint256 bondAmount
 * [2] uint256 borrowAmount
 * [3] uint256 minWethOut (slippage protection)
 * [4] uint256 deadline
 */
const leverageScriptV1 = { ... };

5. Handle Errors Gracefully

async function executeScript(script) {
  try {
    const tx = await vault.unlock(script);
    const receipt = await tx.wait();
    return { success: true, receipt };
  } catch (error) {
    // Parse specific errors
    if (error.message.includes('InsufficientCollateral')) {
      console.error('Not enough collateral for operation');
      return { success: false, reason: 'insufficient_collateral' };
    } else if (error.message.includes('ExcessiveSlippage')) {
      console.error('Swap slippage too high');
      return { success: false, reason: 'slippage_exceeded' };
    } else {
      console.error('Unknown error:', error);
      return { success: false, reason: 'unknown', error };
    }
  }
}

6. Use Constants for Position IDs

// Constants from FluxConstants.sol
const WORKING_CAPITAL_POS_ID = ethers.constants.HashZero; // bytes32(0)
const BOND_POS_ID = ethers.utils.hexZeroPad('0x01', 32);  // bytes32(1)

// Use in scripts
planner.add(vault.locked_moveFunds(
  BOND_POS_ID,
  WORKING_CAPITAL_POS_ID,
  amount
));

7. Simulate Before Executing

// Tenderly simulation
async function simulateScript(script) {
  const simulation = await tenderly.simulate({
    from: managerAddress,
    to: vaultAddress,
    data: vault.interface.encodeFunctionData('unlock', [script]),
    gas: 10_000_000,
  });

  if (!simulation.success) {
    console.error('Simulation failed:', simulation.error);
    return false;
  }

  console.log('Gas estimate:', simulation.gasUsed);
  console.log('State changes:', simulation.stateChanges);
  return true;
}

// Only execute if simulation passes
if (await simulateScript(script)) {
  await executeScript(script);
}

8. Monitor Execution

const tx = await vault.unlock(script);
console.log('Transaction sent:', tx.hash);

// Wait with timeout
const receipt = await Promise.race([
  tx.wait(),
  new Promise((_, reject) =>
    setTimeout(() => reject(new Error('Timeout')), 60000)
  ),
]);

console.log('Transaction confirmed in block:', receipt.blockNumber);
console.log('Gas used:', receipt.gasUsed.toString());

// Verify expected state changes
const [debt, bond] = await vault.getManagerPosition(manager);
console.log('New debt:', ethers.utils.formatEther(debt));
console.log('New bond:', ethers.utils.formatEther(bond));