Skip to content

feat: template fallback operator ${expr || 'default'}#2551

Open
hardyjosh wants to merge 1 commit into
list-tokensfrom
template-fallback
Open

feat: template fallback operator ${expr || 'default'}#2551
hardyjosh wants to merge 1 commit into
list-tokensfrom
template-fallback

Conversation

@hardyjosh
Copy link
Copy Markdown
Contributor

@hardyjosh hardyjosh commented Apr 15, 2026

Motivation

Strategy field names and descriptions in .rain YAML reference token properties via templates like \${order.inputs.0.token.symbol} per \${order.outputs.0.token.symbol}. The webapp resolves these at runtime once tokens have been selected. Any other consumer (notably --describe) that renders these strings before a token is picked sees the raw placeholder, which is confusing.

Dropping the placeholder in un-selected contexts would lose the structural information. Hard-coding a substitution in every consumer is brittle and doesn't match webapp semantics.

Solution

Extend the template syntax with an optional fallback literal:

${path}                    — current behaviour
${path || 'fallback'}      — substitute literal when the path resolves to a missing token
${path || "fallback"}      — double quotes also accepted

The fallback only kicks in on PropertyNotFound("token") (i.e. select-token not yet selected). Other resolution errors still propagate. Templates without || behave identically to today — backwards compatible.

The webapp gets no regression: when tokens are selected the left-hand side always resolves and the fallback never fires. --describe (and any other "no context" consumer) gets readable output for free once registry strategies adopt fallbacks.

Registry adoption is tracked in ST0x-Technology/st0x.registry#9.

Checks

  • made this PR as small as possible
  • unit-tested any new functionality
  • linked any relevant issues or PRs
  • included screenshots (if this involves a front-end change)

Copy link
Copy Markdown
Contributor Author

hardyjosh commented Apr 15, 2026

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more


How to use the Graphite Merge Queue

Add the label Raindex-queue to this PR to add it to the merge queue.

You must have a Graphite account in order to use the merge queue. Sign up using this link.

An organization admin has enabled the Graphite Merge Queue in this repository.

Please do not merge from GitHub as this will restart CI on PRs being processed by the merge queue.

This stack of pull requests is managed by Graphite. Learn more about stacking.

@coderabbitai
Copy link
Copy Markdown
Contributor

coderabbitai Bot commented Apr 15, 2026

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: d35525ea-9610-401a-91c5-8e903eeb1864

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

  • 🔍 Trigger review
✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch template-fallback

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

@hardyjosh hardyjosh changed the base branch from list-tokens to graphite-base/2551 April 15, 2026 12:55
@hardyjosh hardyjosh force-pushed the graphite-base/2551 branch from 38992d1 to 129f279 Compare April 15, 2026 13:04
@hardyjosh hardyjosh changed the base branch from graphite-base/2551 to list-tokens April 15, 2026 13:04
@hardyjosh
Copy link
Copy Markdown
Contributor Author

@coderabbitai review

@coderabbitai
Copy link
Copy Markdown
Contributor

coderabbitai Bot commented Apr 15, 2026

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

@hardyjosh
Copy link
Copy Markdown
Contributor Author

@coderabbitai review

@coderabbitai
Copy link
Copy Markdown
Contributor

coderabbitai Bot commented Apr 15, 2026

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

Copy link
Copy Markdown
Contributor Author

hardyjosh commented May 11, 2026

Merge activity

graphite-app Bot pushed a commit that referenced this pull request May 11, 2026
## Motivation

The Raindex orderbook protocol has a rich GUI builder flow in the webapp for configuring and deploying strategies. There is currently no way to do the same from a terminal or from a non-interactive agent — the webapp is the only entry point. That forces anyone automating a deployment (CI, scripts, AI agents) to either drive the browser or hand-roll the calldata.

## Solution

Add a `strategy-builder` subcommand to the raindex CLI that generates deployment calldata from a remote registry strategy.

```
raindex strategy-builder \
  --registry <url> \
  --strategy <key> \
  --deployment <key> \
  --owner <0x-address> \
  [--select-token KEY=ADDRESS ...] \
  [--set-field BINDING=VALUE ...] \
  [--set-deposit TOKEN=AMOUNT ...]
```

Outputs one `<address>:<calldata>` line per transaction on stdout — approvals first, then the deployment multicall, then optional metaboard meta emission. Each line is one signable transaction.

