### Install weiroll.js

Source: https://github.com/weiroll/weiroll.js/blob/main/README.md

Install the weiroll.js library using npm.

```bash
npm install --save @weiroll/weiroll.js
```

--------------------------------

### Weiroll CommandFlags Enum and Usage

Source: https://context7.com/weiroll/weiroll.js/llms.txt

CommandFlags control on-chain command execution. They are usually set automatically but can be passed manually to the `Contract` constructor. Example shows manual construction of a static-call contract.

```typescript
import { CommandFlags } from '@weiroll/weiroll.js';

// Available flags:
CommandFlags.DELEGATECALL   // 0x00 — used by createLibrary
CommandFlags.CALL           // 0x01 — used by createContract
CommandFlags.STATICCALL     // 0x02 — used by createContract(c, CommandFlags.STATICCALL) or .staticcall()
CommandFlags.CALL_WITH_VALUE // 0x03 — set automatically by .withValue()
CommandFlags.TUPLE_RETURN   // 0x80 — set automatically by .rawValue()
// (EXTENDED_COMMAND 0x40 is set internally for functions with 7+ arguments)

// Example: manually construct a static-call contract
import { Contract } from '@weiroll/weiroll.js';
import { ethers } from 'ethers';
const oracle = Contract.createContract(
  new ethers.Contract('0xAbCd...', ['function getPrice(address) returns (uint256)']),
  CommandFlags.STATICCALL
);
```

--------------------------------

### new Planner()

Source: https://context7.com/weiroll/weiroll.js/llms.txt

Instantiates a new weiroll planner. The planner accumulates commands via add(), addSubplan(), and replaceState(), then compiles them into a { commands, state } pair via plan().

```APIDOC
## new Planner()

### Description
Instantiates a new weiroll planner. The planner accumulates commands via `add()`, `addSubplan()`, and `replaceState()`, then compiles them into a `{ commands, state }` pair via `plan()`.

A planner also exposes a special `planner.state` value that can be passed to subplan functions as a placeholder for the current execution state.

### Usage
```typescript
import { Planner } from '@weiroll/weiroll.js';

const planner = new Planner();

// planner.state is a special Value representing the live state array at runtime
console.log(planner.state); // StateValue { param: ParamType('bytes[]') }
console.log(planner.commands); // [] — empty until add() is called
```
```

--------------------------------

### Instantiate a Planner

Source: https://github.com/weiroll/weiroll.js/blob/main/README.md

Create a new instance of the weiroll Planner.

```javascript
const planner = new weiroll.Planner();
```

--------------------------------

### Instantiate and Execute a Weiroll Subplan

Source: https://github.com/weiroll/weiroll.js/blob/main/README.md

Use this pattern to create and execute a nested Weiroll VM instance. The subplanner's operations are passed to Weiroll.execute and then added to the outer planner using addSubplan. Ensure the subplan function correctly specifies the state argument using Planner.state.

```javascript
const subplanner = new Planner();
const sum = subplanner.add(Math.add(1, 2));

const planner = new Planner();
planner.addSubplan(Weiroll.execute(subplanner, subplanner.state));
planner.add(Events.logUint(sum));

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

--------------------------------

### planner.plan()

Source: https://context7.com/weiroll/weiroll.js/llms.txt

Compiles all accumulated commands into a `{ commands: string[], state: string[] }` result, ready for submission to a weiroll executor contract. It optimizes slot recycling for literals and return values.

```APIDOC
## planner.plan()

### Description
Compiles all accumulated commands into a `{ commands: string[], state: string[] }` result ready to submit to a weiroll executor contract. It runs a pre-planning pass to compute visibility (last-use) of all literals and return values for slot recycling, then encodes each command as a 32-byte word containing the function selector, call flags, up to 6 argument slot indices (or an extended command word for 7+ args), the return slot index, and the contract address.

### Usage
```typescript
import { ethers } from 'ethers';
import { Contract, Planner } from '@weiroll/weiroll.js';
import * as stringsABI from './abis/Strings.json';

const STRINGS_ADDRESS = '0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee';
const Strings = Contract.createLibrary(
  new ethers.Contract(STRINGS_ADDRESS, stringsABI.abi)
);

const planner = new Planner();
const concatenated = planner.add(Strings.strcat('Hello, ', 'world!'));
planner.add(Strings.strlen(concatenated)); // chain dynamic return value

const { commands, state } = planner.plan();
// commands[0]: encodes strcat call, stores result in state slot
// commands[1]: encodes strlen call, reading from the return slot of strcat
console.log(commands);
// [
//   '0xd824ccf3008081ffffffff81eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee',
//   '0x367bbd780081ffffffffffffeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee'
// ]
console.log(state.length); // 2 (two string literals; return slot reused)
```
```

--------------------------------

### Instantiate a new Weiroll Planner

Source: https://context7.com/weiroll/weiroll.js/llms.txt

Create a new `Planner` instance to accumulate commands and manage state for weiroll execution plans. The planner's `state` property is a special value usable within subplans.

```typescript
import { Planner } from '@weiroll/weiroll.js';

const planner = new Planner();

// planner.state is a special Value representing the live state array at runtime
console.log(planner.state); // StateValue { param: ParamType('bytes[]') }
console.log(planner.commands); // [] — empty until add() is called
```

--------------------------------

### planner.addSubplan(functionCall)

Source: https://context7.com/weiroll/weiroll.js/llms.txt

Adds a nested weiroll execution context (subplan) to the plan. The function call passed must accept exactly one `Planner` argument and one `planner.state` argument. If the subplan function returns `bytes[]`, the parent planner's state is replaced with the returned state, allowing return values from inside the subplan to be referenced in the outer scope. If the function returns nothing, the subplan is read-only and its internal return values are not accessible outside.

```APIDOC
## planner.addSubplan(functionCall)

### Description
Adds a nested weiroll execution context (subplan) to the plan. The function call passed must accept exactly one `Planner` argument and one `planner.state` argument. If the subplan function returns `bytes[]`, the parent planner's state is replaced with the returned state, allowing return values from inside the subplan to be referenced in the outer scope. If the function returns nothing, the subplan is read-only and its internal return values are not accessible outside.

### Usage Example
```typescript
import { ethers } from 'ethers';
import { Contract, Planner } from '@weiroll/weiroll.js';
import * as mathABI from './abis/Math.json';

const MATH_ADDRESS    = '0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee';
const WEIROLL_ADDRESS = '0xCcCCccccCCCCcCCCCCCcCcCccCcCCCcCcccccccC';

const Math = Contract.createLibrary(new ethers.Contract(MATH_ADDRESS, mathABI.abi));
const Weiroll = Contract.createLibrary(
  new ethers.Contract(WEIROLL_ADDRESS, [
    'function execute(bytes32[] commands, bytes[] state) returns (bytes[])',
  ])
);

// Build the subplan
const subplanner = new Planner();
const innerSum = subplanner.add(Math.add(10, 20)); // computes 30

// Build the outer plan — subplan returns updated state so innerSum is visible
const planner = new Planner();
planner.addSubplan(Weiroll.execute(subplanner, subplanner.state));
planner.add(Math.add(innerSum, 5)); // uses return value from inner scope → 35

const { commands, state } = planner.plan();
console.log(commands.length); // 2 (subplan invocation + outer add)
```
```

--------------------------------

### planner.replaceState(functionCall)

Source: https://context7.com/weiroll/weiroll.js/llms.txt

Adds a command that calls a function and replaces the entire planner state with its return value (`bytes[]`). Use this for functions that perform arbitrary state transformations outside the normal weiroll slot model. The function must return exactly `bytes[]`; any other return type throws.

```APIDOC
## planner.replaceState(functionCall)

### Description
Adds a command that calls a function and replaces the entire planner state with its return value (`bytes[]`). Use this for functions that perform arbitrary state transformations outside the normal weiroll slot model. The function must return exactly `bytes[]`; any other return type throws.

### Usage Example
```typescript
import { ethers } from 'ethers';
import { Contract, Planner } from '@weiroll/weiroll.js';

const CONTRACT_ADDRESS = '0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee';
const StateManager = Contract.createLibrary(
  new ethers.Contract(CONTRACT_ADDRESS, [
    'function useState(bytes[] state) returns (bytes[])',
  ])
);

const planner = new Planner();
// Pass current state in, get transformed state back
planner.replaceState(StateManager.useState(planner.state));

const { commands, state } = planner.plan();
console.log(commands.length); // 1
// Return slot byte is 0xfe — signals state replacement
console.log(commands[0]);
// '0x08f389c800fefffffffffffeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee'
console.log(state.length); // 0 (no literals needed)
```
```

--------------------------------

### Add Static Call Command to Planner

Source: https://github.com/weiroll/weiroll.js/blob/main/README.md

Add a contract function call to the planner that will be executed as a static call.

```javascript
const result = planner.add(contract.func(a, b).staticcall());
```

--------------------------------

### planner.add(functionCall)

Source: https://context7.com/weiroll/weiroll.js/llms.txt

Adds a FunctionCall to the planner's command sequence. It returns a ReturnValue handle that can be used as an argument in subsequent calls. If the called function has no outputs or more than one output, it returns null.

```APIDOC
## planner.add(functionCall)

### Description
Adds a `FunctionCall` to the planner's command sequence and returns a `ReturnValue` handle that can be passed as an argument to subsequent calls. Returns `null` if the called function has no outputs or more than one output (use `.rawValue()` in that case). Literal arguments are automatically ABI-encoded and deduplicated in the state array.

### Usage
```typescript
import { ethers } from 'ethers';
import { Contract, Planner } from '@weiroll/weiroll.js';
import * as mathABI from './abis/Math.json';

const MATH_ADDRESS = '0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee';
const Math = Contract.createLibrary(new ethers.Contract(MATH_ADDRESS, mathABI.abi));

const planner = new Planner();

// Return values chain between steps
const sum1 = planner.add(Math.add(1, 2));  // ReturnValue handle
const sum2 = planner.add(Math.add(3, 4));  // ReturnValue handle
planner.add(Math.add(sum1, sum2));          // Uses both return values

const { commands, state } = planner.plan();
// commands: 3 encoded bytes32 command words
// state: ABI-encoded literals [1, 2, 3, 4] + slots for return values
console.log(commands.length); // 3
console.log(state.length);    // 5 (4 literals + 1 intermediate return slot)
```
```

--------------------------------

### Contract.createContract(ethersContract, commandflags?)

Source: https://context7.com/weiroll/weiroll.js/llms.txt

Wraps an ethers.js Contract instance as a standard external contract, where calls default to CALL. Optionally pass CommandFlags.STATICCALL to make all calls on the returned object static by default.

```APIDOC
## Contract.createContract(ethersContract, commandflags?)

### Description
Wraps an ethers.js `Contract` instance as a standard external contract, where calls default to `CALL`. Optionally pass `CommandFlags.STATICCALL` to make all calls on the returned object static by default.

### Usage
```typescript
import { ethers } from 'ethers';
import { Contract, CommandFlags } from '@weiroll/weiroll.js';

const TOKEN_ADDRESS = '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48'; // USDC
const ERC20_ABI = [
  'function transfer(address to, uint256 amount) returns (bool)',
  'function balanceOf(address account) returns (uint256)',
];

const tokenEthers = new ethers.Contract(TOKEN_ADDRESS, ERC20_ABI);

// Standard CALL contract
const Token = Contract.createContract(tokenEthers);

// Static-only contract (all calls use STATICCALL)
const TokenReadOnly = Contract.createContract(tokenEthers, CommandFlags.STATICCALL);

console.log(Token.commandflags);         // 1 (CALL)
console.log(TokenReadOnly.commandflags); // 2 (STATICCALL)
```
```

--------------------------------

### Contract.createLibrary(ethersContract)

Source: https://context7.com/weiroll/weiroll.js/llms.txt

Wraps an ethers.js Contract instance as a weiroll library contract, where all calls default to DELEGATECALL. Use this for weiroll-specific library contracts that are designed to be delegate-called.

```APIDOC
## Contract.createLibrary(ethersContract)

### Description
Wraps an ethers.js `Contract` instance as a weiroll library contract, where all calls default to `DELEGATECALL`. Use this for weiroll-specific library contracts (e.g., utility math or string libraries) that are designed to be delegate-called.

### Usage
```typescript
import { ethers } from 'ethers';
import { Contract } from '@weiroll/weiroll.js';
import * as mathABI from './abis/Math.json';

const MATH_ADDRESS = '0x1234567890123456789012345678901234567890';

// Wrap an ethers.js contract as a weiroll library (DELEGATECALL)
const mathEthers = new ethers.Contract(MATH_ADDRESS, mathABI.abi);
const Math = Contract.createLibrary(mathEthers);

// Math now exposes all ABI functions as FunctionCall factories
// Math.add(a, b), Math.sub(a, b), Math.mul(a, b), Math.sum(values)
console.log(typeof Math.add); // 'function'
```
```

--------------------------------

### Generate Weiroll Program

Source: https://github.com/weiroll/weiroll.js/blob/main/README.md

Generate the final weiroll program commands and state after planning operations.

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

--------------------------------

### Add Raw Value Command to Planner

Source: https://github.com/weiroll/weiroll.js/blob/main/README.md

Add a contract function call to the planner and retrieve its raw return value. This is useful for functions returning multiple values that need decoding.

```javascript
const ret = planner.add(contract.func(a, b).rawValue());
```

--------------------------------

### Add Nested Weiroll Execution Context (Subplan)

Source: https://context7.com/weiroll/weiroll.js/llms.txt

Use `addSubplan` to add a nested execution context. The subplan function must accept a `Planner` and `planner.state`. If the subplan returns `bytes[]`, the parent planner's state is updated.

```typescript
import { ethers } from 'ethers';
import { Contract, Planner } from '@weiroll/weiroll.js';
import * as mathABI from './abis/Math.json';

const MATH_ADDRESS    = '0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee';
const WEIROLL_ADDRESS = '0xCcCCccccCCCCcCCCCCCcCcCccCcCCCcCcccccccC';

const Math = Contract.createLibrary(new ethers.Contract(MATH_ADDRESS, mathABI.abi));
const Weiroll = Contract.createLibrary(
  new ethers.Contract(WEIROLL_ADDRESS, [
    'function execute(bytes32[] commands, bytes[] state) returns (bytes[])',
  ])
);

// Build the subplan
const subplanner = new Planner();
const innerSum = subplanner.add(Math.add(10, 20)); // computes 30

// Build the outer plan — subplan returns updated state so innerSum is visible
const planner = new Planner();
planner.addSubplan(Weiroll.execute(subplanner, subplanner.state));
planner.add(Math.add(innerSum, 5)); // uses return value from inner scope → 35

const { commands, state } = planner.plan();
console.log(commands.length); // 2 (subplan invocation + outer add)
```

--------------------------------

### Add Command with Value to Planner

Source: https://github.com/weiroll/weiroll.js/blob/main/README.md

Add a contract function call to the planner, including a value in ether to send. This cannot be combined with delegate calls or static calls.

```javascript
planner.add(contract.func(a, b).withValue(c));
```

--------------------------------

### Wrap ethers.js Contract as Weiroll Library (DELEGATECALL)

Source: https://context7.com/weiroll/weiroll.js/llms.txt

Use `Contract.createLibrary` to wrap an ethers.js contract for delegate calls. This is suitable for weiroll-specific utility libraries.

```typescript
import { ethers } from 'ethers';
import { Contract } from '@weiroll/weiroll.js';
import * as mathABI from './abis/Math.json';

const MATH_ADDRESS = '0x1234567890123456789012345678901234567890';

// Wrap an ethers.js contract as a weiroll library (DELEGATECALL)
const mathEthers = new ethers.Contract(MATH_ADDRESS, mathABI.abi);
const Math = Contract.createLibrary(mathEthers);

// Math now exposes all ABI functions as FunctionCall factories
// Math.add(a, b), Math.sub(a, b), Math.mul(a, b), Math.sum(values)
console.log(typeof Math.add); // 'function'
```

--------------------------------

### Compile Planner Commands

Source: https://context7.com/weiroll/weiroll.js/llms.txt

Compiles accumulated commands into a result ready for submission to a weiroll executor contract. It computes visibility for slot recycling and encodes each command as a 32-byte word.

```typescript
import { ethers } from 'ethers';
import { Contract, Planner } from '@weiroll/weiroll.js';
import * as stringsABI from './abis/Strings.json';

const STRINGS_ADDRESS = '0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee';
const Strings = Contract.createLibrary(
  new ethers.Contract(STRINGS_ADDRESS, stringsABI.abi)
);

const planner = new Planner();
const concatenated = planner.add(Strings.strcat('Hello, ', 'world!'));
planner.add(Strings.strlen(concatenated)); // chain dynamic return value

const { commands, state } = planner.plan();
// commands[0]: encodes strcat call, stores result in state slot
// commands[1]: encodes strlen call, reading from the return slot of strcat
console.log(commands);
// [
//   '0xd824ccf3008081ffffffff81eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee',
//   '0x367bbd780081ffffffffffffeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee'
// ]
console.log(state.length); // 2 (two string literals; return slot reused)
```

--------------------------------

### Wrap ethers.js Contract as Standard Contract (CALL/STATICCALL)

Source: https://context7.com/weiroll/weiroll.js/llms.txt

Use `Contract.createContract` to wrap an ethers.js contract for standard calls. Optionally specify `CommandFlags.STATICCALL` for read-only operations.

```typescript
import { ethers } from 'ethers';
import { Contract, CommandFlags } from '@weiroll/weiroll.js';

const TOKEN_ADDRESS = '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48'; // USDC
const ERC20_ABI = [
  'function transfer(address to, uint256 amount) returns (bool)',
  'function balanceOf(address account) returns (uint256)',
];

const tokenEthers = new ethers.Contract(TOKEN_ADDRESS, ERC20_ABI);

// Standard CALL contract
const Token = Contract.createContract(tokenEthers);

// Static-only contract (all calls use STATICCALL)
const TokenReadOnly = Contract.createContract(tokenEthers, CommandFlags.STATICCALL);

console.log(Token.commandflags);         // 1 (CALL)
console.log(TokenReadOnly.commandflags); // 2 (STATICCALL)
```

--------------------------------

### Add Command to Planner

Source: https://github.com/weiroll/weiroll.js/blob/main/README.md

Add a contract function call to the planner. The return value can be used in subsequent calls.

```javascript
const ret = planner.add(contract.func(a, b));
```

```javascript
planner.add(contract.func2(ret));
```

--------------------------------

### Wrap ethers.js Contract for Standard/Static Calls

Source: https://github.com/weiroll/weiroll.js/blob/main/README.md

Create weiroll Contract objects for regular calls (CALL) or static calls (STATICCALL) to an ethers.js contract.

```javascript
const ethersContract = new ethers.Contract(address, abi);
// Makes calls using CALL
const contract = weiroll.Contract.createContract(ethersContract);
// Makes calls using STATICCALL
const contract = weiroll.Contract.createContract(ethersContract, CommandFlags.STATICCALL);
```

--------------------------------

### Wrap ethers.js Contract for Delegate Calls

Source: https://github.com/weiroll/weiroll.js/blob/main/README.md

Create a weiroll Contract object that generates delegate calls to an ethers.js contract instance.

```javascript
const ethersContract = new ethers.Contract(address, abi);
const contract = weiroll.Contract.createLibrary(ethersContract);
```

--------------------------------

### Replace Planner State with Function Return Value

Source: https://context7.com/weiroll/weiroll.js/llms.txt

Use `replaceState` to call a function and replace the entire planner state with its `bytes[]` return value. This is for functions performing arbitrary state transformations. The function must return exactly `bytes[]`.

```typescript
import { ethers } from 'ethers';
import { Contract, Planner } from '@weiroll/weiroll.js';

