Skip to content

Spec update to better support multi-chain guis #39

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
hardyjosh wants to merge 3 commits into
base: main
Choose a base branch
from
Open

Spec update to better support multi-chain guis #39

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
f0496e2
gui update
hardyjosh Sep 2, 2025
219d879
ob yaml
hardyjosh Sep 2, 2025
de48f36
network values
hardyjosh Sep 2, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
228 changes: 105 additions & 123 deletions gui.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,100 +4,162 @@

The `gui` section within the YAML configuration provides metadata specifically tailored for building user interfaces related to Rainlang strategies. It acts as a bridge between the core technical definition of deployments, tokens, orders, etc., and their presentation to an end-user in a graphical application.

This section dictates how strategy deployments are named, described, and how their configurable parameters (bindings, deposits, token selections) should be rendered as interactive UI elements. It allows for user-friendly labels, descriptions, default values, and predefined options (presets) to simplify the user experience.
This section dictates how strategies are named, described, and how their configurable parameters (bindings, deposits, token selections) should be rendered as interactive UI elements. It allows for user-friendly labels, descriptions, default values, and predefined options (presets) to simplify the user experience.
Copy link

@coderabbitai coderabbitai bot Sep 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick (assertive)

Tighten sentence and fix comma splice.

Apply this diff:

-This section dictates how strategies are named, described, and how their configurable parameters (bindings, deposits, token selections) should be rendered as interactive UI elements.
+This section dictates how strategies are named and described, and how configurable parameters (bindings, deposits, token selections) are rendered as interactive UI elements.
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
This section dictates how strategies are named, described, and how their configurable parameters (bindings, deposits, token selections) should be rendered as interactive UI elements. It allows for user-friendly labels, descriptions, default values, and predefined options (presets) to simplify the user experience.
This section dictates how strategies are named and described, and how configurable parameters (bindings, deposits, token selections) are rendered as interactive UI elements.
🧰 Tools
🪛 LanguageTool

[grammar] ~7-~7: There might be a mistake here.
Context: ...ection dictates how strategies are named, described, and how their configurable p...

(QB_NEW_EN_OTHER)

[grammar] ~7-~7: Use commas correctly
Context: ...ates how strategies are named, described, and how their configurable parameters (...

(QB_NEW_EN_OTHER_ERROR_IDS_33)

[grammar] ~7-~7: Use correct spacing
Context: ...resets) to simplify the user experience. ## Top-Level gui Object The root of the ...

(QB_NEW_EN_OTHER_ERROR_IDS_5)

🤖 Prompt for AI Agents 
In gui.md around line 7, the sentence is a comma splice and needs tightening;
rewrite it into two clauses or use proper punctuation so it reads clearly — for
example split into two sentences or add a conjunction, and ensure the meaning
(naming, descriptions, and rendering of configurable parameters as interactive
UI elements with labels, descriptions, default values and presets) remains
unchanged.


## Top-Level `gui` Object

The root of the GUI configuration is the `gui:` key. It contains general information about the strategy or set of deployments described in the file.
The root of the GUI configuration is the `gui:` key. It contains general information about the strategy and defines reusable field definitions and variations.

```yaml
gui:
name: Fixed limit
description: Fixed limit order strategy
short-description: Buy WETH with USDC on Base.
deployments:
# ... deployment configurations ...
field-definitions:
# ... field definitions ...
variations:
# ... variation configurations ...
```

### Fields