Implementation reuses `RaindexOrderBuilder` from the common crate (same object the webapp drives) and `DotrainRegistry` from the js_api crate, so the CLI and webapp use identical resolution semantics.

Follow-up PRs in this stack add `--interactive` (#2546), `--tokens` (#2549), the template-fallback operator (#2551), and `--describe` (#2548).

## Checks

- [x] made this PR as small as possible
- [x] unit-tested any new functionality
- [x] linked any relevant issues or PRs
- [ ] included screenshots (if this involves a front-end change)

<!-- This is an auto-generated comment: release notes by coderabbit.ai -->

## Summary by CodeRabbit

* **New Features**
  * Added a new `strategy-builder` command that generates deployment calldata from registry strategies with configurable field bindings, token selections, and deposit amounts.

* **Improvements**
  * Token logo URIs are now optional, improving compatibility with token data sources.

<!-- end of auto-generated comment: release notes by coderabbit.ai -->
graphite-app Bot pushed a commit that referenced this pull request May 11, 2026
## Motivation

Strategy field names and descriptions in `.rain` YAML reference token properties via templates like `\${order.inputs.0.token.symbol} per \${order.outputs.0.token.symbol}`. The webapp resolves these at runtime once tokens have been selected. Any other consumer (notably `--describe`) that renders these strings before a token is picked sees the raw placeholder, which is confusing.

Dropping the placeholder in un-selected contexts would lose the structural information. Hard-coding a substitution in every consumer is brittle and doesn't match webapp semantics.

## Solution

Extend the template syntax with an optional fallback literal:

```
${path}                    — current behaviour
${path || 'fallback'}      — substitute literal when the path resolves to a missing token
${path || "fallback"}      — double quotes also accepted
```

The fallback only kicks in on `PropertyNotFound("token")` (i.e. select-token not yet selected). Other resolution errors still propagate. Templates without `||` behave identically to today — backwards compatible.

The webapp gets no regression: when tokens are selected the left-hand side always resolves and the fallback never fires. `--describe` (and any other "no context" consumer) gets readable output for free once registry strategies adopt fallbacks.

Registry adoption is tracked in ST0x-Technology/st0x.registry#9.

## Checks

- [x] made this PR as small as possible
- [x] unit-tested any new functionality
- [x] linked any relevant issues or PRs
- [ ] included screenshots (if this involves a front-end change)
@graphite-app graphite-app Bot force-pushed the template-fallback branch from b205a51 to 3065b16 Compare May 11, 2026 10:05
graphite-app Bot pushed a commit that referenced this pull request May 11, 2026
> [!CAUTION]
>
> The registry-side companion work that uses the template-fallback operator (#2551) to produce readable `--describe` output for existing strategies is in ST0x-Technology/st0x.registry#9 — describe works fine without it, but strategy field names will contain raw `${...}` placeholders until that PR lands.

## Motivation

CLI users and AI agents need a way to learn a registry's full configuration without reading the underlying `.rain` YAML files or running the interactive wizard. That discovery loop is currently: `curl` the registry file → resolve the settings URL → `curl` each strategy → parse the YAML by hand. Every agent we tested (6/6) burned 4+ tool calls just discovering token addresses.

## Solution

Add `--describe` — emits a full markdown dump of the registry: every strategy, its deployments, required/optional fields (with presets and defaults), select-tokens, deposits, plus usage documentation and the `address:calldata` output format.

Intended as a self-generating skill. An agent can run once against a registry and have everything it needs to construct non-interactive deploy commands from a natural-language request. Each deployment includes an **Example command** with the exact flags and placeholders pre-filled.

Also bundled in this PR (small polish items):

- Each field tagged `(required)` or `(optional, default: X)` so it is obvious which flags are mandatory
- `strategy-builder` stdout lines are now labelled with `#` comment headers describing what each transaction does (approve / deploy / meta emission). Safe for `cast send` pipelines (with a one-line skip) and for `stox submit` (updated in ST0x-Technology/st0x.liquidity#578)
- Usage section documents the `#` comment convention, the `--tokens` companion, the cast-send pipe idiom (with comment-skip), the units convention (human-readable decimal), and the build-once guidance for running the binary directly without `nix develop` noise

## Checks

- [x] made this PR as small as possible
- [x] unit-tested any new functionality
- [x] linked any relevant issues or PRs
- [ ] included screenshots (if this involves a front-end change)

<!-- This is an auto-generated comment: release notes by coderabbit.ai -->

## Summary by CodeRabbit

* **New Features**
  * Added `strategy-builder` CLI command with interactive, describe, and tokens modes for deploying order strategies from registry configurations.

* **Bug Fixes**
  * Made token `logoURI` field optional in remote token configurations.

* **Documentation**
  * Updated YAML configuration: replaced `gui:` sections with `builder:` throughout codebase.
  * Renamed public APIs from GUI-centric to builder-centric terminology across CLI, SDK, and UI components.

<!-- end of auto-generated comment: release notes by coderabbit.ai -->
graphite-app Bot pushed a commit that referenced this pull request May 11, 2026
## Motivation

The Raindex orderbook protocol has a rich GUI builder flow in the webapp for configuring and deploying strategies. There is currently no way to do the same from a terminal or from a non-interactive agent — the webapp is the only entry point. That forces anyone automating a deployment (CI, scripts, AI agents) to either drive the browser or hand-roll the calldata.

## Solution

Add a `strategy-builder` subcommand to the raindex CLI that generates deployment calldata from a remote registry strategy.

```
raindex strategy-builder \
  --registry <url> \
  --strategy <key> \
  --deployment <key> \
  --owner <0x-address> \
  [--select-token KEY=ADDRESS ...] \
  [--set-field BINDING=VALUE ...] \
  [--set-deposit TOKEN=AMOUNT ...]
```

Outputs one `<address>:<calldata>` line per transaction on stdout — approvals first, then the deployment multicall, then optional metaboard meta emission. Each line is one signable transaction.

Implementation reuses `RaindexOrderBuilder` from the common crate (same object the webapp drives) and `DotrainRegistry` from the js_api crate, so the CLI and webapp use identical resolution semantics.

Follow-up PRs in this stack add `--interactive` (#2546), `--tokens` (#2549), the template-fallback operator (#2551), and `--describe` (#2548).

## Checks

- [x] made this PR as small as possible
- [x] unit-tested any new functionality
- [x] linked any relevant issues or PRs
- [ ] included screenshots (if this involves a front-end change)

<!-- This is an auto-generated comment: release notes by coderabbit.ai -->

## Summary by CodeRabbit

* **New Features**
  * Added a new `strategy-builder` command that generates deployment calldata from registry strategies with configurable field bindings, token selections, and deposit amounts.

* **Improvements**
  * Token logo URIs are now optional, improving compatibility with token data sources.

<!-- end of auto-generated comment: release notes by coderabbit.ai -->
graphite-app Bot pushed a commit that referenced this pull request May 11, 2026
## Motivation

Strategy field names and descriptions in `.rain` YAML reference token properties via templates like `\${order.inputs.0.token.symbol} per \${order.outputs.0.token.symbol}`. The webapp resolves these at runtime once tokens have been selected. Any other consumer (notably `--describe`) that renders these strings before a token is picked sees the raw placeholder, which is confusing.

Dropping the placeholder in un-selected contexts would lose the structural information. Hard-coding a substitution in every consumer is brittle and doesn't match webapp semantics.

## Solution

Extend the template syntax with an optional fallback literal:

```
${path}                    — current behaviour
${path || 'fallback'}      — substitute literal when the path resolves to a missing token
${path || "fallback"}      — double quotes also accepted
```

The fallback only kicks in on `PropertyNotFound("token")` (i.e. select-token not yet selected). Other resolution errors still propagate. Templates without `||` behave identically to today — backwards compatible.

The webapp gets no regression: when tokens are selected the left-hand side always resolves and the fallback never fires. `--describe` (and any other "no context" consumer) gets readable output for free once registry strategies adopt fallbacks.

Registry adoption is tracked in ST0x-Technology/st0x.registry#9.

## Checks

- [x] made this PR as small as possible
- [x] unit-tested any new functionality
- [x] linked any relevant issues or PRs
- [ ] included screenshots (if this involves a front-end change)
@graphite-app graphite-app Bot force-pushed the template-fallback branch from 3065b16 to 9e4531a Compare May 11, 2026 12:29
graphite-app Bot pushed a commit that referenced this pull request May 11, 2026
> [!CAUTION]
>
> The registry-side companion work that uses the template-fallback operator (#2551) to produce readable `--describe` output for existing strategies is in ST0x-Technology/st0x.registry#9 — describe works fine without it, but strategy field names will contain raw `${...}` placeholders until that PR lands.

## Motivation

CLI users and AI agents need a way to learn a registry's full configuration without reading the underlying `.rain` YAML files or running the interactive wizard. That discovery loop is currently: `curl` the registry file → resolve the settings URL → `curl` each strategy → parse the YAML by hand. Every agent we tested (6/6) burned 4+ tool calls just discovering token addresses.

## Solution

Add `--describe` — emits a full markdown dump of the registry: every strategy, its deployments, required/optional fields (with presets and defaults), select-tokens, deposits, plus usage documentation and the `address:calldata` output format.

Intended as a self-generating skill. An agent can run once against a registry and have everything it needs to construct non-interactive deploy commands from a natural-language request. Each deployment includes an **Example command** with the exact flags and placeholders pre-filled.

Also bundled in this PR (small polish items):

- Each field tagged `(required)` or `(optional, default: X)` so it is obvious which flags are mandatory
- `strategy-builder` stdout lines are now labelled with `#` comment headers describing what each transaction does (approve / deploy / meta emission). Safe for `cast send` pipelines (with a one-line skip) and for `stox submit` (updated in ST0x-Technology/st0x.liquidity#578)
- Usage section documents the `#` comment convention, the `--tokens` companion, the cast-send pipe idiom (with comment-skip), the units convention (human-readable decimal), and the build-once guidance for running the binary directly without `nix develop` noise

## Checks

- [x] made this PR as small as possible
- [x] unit-tested any new functionality
- [x] linked any relevant issues or PRs
- [ ] included screenshots (if this involves a front-end change)

<!-- This is an auto-generated comment: release notes by coderabbit.ai -->

## Summary by CodeRabbit

* **New Features**
  * Added `strategy-builder` CLI command with interactive, describe, and tokens modes for deploying order strategies from registry configurations.

* **Bug Fixes**
  * Made token `logoURI` field optional in remote token configurations.

* **Documentation**
  * Updated YAML configuration: replaced `gui:` sections with `builder:` throughout codebase.
  * Renamed public APIs from GUI-centric to builder-centric terminology across CLI, SDK, and UI components.

<!-- end of auto-generated comment: release notes by coderabbit.ai -->
## Motivation

Strategy field names and descriptions in `.rain` YAML reference token properties via templates like `\${order.inputs.0.token.symbol} per \${order.outputs.0.token.symbol}`. The webapp resolves these at runtime once tokens have been selected. Any other consumer (notably `--describe`) that renders these strings before a token is picked sees the raw placeholder, which is confusing.

Dropping the placeholder in un-selected contexts would lose the structural information. Hard-coding a substitution in every consumer is brittle and doesn't match webapp semantics.

## Solution

Extend the template syntax with an optional fallback literal:

```
${path}                    — current behaviour
${path || 'fallback'}      — substitute literal when the path resolves to a missing token
${path || "fallback"}      — double quotes also accepted
```

The fallback only kicks in on `PropertyNotFound("token")` (i.e. select-token not yet selected). Other resolution errors still propagate. Templates without `||` behave identically to today — backwards compatible.

The webapp gets no regression: when tokens are selected the left-hand side always resolves and the fallback never fires. `--describe` (and any other "no context" consumer) gets readable output for free once registry strategies adopt fallbacks.

Registry adoption is tracked in ST0x-Technology/st0x.registry#9.

## Checks

- [x] made this PR as small as possible
- [x] unit-tested any new functionality
- [x] linked any relevant issues or PRs
- [ ] included screenshots (if this involves a front-end change)
graphite-app Bot pushed a commit that referenced this pull request May 11, 2026
## Motivation

The Raindex orderbook protocol has a rich GUI builder flow in the webapp for configuring and deploying strategies. There is currently no way to do the same from a terminal or from a non-interactive agent — the webapp is the only entry point. That forces anyone automating a deployment (CI, scripts, AI agents) to either drive the browser or hand-roll the calldata.

## Solution

Add a `strategy-builder` subcommand to the raindex CLI that generates deployment calldata from a remote registry strategy.

```
raindex strategy-builder \
  --registry <url> \
  --strategy <key> \
  --deployment <key> \
  --owner <0x-address> \
  [--select-token KEY=ADDRESS ...] \
  [--set-field BINDING=VALUE ...] \
  [--set-deposit TOKEN=AMOUNT ...]
```

Outputs one `<address>:<calldata>` line per transaction on stdout — approvals first, then the deployment multicall, then optional metaboard meta emission. Each line is one signable transaction.

Implementation reuses `RaindexOrderBuilder` from the common crate (same object the webapp drives) and `DotrainRegistry` from the js_api crate, so the CLI and webapp use identical resolution semantics.

Follow-up PRs in this stack add `--interactive` (#2546), `--tokens` (#2549), the template-fallback operator (#2551), and `--describe` (#2548).

## Checks

- [x] made this PR as small as possible
- [x] unit-tested any new functionality
- [x] linked any relevant issues or PRs
- [ ] included screenshots (if this involves a front-end change)

<!-- This is an auto-generated comment: release notes by coderabbit.ai -->
## Summary by CodeRabbit

* **New Features**
  * Added `strategy-builder` command to the CLI for generating deployment calldata from registry-based strategies. The command accepts required parameters for registry URL, strategy identifier, deployment address, and owner. Users can further customize strategy deployments with repeatable options to set field bindings, select tokens, and configure deposit amounts, enabling streamlined deployment workflows.

[![Review Change Stack](https://storage.googleapis.com/coderabbit_public_assets/review-stack-in-coderabbit-ui.svg)](https://app.coderabbit.ai/change-stack/rainlanguage/raindex/pull/2544)
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
@graphite-app graphite-app Bot force-pushed the template-fallback branch from 9e4531a to d8d142d Compare May 11, 2026 12:33
graphite-app Bot pushed a commit that referenced this pull request May 11, 2026
> [!CAUTION]
>
> The registry-side companion work that uses the template-fallback operator (#2551) to produce readable `--describe` output for existing strategies is in ST0x-Technology/st0x.registry#9 — describe works fine without it, but strategy field names will contain raw `${...}` placeholders until that PR lands.

## Motivation

CLI users and AI agents need a way to learn a registry's full configuration without reading the underlying `.rain` YAML files or running the interactive wizard. That discovery loop is currently: `curl` the registry file → resolve the settings URL → `curl` each strategy → parse the YAML by hand. Every agent we tested (6/6) burned 4+ tool calls just discovering token addresses.

## Solution

Add `--describe` — emits a full markdown dump of the registry: every strategy, its deployments, required/optional fields (with presets and defaults), select-tokens, deposits, plus usage documentation and the `address:calldata` output format.

Intended as a self-generating skill. An agent can run once against a registry and have everything it needs to construct non-interactive deploy commands from a natural-language request. Each deployment includes an **Example command** with the exact flags and placeholders pre-filled.

Also bundled in this PR (small polish items):

- Each field tagged `(required)` or `(optional, default: X)` so it is obvious which flags are mandatory
- `strategy-builder` stdout lines are now labelled with `#` comment headers describing what each transaction does (approve / deploy / meta emission). Safe for `cast send` pipelines (with a one-line skip) and for `stox submit` (updated in ST0x-Technology/st0x.liquidity#578)
- Usage section documents the `#` comment convention, the `--tokens` companion, the cast-send pipe idiom (with comment-skip), the units convention (human-readable decimal), and the build-once guidance for running the binary directly without `nix develop` noise

## Checks

- [x] made this PR as small as possible
- [x] unit-tested any new functionality
- [x] linked any relevant issues or PRs
- [ ] included screenshots (if this involves a front-end change)

<!-- This is an auto-generated comment: release notes by coderabbit.ai -->

## Summary by CodeRabbit

* **New Features**
  * Added `strategy-builder` CLI command with interactive, describe, and tokens modes for deploying order strategies from registry configurations.

* **Bug Fixes**
  * Made token `logoURI` field optional in remote token configurations.

* **Documentation**
  * Updated YAML configuration: replaced `gui:` sections with `builder:` throughout codebase.
  * Renamed public APIs from GUI-centric to builder-centric terminology across CLI, SDK, and UI components.

<!-- end of auto-generated comment: release notes by coderabbit.ai -->
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants