diff --git a/gui.md b/gui.md index 75b0892..71c05b7 100644 --- a/gui.md +++ b/gui.md @@ -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. ## 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: - : - # ... configuration for deployment 1 ... - : - # ... 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 (``) +### 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` + * **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: + 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 @@ -118,7 +180,7 @@ 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. @@ -126,86 +188,6 @@ deposits: * **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. diff --git a/ob-yaml.md b/ob-yaml.md index 9ce1565..2db87a5 100644 --- a/ob-yaml.md +++ b/ob-yaml.md @@ -4,7 +4,7 @@ - Avoid repetition - prefer named items (k/v sets) over unordered lists with inline ad hoc naming - can be referenced elsewhere unambiguously -- avoid needless depth in heirarchies +- avoid needless depth in hierarchies - prefer flat, except where it would imply excessive repetition - support multitudes of things - strict yaml for parsing, apply explicit schemas/types for non-strings @@ -53,7 +53,7 @@ https://besu.hyperledger.org/23.4.0/public-networks/concepts/network-and-chain-i ### Example -``` +```yaml networks: mainnet: rpcs: @@ -93,33 +93,51 @@ needed. ### Example -``` +```yaml using-networks-from: chainid: url: https://chainid.network/chains.json format: chainid ``` +## Network Values + +The `network-values` section provides network-specific values that can be referenced in scenarios (and in future potentially other parts of the yaml) using template syntax. This allows strategies to share scenario definitions while using different network-specific addresses or configuration values. + +Network values have no required structure - they are arbitrary key-value pairs that can be referenced via `${network-values.property}` syntax in scenario bindings. + +### Example + +```yaml +network-values: + arbitrum: + raindex-subparser: 0xe80e7438ce6b1055c8e9CDE1b6336a4F9D53C666 + subparser-0: 0xe80e7438ce6b1055c8e9CDE1b6336a4F9D53C666 + flare: + raindex-subparser: 0xFe2411CDa193D9E4e83A5c234C7Fd320101883aC + subparser-0: 0x915E36ef882941816356bC3718Df868054F868aD +``` + ## Subgraphs Currently subgraphs are 1:1 with orderbooks, but this could and probably should change in the future. It would be far better for downstream implementations if a single subgraph could handle _at least_ all bytecode identical orderbooks deployed to the same network, if not a set of known compatible bytecodes. For that reason, it might seem overkill to specify subgraphs separately but they should have a 1:many relationship with orderbooks in the mid term. Subgraphs have no fields, they're merely a name for a url string. -``` +```yaml subgraphs: polygon: https://... polygon2: https://... mainnet: https://... ``` -# Metaboards +## Metaboards Metaboard is an onchain contract for posting Rain meta about a subject (an address). This meta is indexed by a metaboard subgraph. Currently these are 1-1 with networks. Metaboards have no fields, they're merely a name for a url string. -``` +```yaml metaboards: polygon: https://... polygon2: https://... @@ -138,7 +156,7 @@ Optional fields: - `subgraph` (default is same as orderbook name) - `label` -``` +```yaml orderbooks: polygon: address: 0x... @@ -160,7 +178,7 @@ At the minimum a token is a network, address and decimals. While ERC20 doesn't m > **Note:** The top-level `tokens` field is optional and may be omitted if no tokens need to be predefined. Orders can reference tokens from other sources, including: > - `using-tokens-from` -> - the GUI’s `select-tokens` field under the top-level `gui` section +> - the GUI's `select-tokens` field under variations > > The top-level `tokens` mapping will be populated automatically by these sources when used. @@ -177,7 +195,7 @@ Optional fields: - `label` (fetch from contract, called `name` in the erc20 interface) - `symbol` (fetch from contract) -``` +```yaml tokens: eth-usdc: network: mainnet @@ -220,7 +238,7 @@ Optional fields: - `network` (assume deployer name if not set) - `label` -``` +```yaml deployers: mainnet: address: 0x... @@ -237,7 +255,7 @@ Accounts are optional filters that can be used to filter the orderbook to only s Account aliases are mapped to account addresses. -``` +```yaml accounts: my-account: 0x... my-other-account: 0x... @@ -250,7 +268,7 @@ The app will optionally collect analytics data to send to Sentry. This functiona Optional fields: - `sentry` (defaults to 'true') -``` +```yaml sentry: false ``` @@ -275,7 +293,7 @@ Optional fields: - `deployer` (defaults to network deployer if unambiguous, otherwise required) - `orderbook` (defaults to network orderbook if unambiguous, otherwise required) -``` +```yaml orders: dca-eth: inputs: @@ -303,12 +321,14 @@ orders: vault-id: 0xabcd ``` -### front matter scenarios +### Front matter scenarios Scenarios are a hierarchical structure that specifies bindings used by `dotrain` tooling to produce a concrete rainlang instance that can be parsed and deployed onchain, and deliberately introduces ambiguity to be iteratively disambiguated by a fuzzer, for the purpose of producing simulations. The bindings in yaml are forwarded as-is to `dotrain` as strings, so all forms are supported including quote bindings, etc. +Scenarios support template syntax for referencing network-specific values via `${network-values.property}` which will be resolved based on the network context when deploying. + All fields are optional, if there exists enough unambiguous deployment components all sharing the same name, e.g. `mainnet` and there are no elided bindings in the body of the .rain file (under the front matter) then a deployment is possible, as no bindings are required. If there is any ambiguity however, notably in the case of elided bindings, a binding set will need to be provided. @@ -370,7 +390,7 @@ scenarios: bing: ... ``` -### front matter charts +### Front matter charts Any scenario can be charted as every concrete set of bindings can be treated as a data point. For a single concrete set, a single data point is produced, for a @@ -489,15 +509,15 @@ charts: bin-width: 50 ``` -### front matter deployments +### Front matter deployments -Specifies deployments that consist of `scenario` in combination with an `order` mapped to a key: +Specifies deployments that consist of `scenario` in combination with an `order` mapped to a key. These deployment keys are referenced by GUI variations to determine which deployment to use for each network. Required deployment fields: - `scenario` name of a defined `scenario` - `order` name of a defined `order` -``` +```yaml deployments: first-deployment: scenario: scenario1 @@ -506,3 +526,34 @@ deployments: scenario: scenario2 order: order2 ``` + +## GUI Configuration + +See the separate [GUI Configuration](gui.md) documentation for details on the `gui` section. The GUI configuration in version 2 introduces: + +- `field-definitions`: Reusable field configurations that avoid duplication +- `variations`: Different strategy variations that map to deployments based on network + +Example structure: + +```yaml +gui: + name: Strategy Name + description: Strategy description + field-definitions: + field-1: + name: Field Name + description: Field description + default: 0 + variations: + standard: + name: Standard Variation + description: Description + fields: + - field-1 + deposits: + - token: output + networks: + 42161: arbitrum # Chain ID → deployment key + 14: flare +``` \ No newline at end of file