sketch for gui struct in rust

[hardyjosh]

Interface Definition for DotrainOrderGui

TODO:

• think about how we can modify tokens and when in the process this happens, especially if we have contextual replacements in bindings etc

Core Interfaces

DotrainOrder

// The underlying order implementation that handles RainLang composition and deployment
(As per attached implementation)

Deposit

// Configuration for what token deposits are allowed for a deployment
struct Deposit {
   token: String,      // Token identifier matching the YAML config
   min: f64,          // Minimum amount that can be deposited
   presets: Vec<f64>  // Suggested/common deposit amounts to show in UI
}

Preset

// A preset value for a field with a human readable name
struct Preset {
   name: String,     // Human readable name for the preset (e.g. "Every hour (3600)")
   value: FieldValue // The actual value for this preset
}

FieldDefinition

// Definition of a configurable field in a deployment
struct FieldDefinition {
   id: String,         // Unique identifier (hash of the field definition)
   name: String,       // Human readable field name
   description: String, // Detailed field description/help text
   validation: String,  // JSON Schema string for field validation
   presets: Vec<Preset> // Suggested/common values for this field
}

Deployment

// A complete deployment configuration from the YAML
struct Deployment {
   id: String,           // Deployment identifier
   name: String,         // Human readable name
   description: String,  // Detailed deployment description
   deposits: Vec<Deposit>, // Allowed token deposits
   fields: Vec<FieldDefinition> // Configurable fields
}

GUI

// Main state container for order configuration
struct DotrainOrderGui {
   dotrain_order: DotrainOrder,  // Reference to underlying order
   deployment: Deployment,        // Selected deployment configuration
   field_values: HashMap<String, FieldValue>, // Current values for fields
   deposits: Vec<TokenDeposit>,  // Current token deposits
}

Constructor

// Creates new GUI for configuring a specific deployment
DotrainOrderGui::new(dotrain_order: DotrainOrder, deployment_id: String) -> Result<Self, GuiError>

Field Operations

// Save single field value with validation
save_field(field_id: String, value: FieldValue) -> Result<(), ValidationError>

// Save multiple field values at once with validation
save_fields(field_values: Vec<(String, FieldValue)>) -> Result<(), Vec<ValidationError>>

// Get current value for a field
get_field_value(field_id: String) -> Option<FieldValue> 

// Get all current field values
get_all_field_values() -> HashMap<String, FieldValue>

// Get definition for a field
get_field_definition(field_id: String) -> Option<FieldDefinition>

// Get all field definitions
get_all_field_definitions() -> Vec<FieldDefinition>

Deposit Operations

// Get current token deposits
get_deposits() -> Vec<TokenDeposit>

// Save token deposit with validation
save_deposit(deposit: TokenDeposit) -> Result<(), ValidationError>

// Remove a token deposit
remove_deposit(deposit_id: String)

State Management

// Serialize current state for sharing/saving (e.g. URL params)
serialize() -> Result<String, SerializeError>

// Restore state from serialized form
deserialize_state(state: String) -> Result<(), DeserializeError>

// Reset all state to defaults
reset_state()

Order Operations

// Check if tokens have sufficient allowances for deposits
check_allowances() -> Vec<TokenAllowance>

// Generate approval transaction data for insufficient allowances
generate_approval_calldatas() -> Vec<(Address, Bytes)>  // (token_address, calldata)

// Generate deposit transaction data
generate_deposit_calldatas() -> Vec<Bytes>

// Generate add order transaction data
generate_add_order_calldata() -> Bytes

// Generate combined deposit and add order transaction data
generate_deposit_and_add_order_calldata() -> Bytes

Core Types

FieldValue

// Possible field value types
enum FieldValue {
   Text(String),   // Text input
   Number(f64),    // Numeric input 
   Address(String), // Ethereum address
   Boolean(bool)   // True/false toggle
}

// A configured token deposit amount
struct TokenDeposit {
   token: String,  // Token identifier
   amount: f64,    // Deposit amount
   address: String // Token contract address
}

// Token approval status
struct TokenAllowance {
   token: String,            // Token identifier
   current_allowance: u256,  // Current approved amount
   required_allowance: u256  // Required approved amount
}

Error Types

ValidationError

// Field validation error
struct ValidationError {
   field_id: String,  // ID of field that failed validation
   message: String,   // Human readable error message
   schema_errors: Vec<ValidationFailure> // Detailed JSON Schema validation errors
}

GuiError

// Possible GUI operation errors
enum GuiError {
   DeploymentNotFound(String),     // Deployment ID not found
   InvalidFieldValue(ValidationError), // Field validation failed
   InvalidDeposit(ValidationError),   // Deposit validation failed 
   InvalidState(String),              // Invalid serialized state
   DotrainError(DotrainOrderError)    // Underlying order error
}

SerializeError

// Error serializing state

DeserializeError

// Error deserializing state

[findolor]

for order operations we also need to add a function for fetching token info

[hardyjosh]

we need a way to flag tokens as swappable, so rather than defining the tokens up front, i can change their address as a first step

We can mark which tokens in the tokens map can be changed:

''' gui: select-tokens:

• token1
• token2

tokens: token1: address: 0x00 (placeholder) token2: address: 0x00 '''

token1 and token2 would be used in the order, and as a first step of the gui you can change their address

this structure means we can map one choice to both an input and output, e.g.

''' my-order: inputs:

• token1
• token2 outputs:
• token1
• token2 '''

this must be done as a first step before anything else. we'll be adding token replacement for token symbols into field descriptions, which means we need to know the token symbols up front.

[hardyjosh]

We also need the ability to optionally set a vault id that will be used for all inputs and outputs in the order.

This could be done at any stage by updating the OrderIO for the relevant order

https://github.com/rainlanguage/rain.orderbook/blob/main/crates/settings/src/order.rs#L32