const CONTRACT_ADDRESS = '0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee';
const StateManager = Contract.createLibrary(
  new ethers.Contract(CONTRACT_ADDRESS, [
    'function useState(bytes[] state) returns (bytes[])',
  ])
);

const planner = new Planner();
// Pass current state in, get transformed state back
planner.replaceState(StateManager.useState(planner.state));

const { commands, state } = planner.plan();
console.log(commands.length); // 1
// Return slot byte is 0xfe — signals state replacement
console.log(commands[0]);
// '0x08f389c800fefffffffffffeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee'
console.log(state.length); // 0 (no literals needed)
```

--------------------------------

### Add Function Call to Planner

Source: https://context7.com/weiroll/weiroll.js/llms.txt

Adds a FunctionCall to the planner's command sequence. ReturnValue handles can be passed as arguments to subsequent calls. Literal arguments are ABI-encoded and deduplicated.

```typescript
import { ethers } from 'ethers';
import { Contract, Planner } from '@weiroll/weiroll.js';
import * as mathABI from './abis/Math.json';

const MATH_ADDRESS = '0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee';
const Math = Contract.createLibrary(new ethers.Contract(MATH_ADDRESS, mathABI.abi));

const planner = new Planner();

// Return values chain between steps
const sum1 = planner.add(Math.add(1, 2));  // ReturnValue handle
const sum2 = planner.add(Math.add(3, 4));  // ReturnValue handle
planner.add(Math.add(sum1, sum2));          // Uses both return values

const { commands, state } = planner.plan();
// commands: 3 encoded bytes32 command words
// state: ABI-encoded literals [1, 2, 3, 4] + slots for return values
console.log(commands.length); // 3
console.log(state.length);    // 5 (4 literals + 1 intermediate return slot)
```

--------------------------------

### Capture Multi-Return Function Output as Raw Bytes

Source: https://context7.com/weiroll/weiroll.js/llms.txt

Use `rawValue()` when a target function returns multiple values. The captured bytes can be passed to a subsequent function that accepts and decodes it. Ensure `TUPLE_RETURN` flag is set.

```typescript
import { ethers } from 'ethers';
import { Contract, Planner } from '@weiroll/weiroll.js';

const CONTRACT_ADDRESS = '0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee';
const Test = Contract.createLibrary(
  new ethers.Contract(CONTRACT_ADDRESS, [
    'function returnsTuple() returns (uint256 a, bytes32[] b)',
    'function acceptsBytes(bytes raw)',
  ])
);

const planner = new Planner();
// Capture multi-return function output as raw bytes
const rawResult = planner.add(Test.returnsTuple().rawValue());
// Pass the raw bytes to a decoder function
planner.add(Test.acceptsBytes(rawResult));

const { commands } = planner.plan();
console.log(commands);
// [
//   '0x61a7e05e80ffffffffffff00eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee',
//   '0x3e9ef66a0080ffffffffffffeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee'
// ]
```

--------------------------------

### FunctionCall.withValue(value)

Source: https://context7.com/weiroll/weiroll.js/llms.txt

Returns a new FunctionCall that sends ether with the call, changing the call type to CALL_WITH_VALUE. The `value` can be a literal number or a ReturnValue from a previous step. This method is only valid on CALL-type function calls.

```APIDOC
## FunctionCall.withValue(value)

### Description
Returns a new `FunctionCall` that sends ether with the call (upgrades the call type to `CALL_WITH_VALUE`). `value` can be a literal number or a `ReturnValue` from a previous step. Only valid on `CALL`-type function calls — throws on `DELEGATECALL` or `STATICCALL`.