* `name`
* **Required**: Yes
* **Description**: The primary, human-readable name for the overall strategy or configuration presented in the GUI.
* **Description**: The primary, human-readable name for the overall strategy presented in the GUI.
* `description`
* **Required**: Yes
* **Description**: A more detailed description of the strategy or configuration, intended for display in the GUI.
* **Description**: A more detailed description of the strategy, intended for display in the GUI.
* `short-description`
* **Required**: No
* **Description**: An optional, concise description, potentially used in contexts where space is limited (e.g., list views, tooltips).
* `deployments`
* `field-definitions`
* **Required**: No
* **Description**: A map of reusable field definitions that can be referenced by variations. See the [Field Definitions](#field-definitions) section for details.
* `variations`
* **Required**: Yes
* **Description**: A map containing the specific UI configurations for one or more named deployments. See the [Deployments Map](#deployments-map-deployments) section for details.
* **Description**: A map containing the specific UI configurations for different strategy variations. See the [Variations Map](#variations-map) section for details.

## Deployments Map (`deployments`)
## Field Definitions

The `deployments` field under `gui` holds a map where each key is the name of a deployment (which must correspond to a deployment defined elsewhere in the configuration, e.g., under the top-level `deployments:` key) and the value is an object defining the GUI configuration specific to that deployment.
The `field-definitions` field under `gui` holds a map where each key is a field identifier and the value defines the complete UI configuration for that field. These definitions are referenced by variations to avoid duplication.

```yaml
gui:
# ... name, description ...
deployments:
<deployment-key-1>:
# ... configuration for deployment 1 ...
<deployment-key-2>:
# ... configuration for deployment 2 ...
# ... etc ...
field-definitions:
time-per-amount-epoch:
name: Budget period (in seconds)
description: The budget is spent over this time period
show-custom-field: true
default: 86400
presets:
- name: Per day (86400)
value: 86400
- name: Per week (604800)
value: 604800
validation:
type: number
minimum: 60
amount-per-epoch:
name: Budget (${order.outputs.0.token.symbol} per period)
description: The amount to spend each budget period
default: 0
validation:
type: number
minimum: 0
```

## Deployment Configuration (`<deployment-key>`)
### Field Definition Structure

Each field definition contains the complete configuration for a user-configurable input field. The field identifier (the key in the map) corresponds to the binding name in scenarios.

#### Fields

* `name`
* **Required**: Yes
* **Description**: The human-readable label displayed for this input field in the GUI. Can include template variables like `${order.outputs.0.token.symbol}`.
* `description`
* **Required**: No
* **Description**: An optional, longer description or help text displayed for this field, potentially as a tooltip or helper text.
* `presets`
* **Required**: No
* **Description**: An optional list of [Preset Items](#preset-item) containing predefined values the user can select for this field.
* `default`
Comment on lines +83 to +86
Copy link

@coderabbitai coderabbitai bot Sep 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue

Fix invalid link: “Preset Item” anchor doesn’t exist.

The link to [Preset Items](#preset-item) breaks (MD051). Either add a “Preset Item” section or simplify the reference.

Apply this diff:

-* `presets`
-  * **Required**: No
-  * **Description**: An optional list of [Preset Items](#preset-item) containing predefined values the user can select for this field.
+* `presets`
+  * **Required**: No
+  * **Description**: An optional list of preset values the user can select for this field.
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
* `presets`
* **Required**: No
* **Description**: An optional list of [Preset Items](#preset-item) containing predefined values the user can select for this field.
* `default`
* `presets`
* **Required**: No
* **Description**: An optional list of preset values the user can select for this field.
* `default`
🧰 Tools
🪛 LanguageTool

[grammar] ~84-~84: There might be a mistake here.
Context: ...r text. * presets * Required: No * Description: An optional list of [Pres...

(QB_NEW_EN)

[grammar] ~85-~85: Use correct spacing
Context: ...lues the user can select for this field. * default * Required: No * Description: An o...

(QB_NEW_EN_OTHER_ERROR_IDS_5)

🪛 markdownlint-cli2 (0.17.2)

85-85: Link fragments should be valid

(MD051, link-fragments)

🤖 Prompt for AI Agents 
In gui.md around lines 83 to 86, the link text “[Preset Items](#preset-item)”
points to a nonexistent anchor causing MD051; either add a matching "Preset
Item" (or "Preset Items") heading with the corresponding anchor elsewhere in the
document, or change the link to reference an existing heading (for example
adjust to `[Preset Items](#preset-items)` or remove the anchor and inline the
short description). Implement the chosen fix so the markdown link targets a
valid heading slug and update any heading text to match the link slug
casing/punctuation.

* **Required**: No
* **Description**: An optional default value to pre-populate the input field with.
* `validation`
* **Required**: No
* **Description**: An optional [Validation Object](#validation-object) defining validation rules for the field's value.
* `show-custom-field`
* **Required**: No
* **Description**: Controls whether the user is presented with a free-form input field in addition to any defined presets. When set to `false`, the user can only select from presets. Defaults to `true`.

Each entry within the `deployments` map defines the specific UI elements and text for a single deployment.
## Variations Map

The `variations` field under `gui` holds a map where each key is a variation identifier and the value defines the specific UI configuration for that variation of the strategy.

```yaml
gui:
# ...
deployments:
some-deployment: # This key must match a defined deployment
name: Buy WETH with USDC on Base.
description: Buy WETH with USDC for fixed price on Base network.
short-description: Buy WETH with USDC on Base.
deposits:
# ... deposit items ...
variations:
standard:
name: Standard DCA
description: Deploy a standard dollar-cost averaging order
fields:
# ... field items ...
- time-per-amount-epoch
- amount-per-epoch
deposits:
- token: output
select-tokens:
# ... select token items ...
- key: output
name: Token to Sell
- key: input
name: Token to Buy
networks:
Comment on lines +107 to +116
Copy link

@coderabbitai coderabbitai bot Sep 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue

Fix inverted input/output in DCA example (deposits and select-tokens).

In a DCA “Buy WETH with USDC” flow, users deposit the input token (USDC) and receive the output token (WETH). The example currently deposits output and labels output as “Token to Sell”.

Apply this diff:

       fields:
         - time-per-amount-epoch
         - amount-per-epoch
       deposits:
-        - token: output
+        - token: input
       select-tokens:
-        - key: output
-          name: Token to Sell
-        - key: input
-          name: Token to Buy
+        - key: input
+          name: Token to Sell
+        - key: output
+          name: Token to Buy

Also applies to: 109-116

🤖 Prompt for AI Agents 
In gui.md around lines 107-116 (also applies to 109-116): the DCA example has
input/output inverted — deposits use `output` and the select-tokens labels are
reversed. Change deposits to use token: input, and swap the select-tokens names
so that key: output is labeled "Token to Buy" and key: input is labeled "Token
to Sell" to reflect a "Buy WETH with USDC" flow.

42161: arbitrum
14: flare
special-variant:
name: Special Variant
description: A specialized version of the strategy
fields:
- time-per-amount-epoch
- special-field
deposits:
- token: special-token
networks:
14: special-deployment
```

### Fields
### Variation Configuration

Each variation defines which fields to show, which tokens can be deposited, and how it maps to different networks and deployments.

#### Fields

* `name`
* **Required**: Yes
* **Description**: The name of this specific deployment variation as it should appear in the GUI.
* **Description**: The name of this variation as it should appear in the GUI.
* `description`
* **Required**: Yes
* **Description**: A detailed description for this specific deployment variation.
* `short-description`
* **Required**: No
* **Description**: An optional, concise description for this deployment variation.
* `deposits`
* **Required**: Yes
* **Description**: A list of [Deposit Items](#deposit-item) that defines the tokens users can deposit into the strategy and provides UI hints like presets.
* **Description**: A detailed description for this specific variation.
* `fields`
* **Required**: Yes
* **Description**: A list of [Field Items](#field-item) that defines the user-configurable parameters (bindings) for the strategy, including labels, descriptions, presets, and defaults.
* **Description**: A list of field identifiers referencing entries in `field-definitions`. The order in the list determines the display order in the GUI.
* `deposits`
* **Required**: Yes
* **Description**: A list of [Deposit Items](#deposit-item) that defines the tokens users can deposit into the strategy.
* `select-tokens`
* **Required**: No
* **Description**: A list of [Select Token Items](#select-token-item) that defines specific tokens that might be selectable in other parts of the UI for this deployment (e.g., choosing an output token if the strategy supports it).
* **Description**: A list of [Select Token Items](#select-token-item) that defines tokens that need to be selected by the user. Only include tokens that require user selection; hardcoded tokens should be defined directly in the order.
* `networks`
* **Required**: Yes
* **Description**: A map where keys are chain IDs (as integers) and values are deployment identifiers (referencing keys in the top-level `deployments` map). This determines which deployment to use for each network when this variation is selected.

## Deposit Item

Each item in the `deposits` list defines a token that can be deposited and optional preset amounts for the UI.

```yaml
# Example within a deployment's deposits list:
deposits:
- token: token1 # Must match a defined token key
- token: output # References one of the order's inputs/outputs
presets:
- 0
- 10
Expand All @@ -118,94 +180,14 @@ deposits:

* `token`
* **Required**: Yes
* **Description**: The key referencing a token defined in the top-level `tokens` section. This specifies which token the deposit configuration applies to.
* **Description**: The key referencing a token. This corresponds to a token defined in the order's inputs/outputs.
* `presets`
* **Required**: No
* **Description**: An optional list of suggested deposit amounts to display as quick options in the UI. The UI will typically show these alongside the primary deposit input field.
* `validation`
* **Required**: No
* **Description**: An optional [Validation Object](#validation-object) defining validation rules for the deposit amount. For deposits, this will always use number validation rules. See the [Validation Object](#validation-object) section for details on available number validation fields like `minimum`, `exclusiveMinimum`, `maximum`, `exclusiveMaximum`, and `multipleOf`.

## Field Item

Each item in the `fields` list defines a user-configurable input field, mapping it to an underlying Rainlang binding.

```yaml
# Example within a deployment's fields list:
fields:
- binding: binding-1 # The corresponding binding in the Rainlang source
name: Price
description: The price for the order
presets:
# ... preset items for this field ...
default: 100.50
validation:
type: number
minimum: 0.01
multipleOf: 0.01
- binding: binding-2
name: Slippage Tolerance
description: Maximum allowed slippage in percentage
validation:
type: number
minimum: 0
maximum: 100
- binding: user-provided-note
name: Order Note
description: A custom note for the order
validation:
type: string
maxLength: 140
show-custom-field: true # Explicitly allow custom input
```

### Fields

* `binding`
* **Required**: Yes
* **Description**: The name of the binding in the associated Rainlang source code that this field provides the value for.
* `name`
* **Required**: Yes
* **Description**: The human-readable label displayed for this input field in the GUI.
* `description`
* **Required**: No
* **Description**: An optional, longer description or help text displayed for this field, potentially as a tooltip or helper text.
* `presets`
* **Required**: No
* **Description**: An optional list of [Preset Items](#preset-item) containing predefined values the user can select for this field.
* `default`
* **Required**: No
* **Description**: An optional default value to pre-populate the input field with.
* `validation`
* **Required**: No
* **Description**: An optional [Validation Object](#validation-object) defining validation rules for the field's value. This includes specifying the semantic type (e.g., "number", "string", "boolean") and type-specific rules like `minimum`/`exclusiveMinimum`/`maximum`/`exclusiveMaximum` for numbers, or `minLength`/`maxLength` for strings. See the [Validation Object](#validation-object) section for details.
* `show-custom-field`
* **Required**: No
* **Description**: Controls whether the user is presented with a free-form input field in addition to any defined presets. When set to a falsy value (e.g., `false`), the user might only be able to select from the presets. When set to a truthy value or omitted, a custom input field is typically shown.

## Preset Item

Each item in a field's `presets` list defines a single predefined option for that field.

```yaml
# Example within a field's presets list:
presets:
- name: Preset 1 Name # Optional name for the preset
value: 0x1234567890abcdef1234567890abcdef12345678
- value: false # Preset without an explicit name
- name: Preset 3 Name
value: some-string
```

### Fields

* `name`
* **Required**: No
* **Description**: An optional label for the preset option shown in the UI (e.g., in a dropdown or radio button list). If omitted, the `value` itself might be displayed.
* `value`
* **Required**: Yes
* **Description**: The actual value that will be used for the binding if this preset is selected.

## Select Token Item

Each item in the optional `select-tokens` list defines a token that might be presented for selection elsewhere in the UI for this deployment.
Expand Down
Loading