Checks if all required tokens have been selected and configured.

Validates that every token in the select-tokens configuration has been given an address. Use this for overall validation and progress tracking.

Examples

const result = gui.areAllTokensSelected();
if (result.error) {
  console.error("Error:", result.error.readableMsg);
  return;
}

const allSelected = result.value;
// Do something
Copy

Checks token allowances for all deposits against the orderbook contract.

Queries the blockchain to determine current allowances for each output token that will be deposited. This helps determine which tokens need approval before the order can be created.

Examples

const result = await gui.checkAllowances(walletAddress);
if (result.error) {
  console.error("Allowance check failed:", result.error.readableMsg);
  return;
}
const [allowance1, allowance2, ...] = result.value;
const {
  // token is the token address
  token,
  // allowance is the current allowance for the token
  allowance,
} = allowance1;
Copy

Validates that all required tokens have been selected.

Checks if all tokens in the select-tokens configuration have been given addresses. Use this before generating transactions to ensure completeness.

Examples

const result = gui.checkSelectTokens();
if (result.error) {
  console.error("Selection incomplete:", result.error.readableMsg);
  return;
// Do something
Copy

Manually triggers the state update callback.

Calls the registered state update callback with the current serialized state. This is typically called automatically after state-changing operations, but can be triggered manually if needed.

Examples

// Manual state update trigger
const result = gui.executeStateUpdateCallback();
if (result.error) {
  console.error("Callback error:", result.error.readableMsg);
}
Copy

Generates calldata for adding the order to the orderbook.

Creates the addOrder calldata with all field values applied to the Rainlang code and proper vault configurations.

Examples

const result = await gui.generateAddOrderCalldata();
if (result.error) {
  console.error("Cannot create order:", result.error.readableMsg);
  // Show user what needs to be fixed
  return;
}
const addOrderCalldata = result.value;
// Do something with the add order calldata
Copy

Generates approval calldatas for tokens that need increased allowances.

Automatically checks current allowances and generates approval calldata whenever the on-chain allowance differs from the planned deposit amount.

Examples

const result = await gui.generateApprovalCalldatas(walletAddress);
if (result.error) {
  console.error("Error:", result.error.readableMsg);
  return;
}

// If there are approvals
const [approval1, approval2, ...] = result.value;
const {
  // token is the token address
  token,
  // calldata is the approval calldata
  calldata,
} = approval1;
Copy

Generates a multicall combining all deposits and add order in one calldata.

This is the most efficient way to deploy an order, combining all necessary operations into a single calldata to minimize gas costs and ensure atomicity.

Transaction Structure

The multicall includes:

1. AddOrder call (always first)
2. All deposit calls for non-zero amounts

Examples

const result = await gui.generateDepositAndAddOrderCalldatas();
if (result.error) {
  console.error("Error:", result.error.readableMsg);
  return;
}
const multicallData = result.value;
// Do something with the multicall data
Copy

Generates calldata for depositing tokens into orderbook vaults.

Creates deposit calldatas for all configured deposits, automatically skipping zero amounts and ensuring vault IDs are properly assigned.

Examples

const result = await gui.generateDepositCalldatas();
if (result.error) {
  console.error("Error:", result.error.readableMsg);
  return;
}

// If there are deposits
const [depositCalldata1, depositCalldata2, ...] = result.value;
const {
  // calldata is the deposit calldata
  calldata,
} = depositCalldata1;
Copy

Exports the current configuration as a complete dotrain text file.

This generates a valid dotrain file with YAML frontmatter and Rainlang code, preserving all configurations and bindings. Useful for saving or sharing orders.

Format

The output follows the standard dotrain format:

gui:
  ...
---
#binding1 !The binding value
#calculate-io
...
Copy

Examples

const result = gui.generateDotrainText();
if (result.error) {
  console.error("Export failed:", result.error.readableMsg);
  return;
}
const dotrain = result.value;
// Do something with the dotrain
Copy

Gets the balance of a specific token for a given owner address

Retrieves the ERC20 token balance by connecting to the current deployment's network RPC and querying the token contract.

Examples

const result = await gui.getAccountBalance("0x123...", "0xabc...");
if (result.error) {
  console.error("Error:", result.error.readableMsg);
  return;
}

console.log("Raw balance:", result.value.balance);
console.log("Formatted balance:", result.value.formattedBalance);
Copy

Gets all field definitions with optional filtering by default value presence.

This method helps build dynamic forms by providing all field configurations at once. The filter option allows separating required fields (no default) from optional fields (with default).

Examples

// Get all fields
const allFieldsResult = gui.getAllFieldDefinitions();
if (allFieldsResult.error) {
  console.error("Error:", allFieldsResult.error.readableMsg);
  return;
}

// Get only required fields (no defaults)
const requiredResult = gui.getAllFieldDefinitions(false);
if (requiredResult.error) {
  console.error("Error:", requiredResult.error.readableMsg);
  return;
}
const requiredFields = requiredResult.value;

// Get optional fields (with defaults)
const optionalResult = gui.getAllFieldDefinitions(true);
if (optionalResult.error) {
  console.error("Error:", optionalResult.error.readableMsg);
  return;
}
const optionalFields = optionalResult.value;

Copy

Gets all configured field values with their metadata.

Returns all field values that have been set, with preset values expanded.

Examples

const result = gui.getAllFieldValues();
if (result.error) {
  console.error("Error:", result.error.readableMsg);
  return;
}

const [fieldValue1, fieldValue2, ...] = result.value;
const {
  // field is the field identifier
  field,
  // value is the field value
  value,
  // isPreset is a boolean indicating if the value is a preset
  isPreset
} = fieldValue1;
Copy

Gets comprehensive configuration for complete UI initialization.

Provides all configuration data needed to build a complete order interface, organized by requirement type for progressive UI construction.

Configuration Structure

• fieldDefinitionsWithoutDefaults - Required fields needing user input
• fieldDefinitionsWithDefaults - Optional fields with fallback values
• deposits - Deposit configurations with tokens and presets
• orderInputs - Input token configurations
• orderOutputs - Output token configurations

Examples

const result = gui.getAllGuiConfig();
if (result.error) {
  console.error("Error:", result.error.readableMsg);
  return;
}
const config = result.value;

// Build required fields section
config.fieldDefinitionsWithoutDefaults.forEach(field => {
  // Do something with the fields
});

// Build optional fields section
if (config.fieldDefinitionsWithDefaults.length > 0) {
  // Do something with the fields
}

// Build deposits section
config.deposits.forEach(deposit => {
  // Do something with the deposits
});

// Show order preview
config.orderInputs.forEach(input => {
  // Do something with the order inputs
});
config.orderOutputs.forEach(output => {
  // Do something with the order outputs
});
Copy

Gets information for all tokens used in the current deployment's order.

This function automatically determines which tokens to fetch based on the deployment:

• If select-tokens is defined, returns info for those tokens
• Otherwise, returns info for all input/output tokens in the order

Performance Note

This may trigger multiple blockchain queries if token data isn't cached in YAML. Consider caching the results in your application.

Examples

const result = await gui.getAllTokenInfos();
if (result.error) {
  console.error("Error:", result.error.readableMsg);
  return;
}
const tokens = result.value;
// Do something with the tokens
Copy

Gets all tokens configured for the selected deployment's network.

Retrieves token information from the YAML configuration, using cached metadata when available or fetching from blockchain via ERC20 contracts. Results are filtered by the search term (matching name or address) and sorted by address and deduplicated.

Examples

// Get all tokens
const result = await gui.getAllTokens();

// Search for specific tokens
const usdcResult = await gui.getAllTokens("USDC");
const addressResult = await gui.getAllTokens("0x1234...");
Copy

Composes the final Rainlang code with all bindings and scenarios applied.

This method updates scenario bindings from current field values and composes the Rainlang code ready to be displayed on the UI.

Side Effects

Updates the internal scenario bindings before composition.

Examples

const result = await gui.getComposedRainlang();
if (result.error) {
  console.error("Composition error:", result.error.readableMsg);
  return;
}
const rainlang = result.value;
// Do something with the rainlang
Copy

Gets the active deployment's configuration including fields, deposits, and tokens.

This is the primary method for accessing deployment-specific settings that define what inputs are needed from the user. The configuration drives UI generation.

Configuration Structure

• fields - Input fields requiring user configuration
• deposits - Token deposits with amounts and presets
• selectTokens - Tokens that users must choose addresses for
• deployment - Underlying order and scenario configuration

Examples

const result = gui.getCurrentDeployment();
if (result.error) {
  console.error("Error:", result.error.readableMsg);
  return;
}
const deployment = result.value;
// Do something with the deployment
Copy

Gets metadata for the currently active deployment.

Instance method that returns name and description for the deployment selected during initialization.

Examples

const result = gui.getCurrentDeploymentDetails();
if (result.error) {
  console.error("Error:", result.error.readableMsg);
  return;
}
const details = result.value;
// Do something with the details
Copy

Gets transaction data for order deployment including approvals.

This is the comprehensive function that provides everything needed to deploy an order: approval calldatas, the main deployment transaction, and metadata. Use this for full transaction orchestration.

Transaction Package

• approvals - Token approval calldatas with symbols for UI
• deploymentCalldata - Main order deployment calldata
• orderbookAddress - Target contract address
• chainId - Network identifier

Examples

const result = await gui.getDeploymentTransactionArgs(walletAddress);
if (result.error) {
  console.error("Error:", result.error.readableMsg);
  return;
}

const {
  // approvals is an array of extended approval calldatas
  // extended approval calldata includes the token address, calldata, and symbol
  approvals,
  // deploymentCalldata is the multicall calldata for the order
  deploymentCalldata,
  // orderbookAddress is the address of the orderbook
  orderbookAddress,
  // chainId is the chain ID of the network
  chainId,
} = result.value;
Copy

Gets preset amounts available for a specific deposit token.

Returns the preset values configured for this token in the deployment, useful for building quick-select interfaces.

Examples

const result = gui.getDepositPresets("usdc");
if (result.error) {
  console.error("Error:", result.error.readableMsg);
  return;
}
// items are preset amounts
const [preset1, preset2, ...] = result.value;
Copy

Gets all configured deposit amounts with token information.

Returns deposits as token deposits with human-readable amounts and addresses. This combines the stored deposit amounts with token metadata for display and transaction preparation.

Examples

const result = gui.getDeposits();
if (result.error) {
  console.error("Error:", result.error.readableMsg);
  return;
}
const [deposit1, deposit2, ...] = result.value;
const {
  // token is the token address
  token,
  // amount is the deposit amount
  amount,
  // address is the token address
} = deposit1;
Copy

Gets the complete definition for a specific field including presets and validation.

Use this to build dynamic UIs that adapt to field configurations, showing appropriate input controls, preset options, and validation rules.

Examples

const result = gui.getFieldDefinition("max-price");
if (result.error) {
  console.error("Not found:", result.error.readableMsg);
  return;
}

const {
  // field is the field identifier
  field,
  // name is the display name for the field
  name,
  // description is the help text for the field
  description,
  // presets are the available preset options for the field
  presets,
  // default is the default value for the field if no value is set by the user
  default,
  // showCustomField is a boolean indicating if the field allows custom input
  showCustomField
} = result.value;
Copy

Retrieves a field value with preset expansion and metadata.

This function returns the saved value along with information about whether it's a preset.

Examples

const result = gui.getFieldValue("max-price");
if (result.error) {
  console.error("Not found:", result.error.readableMsg);
  return;
}

const { field, value, isPreset } = result.value;
// field is the field identifier
// value is the field value
// isPreset is a boolean indicating if the value is a preset
Copy

Retrieves the complete GUI configuration including all deployments.

This returns the parsed GUI section from the YAML, filtered to include only the current deployment. Use this to access order-level metadata.

Examples

const result = gui.getGuiConfig();
if (result.error) {
  console.error("Config error:", result.error.readableMsg);
  return;
}
const config = result.value;
// Do something with the config
Copy

Lists tokens that require deposits but haven't been configured.

Returns token keys for deposits that are required by the deployment but haven't been set yet. Use this for validation and user guidance.

Examples

const result = gui.getMissingDeposits();
if (result.error) {
  console.error("Error:", result.error.readableMsg);
  return;
}
// items are token keys
const [missing1, missing2, ...] = result.value;
if (missing.length > 0) {
  // Do something with the missing tokens
}
Copy

Lists field definitions that haven't been configured yet.

Returns field definitions for fields that need values. Use this for validation and to guide users through required configurations.

Examples

const result = gui.getMissingFieldValues();
if (result.error) {
  console.error("Error:", result.error.readableMsg);
  return;
}
const missing = result.value;
// Do something with the missing
Copy

Gets tokens that need user selection for the current deployment.

Returns tokens defined in the select-tokens section that require user input to specify contract addresses. This enables generic orders that work with user-chosen tokens.

Examples

const result = gui.getSelectTokens();
if (result.error) {
  console.error("Error:", result.error.readableMsg);
  return;
}

const selectableTokens = result.value;
// Do something with the selectable tokens
Copy

Retrieves detailed token information from YAML configuration or blockchain.

This function first checks the YAML for cached token data (decimals, name, symbol). If any information is missing, it queries the blockchain to fetch the complete details. This hybrid approach minimizes RPC calls while ensuring accurate data.

Network Selection

The RPC endpoint is determined by the deployment's order network configuration.

Examples

// Get token info (may query blockchain)
const result = await gui.getTokenInfo("weth");
if (result.error) {
  console.error("Token error:", result.error.readableMsg);
  return;
}
const tokenInfo = result.value;
// Do something with the tokenInfo
Copy

Gets all configured vault IDs for inputs and outputs.

Returns a map with 'input' and 'output' keys, where each value is a map of token keys to their configured vault IDs (or undefined if not set).

Examples

const result = gui.getVaultIds();
if (result.error) {
  console.error("Error:", result.error.readableMsg);
  return;
}

// Access input token vault IDs
for (const [tokenKey, vaultId] of result.value.get('input')) {
  console.log(`Input token ${tokenKey} uses vault ${vaultId || 'none'}`);
}

// Access output token vault IDs
for (const [tokenKey, vaultId] of result.value.get('output')) {
  console.log(`Output token ${tokenKey} uses vault ${vaultId || 'none'}`);
}
Copy

Checks if any deposits have been configured.

Quick check to determine if the user has started configuring deposits. Useful for showing different UI states or progress indicators.

Examples

const result = gui.hasAnyDeposit();
if (result.error) {
  console.error("Error:", result.error.readableMsg);
  return;
}
const hasDeposits = result.value;
if (!hasDeposits) {
  // Do something
}
Copy

Checks if any vault IDs have been configured.

Quick validation to determine if vault configuration has started. Useful for UI state management and validation flows.

Examples

const result = gui.hasAnyVaultId();
if (result.error) {
  console.error("Error:", result.error.readableMsg);
  return;
}

const hasVaults = result.value;
// Do something with the has vaults
Copy

Checks if a selectable token has been configured with an address.

Use this to determine if a user has provided an address for a select-token, enabling progressive UI updates and validation.

Examples

const result = gui.isSelectTokenSet("stable-token");
if (result.error) {
  console.error("Error:", result.error.readableMsg);
  return;
}

const isSelectTokenSet = result.value;
// Do something
Copy

Exports the complete GUI state as a compressed, encoded string.

Serializes all current configuration including field values, deposits, selected tokens, and vault IDs into a compact format for persistence or sharing. The output is gzipped and base64-encoded.

State Contents

• Field values with preset information
• Deposit amounts with preset references
• Selected token configurations
• Vault ID assignments
• Configuration hash for validation

Examples

const result = gui.serializeState();
if (result.error) {
  console.error("Serialization error:", result.error.readableMsg);
  return;
}
const state = result.value;
// Do something with the state
Copy

Sets a deposit amount for a specific token.

Sets the deposit amount for a token, automatically detecting if the amount matches a preset value.

Preset Detection

If the amount matches a preset value from the configuration, it's stored as a preset reference for efficiency and consistency.

Examples

// Set a custom deposit amount
const result = await gui.setDeposit("usdc", "1000.50");
if (result.error) {
  console.error("Deposit error:", result.error.readableMsg);
  return;
}
Copy

Sets a value for a specific field binding with automatic preset detection.

This function stores the provided value and automatically determines if it matches a preset from the field definition. Preset detection enables the UI to show whether a standard option or custom value is being used.

Preset Detection

The function checks if the value matches any preset in the field definition. If it matches, it stores the preset index; otherwise, stores the raw value.

Examples

// Set a custom value
const result = gui.setFieldValue("max-price", "1500.50");
if (result.error) {
  console.error("Set failed:", result.error.readableMsg);
  return;
}
Copy

Batch sets multiple field values in a single operation.

This is more efficient than calling setFieldValue multiple times, especially when loading saved configurations or applying templates. Each value is processed with the same preset detection as individual saves.

Examples

const fields = [
  { field: "max-price", value: "1500" },
  { field: "min-amount", value: "100" },
  { field: "slippage", value: "0.5" }
];

const result = gui.setFieldValues(fields);
if (result.error) {
  console.error("Batch set failed:", result.error.readableMsg);
  return;
}
Copy

Sets a custom token address to be used in the order.

Takes a token address provided by the user and queries the blockchain to get the token's name, symbol, and decimals. This information is then cached for efficient access.

Network Usage

The function uses the deployment's network configuration to determine the RPC endpoint for querying token information.

Examples

// User selects token
const result = await gui.setSelectToken(
  "stable-token",
  "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
);

if (result.error) {
  console.error("Selection failed:", result.error.readableMsg);
  return;
}
// Do something with the token
Copy

Configures vault IDs for order inputs or outputs.

Sets the vault ID for a specific input or output token. Vault IDs determine which vaults are used for the input or output tokens in the order.

Examples

const result1 = gui.setVaultId("input", "token1", "42");
if (result1.error) {
  console.error("Error:", result1.error.readableMsg);
  return;
}
const result2 = gui.setVaultId("output", "token2", "43");
const result3 = gui.setVaultId("output", "token2", undefined);
Copy

Unsets the deposit amount for a specific token.

Use this to clear a deposit that's no longer needed.

Examples

// Unset a specific token deposit
const result = gui.unsetDeposit("usdc");
if (result.error) {
  console.error("Unset failed:", result.error.readableMsg);
  return;
}
Copy

Unsets a previously set field value.

Use this to clear a field value, returning it to an unset state.

Examples

// Clear a field value
const result = gui.unsetFieldValue("max-price");
if (result.error) {
  console.error("Unset failed:", result.error.readableMsg);
  return;
}
Copy

Removes a previously selected token configuration.

Clears the address and cached information for a select-token, returning it to an unselected state.

Examples

// Remove token selection
const result = gui.unsetSelectToken("stable-token");
if (result.error) {
  console.error("Remove failed:", result.error.readableMsg);
  return;
}
Copy

Gets metadata for a specific deployment by key.

Convenience method that extracts details for a single deployment without parsing all deployments.

Examples

const result = await getDeploymentDetail(dotrainYaml, "mainnet-order");
if (result.error) {
  console.error("Not found:", result.error.readableMsg);
  return;
}
const detail = result.value;
// Do something with the detail
Copy

Gets metadata for all deployments defined in the configuration.

This static method extracts name and description for each deployment, useful for building deployment selection interfaces with rich descriptions.

Examples

const result = await getDeploymentDetails(dotrainYaml);
if (result.error) {
  console.error("Error:", result.error.readableMsg);
  return;
}

// key is the deployment key
// value is the deployment metadata
for (const [key, value] of result.value) {
  const {
    // name is the deployment name
    // description is the deployment description
    name,
    description,
    // short_description is the deployment short description (optional)
    short_description,
  } = value;
}
Copy

Lists all available gui deployment keys from a dotrain YAML file.

This function parses the gui section of the YAML frontmatter to extract deployment keys that can be used to initialize a GUI instance. Use this to build deployment selectors in your UI.

Examples

const dotrain = `
gui:
  deployments:
    mainnet-order:
      name: "Mainnet Trading"
    testnet-order:
      name: "Test order"
`;

const result = await DotrainOrderGui.getDeploymentKeys(dotrain);
if (result.error) {
  console.error("Error:", result.error.readableMsg);
  return;
}
const deploymentKeys = result.value;
// Do something with the deploymentKeys
Copy

Extracts order-level metadata from a dotrain configuration.

This static method allows checking order details without creating a GUI instance, useful for displaying order information before deployment selection.

Required Fields

The YAML must contain:

• gui.name - Order display name
• gui.description - Full order description
• gui.short-description - Brief summary (optional but recommended)

Examples

const result = await getOrderDetails(dotrainYaml);
if (result.error) {
  console.error("Error:", result.error.readableMsg);
  return;
}
const details = result.value;
// Do something with the details
Copy

Restores a GUI instance from previously serialized state.

Creates a new GUI instance with all configuration restored from a saved state. The dotrain content must match the original for security validation.

Security

The function validates that the dotrain content hasn't changed by comparing hashes. This prevents state injection attacks and ensures consistency.

Examples

const result = await DotrainOrderGui.newFromState(dotrainYaml, savedState);
if (result.error) {
  console.error("Restore failed:", result.error.readableMsg);
  return;
}
const gui = result.value;
// Do something with the gui
Copy

Creates a new GUI instance for managing a specific deployment configuration.

This is the primary initialization function that sets up the GUI context for a chosen deployment. The instance tracks field values, deposits, token selections, and provides methods for generating order transactions.

State Management

The callback function receives a serialized state string on every change, enabling auto-save functionality or state synchronization across components.

Examples

// Basic initialization
const result = await DotrainOrderGui.newWithDeployment(dotrainYaml, "mainnet-order");
if (result.error) {
  console.error("Init failed:", result.error.readableMsg);
  return;
}
const gui = result.value;

// With state persistence
const result = await DotrainOrderGui.newWithDeployment(
  dotrainYaml,
  "mainnet-order",
  (serializedState) => {
    localStorage.setItem('orderState', serializedState);
  }
);
if (!result.error) {
  const gui = result.value;
  // Use gui instance...
}
Copy