### Usage
```typescript
import { ethers } from 'ethers';
import { Contract, Planner } from '@weiroll/weiroll.js';
import * as mathABI from './abis/Math.json';

const MATH_ADDRESS   = '0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee';
const VAULT_ADDRESS  = '0xDeaDbeefdEAdbeefdEadbEEFdeadbeEFdEaDbeeF';

const Math  = Contract.createLibrary(new ethers.Contract(MATH_ADDRESS, mathABI.abi));
const Vault = Contract.createContract(
  new ethers.Contract(VAULT_ADDRESS, ['function deposit(uint256 amount) payable'])
);

const planner = new Planner();

// Compute the value to send dynamically from a prior step
const sendAmount = planner.add(Math.add(100, 50)); // 150 wei
planner.add(Vault.deposit(1000).withValue(sendAmount)); // send 150 wei with call

const { commands } = planner.plan();
console.log(commands.length); // 2
// commands[1] will have CALL_WITH_VALUE (0x03) flag byte
```
```

--------------------------------

### FunctionCall.staticcall()

Source: https://context7.com/weiroll/weiroll.js/llms.txt

Returns a new FunctionCall that uses STATICCALL instead of CALL. This is useful for read-only queries within a weiroll program without altering the contract's default call type. This method is only valid on CALL-type function calls.

```APIDOC
## FunctionCall.staticcall()

### Description
Returns a new `FunctionCall` that uses `STATICCALL` instead of `CALL`. Only valid on `CALL`-type function calls; throws on `DELEGATECALL`. Useful for read-only queries inside a weiroll program without changing a contract's default call type.

### Usage
```typescript
import { ethers } from 'ethers';
import { Contract, Planner } from '@weiroll/weiroll.js';
import * as mathABI from './abis/Math.json';

const MATH_ADDRESS = '0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee';
const Math = Contract.createContract(new ethers.Contract(MATH_ADDRESS, mathABI.abi));

const planner = new Planner();
// Force a specific call to be static even though the contract defaults to CALL
planner.add(Math.add(1, 2).staticcall());

const { commands } = planner.plan();
// Flag byte is 0x02 (STATICCALL)
console.log(commands[0]);
// '0x771602f7020001ffffffffffeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee'
```
```

--------------------------------

### CommandFlags enum

Source: https://context7.com/weiroll/weiroll.js/llms.txt

Flags that control how a command's call is executed on-chain. They are set automatically by `createLibrary` / `createContract` / `staticcall()` / `withValue()`, but can also be passed manually to the `Contract` constructor.

```APIDOC
## CommandFlags enum

### Description
Flags that control how a command's call is executed on-chain. They are set automatically by `createLibrary` / `createContract` / `staticcall()` / `withValue()`, but can also be passed manually to the `Contract` constructor.

### Available Flags
- `CommandFlags.DELEGATECALL`  // 0x00 — used by createLibrary
- `CommandFlags.CALL`          // 0x01 — used by createContract
- `CommandFlags.STATICCALL`    // 0x02 — used by createContract(c, CommandFlags.STATICCALL) or .staticcall()
- `CommandFlags.CALL_WITH_VALUE` // 0x03 — set automatically by .withValue()
- `CommandFlags.TUPLE_RETURN`   // 0x80 — set automatically by .rawValue()
- `(EXTENDED_COMMAND 0x40 is set internally for functions with 7+ arguments)`

### Usage Example
```typescript
import { CommandFlags } from '@weiroll/weiroll.js';

// Available flags:
// CommandFlags.DELEGATECALL   // 0x00 — used by createLibrary
// CommandFlags.CALL           // 0x01 — used by createContract
// CommandFlags.STATICCALL     // 0x02 — used by createContract(c, CommandFlags.STATICCALL) or .staticcall()
// CommandFlags.CALL_WITH_VALUE // 0x03 — set automatically by .withValue()
// CommandFlags.TUPLE_RETURN   // 0x80 — set automatically by .rawValue()
// (EXTENDED_COMMAND 0x40 is set internally for functions with 7+ arguments)

// Example: manually construct a static-call contract
import { Contract } from '@weiroll/weiroll.js';
import { ethers } from 'ethers';
const oracle = Contract.createContract(
  new ethers.Contract('0xAbCd...', ['function getPrice(address) returns (uint256)']),
  CommandFlags.STATICCALL
);
```
```

--------------------------------

### FunctionCall.rawValue()

Source: https://context7.com/weiroll/weiroll.js/llms.txt

Returns a new `FunctionCall` whose return value is wrapped in `bytes`. This is useful for functions that return multiple values, as weiroll normally only captures a single return value. The captured `bytes` can be passed to a subsequent function that accepts and decodes it.

```APIDOC
## FunctionCall.rawValue()

### Description
Returns a new `FunctionCall` whose return value is wrapped in `bytes` (sets `TUPLE_RETURN` flag). Use this when the target function returns multiple values, since weiroll normally only captures a single return value. The captured `bytes` can be passed to a subsequent function that accepts and decodes it.

### Usage Example
```typescript
import { ethers } from 'ethers';
import { Contract, Planner } from '@weiroll/weiroll.js';

const CONTRACT_ADDRESS = '0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee';
const Test = Contract.createLibrary(
  new ethers.Contract(CONTRACT_ADDRESS, [
    'function returnsTuple() returns (uint256 a, bytes32[] b)',
    'function acceptsBytes(bytes raw)',
  ])
);

const planner = new Planner();
// Capture multi-return function output as raw bytes
const rawResult = planner.add(Test.returnsTuple().rawValue());
// Pass the raw bytes to a decoder function
planner.add(Test.acceptsBytes(rawResult));

const { commands } = planner.plan();
console.log(commands);
// [
//   '0x61a7e05e80ffffffffffff00eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee',
//   '0x3e9ef66a0080ffffffffffffeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee'
// ]
```
```

--------------------------------

### Perform Static Call

Source: https://context7.com/weiroll/weiroll.js/llms.txt

Returns a new FunctionCall that uses STATICCALL instead of CALL. This is useful for read-only queries within a weiroll program without changing a contract's default call type. Only valid on CALL-type function calls.

```typescript
import { ethers } from 'ethers';
import { Contract, Planner } from '@weiroll/weiroll.js';
import * as mathABI from './abis/Math.json';

const MATH_ADDRESS = '0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee';
const Math = Contract.createContract(new ethers.Contract(MATH_ADDRESS, mathABI.abi));

const planner = new Planner();
// Force a specific call to be static even though the contract defaults to CALL
planner.add(Math.add(1, 2).staticcall());

const { commands } = planner.plan();
// Flag byte is 0x02 (STATICCALL)
console.log(commands[0]);
// '0x771602f7020001ffffffffffeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee'
```

--------------------------------

### Add Ether Value to Function Call

Source: https://context7.com/weiroll/weiroll.js/llms.txt

Returns a new FunctionCall that sends ether with the call, upgrading the call type to CALL_WITH_VALUE. The value can be a literal or a ReturnValue from a previous step. Only valid on CALL-type function calls.

```typescript
import { ethers } from 'ethers';
import { Contract, Planner } from '@weiroll/weiroll.js';
import * as mathABI from './abis/Math.json';

const MATH_ADDRESS   = '0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee';
const VAULT_ADDRESS  = '0xDeaDbeefdEAdbeefdEadbEEFdeadbeEFdEaDbeeF';

const Math  = Contract.createLibrary(new ethers.Contract(MATH_ADDRESS, mathABI.abi));
const Vault = Contract.createContract(
  new ethers.Contract(VAULT_ADDRESS, ['function deposit(uint256 amount) payable'])
);

const planner = new Planner();

// Compute the value to send dynamically from a prior step
const sendAmount = planner.add(Math.add(100, 50)); // 150 wei
planner.add(Vault.deposit(1000).withValue(sendAmount)); // send 150 wei with call

const { commands } = planner.plan();
console.log(commands.length); // 2
// commands[1] will have CALL_WITH_VALUE (0x03) flag byte
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.