Skip to content

docs(orderbook): add troubleshooting section #2475

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
dcatki2 wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs(orderbook): add troubleshooting section #2475

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
84 changes: 84 additions & 0 deletions packages/orderbook/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -736,6 +736,90 @@ if (result.error) {
console.log(result.value);
```

## Troubleshooting

### Subgraph query errors

**"error decoding response body"**

The subgraph returned malformed data. Common causes:
- Subgraph is syncing or temporarily unavailable
- Network connectivity issues
- Query timeout

Solutions:
1. Wait 30 seconds and retry
2. Check subgraph status at your provider's dashboard
3. Try a simpler query to isolate the issue

**Empty results when orders exist**

Subgraph indexing runs 1-3 blocks behind. After submitting a transaction, wait before querying:
```ts
// Poll for order after deployment
const order = await waitForOrderFromTx(client, { chainId, orderbookAddress, txHash });
```
Comment on lines +757 to +761
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai Bot Feb 21, 2026

Choose a reason for hiding this comment

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

⚠️ Potential issue | 🟡 Minor

Add blank lines around every fenced code block to fix MD031 linting errors.

markdownlint-cli2 flags five code fences that are not surrounded by blank lines (lines 758, 774, 784, 796, 808). All five need a blank line immediately before the opening ``` fence (the closing fence already has a trailing blank line in each case).

📝 Proposed fix — add the five missing blank lines 
 Subgraph indexing runs 1-3 blocks behind. After submitting a transaction, wait before querying:
+
 ```ts
 // Poll for order after deployment
 The SDK includes a Buffer polyfill, but some bundlers may need configuration:
+
 ```ts
 import { Buffer } from 'buffer';
 Add required metadata to your dotrain frontmatter:
+
 ```yaml
 deployments:
 The Rainlang references a binding not defined in `scenarios.bindings`:
+
 ```yaml
 scenarios:
 A numeric value cannot be precisely represented. Use `Float.parse()` for arbitrary precision:
+
 ```ts
 const amount = Float.parse('1000000000000000000');

Also applies to: 773-777, 783-791, 795-801, 807-811

🧰 Tools
🪛 markdownlint-cli2 (0.21.0)

[warning] 758-758: Fenced code blocks should be surrounded by blank lines

(MD031, blanks-around-fences)

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@packages/orderbook/README.md` around lines 757 - 761, MD031 lint errors come
from fenced code blocks that lack a blank line immediately before their opening
```; update the README.md to insert a single blank line before each affected
code fence referenced in the comment (the TypeScript block with the "Poll for
order after deployment" example used by waitForOrderFromTx, the TypeScript block
containing "import { Buffer } from 'buffer';", the YAML "deployments:" block,
the YAML "scenarios:" block, and the TypeScript block with "const amount =
Float.parse('1000000000000000000');") so each opening ``` has an empty line
above it, then re-run markdownlint to confirm MD031 is resolved.


### WASM initialization

**"Cannot read properties of undefined"**

The WASM module hasn't initialized. For ESM builds:
- Ensure your bundler supports top-level await
- Import the module before using exports

**"Buffer is not defined" (browser)**

The SDK includes a Buffer polyfill, but some bundlers may need configuration:
```ts
import { Buffer } from 'buffer';
globalThis.Buffer = Buffer;
```

### Dotrain parsing

**"deployment-block is required"**

Add required metadata to your dotrain frontmatter:
```yaml
deployments:
my-deployment:
order: my-order
scenario: default
deployment-block: 12345678
description: "My strategy"
```
Comment on lines +783 to +791
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai Bot Feb 21, 2026

Choose a reason for hiding this comment

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

⚠️ Potential issue | 🟡 Minor

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# First, let's explore the repository structure and locate the README file
git ls-files | grep -E "(README|orderbook)" | head -20

Repository: rainlanguage/rain.orderbook

Length of output: 936

🏁 Script executed:

#!/bin/bash
# Search for deployment-block references in the codebase to understand correct placement
rg -n "deployment.block" -C 2 | head -100

Repository: rainlanguage/rain.orderbook

Length of output: 6865

🏁 Script executed:

#!/bin/bash
# Search for deployment-block in YAML/config related files
rg -n "deployment-block" --type yaml --type rust --type ts -C 3 | head -150

Repository: rainlanguage/rain.orderbook

Length of output: 10499

🏁 Script executed:

#!/bin/bash
# Check if packages/orderbook/README.md exists and view the specific sections
if [ -f "packages/orderbook/README.md" ]; then
  echo "=== Lines 72-79 (FIXED_LIMIT_SOURCE example) ==="
  sed -n '72,79p' packages/orderbook/README.md
  echo ""
  echo "=== Lines 783-791 (troubleshooting section) ==="
  sed -n '783,791p' packages/orderbook/README.md
else
  echo "File not found"
fi

Repository: rainlanguage/rain.orderbook

Length of output: 541

🏁 Script executed:

#!/bin/bash
# Let's also search for examples with "deployments:" to understand the structure
rg -n "deployments:" packages/orderbook/README.md -A 5 -B 2 | head -50

Repository: rainlanguage/rain.orderbook

Length of output: 774

🏁 Script executed:

#!/bin/bash
# Let's check the context around the troubleshooting section to understand what it's documenting
sed -n '770,800p' packages/orderbook/README.md

Repository: rainlanguage/rain.orderbook

Length of output: 683

🏁 Script executed:

#!/bin/bash
# Let's verify the parser strictly requires deployment-block in orderbooks and rejects it elsewhere
rg -n "require_string.*deployment-block" -A 10 -B 5 crates/settings/src/orderbook.rs

Repository: rainlanguage/rain.orderbook

Length of output: 53

🏁 Script executed:

#!/bin/bash
# Let's check how the parser processes the dotrain frontmatter and deployment-block
rg -n "deployment.block" crates/settings/src/orderbook.rs -B 5 -A 5

Repository: rainlanguage/rain.orderbook

Length of output: 19256

🏁 Script executed:

#!/bin/bash
# Let's search for the error message "deployment-block is required" to understand the context
rg -n "deployment-block is required" -C 5

Repository: rainlanguage/rain.orderbook

Length of output: 614

🏁 Script executed:

#!/bin/bash
# Let's verify if there's any code that parses deployment-block from the deployments section
rg -n "deployments" crates/settings/src -A 5 -B 2 | grep -A 5 -B 2 "deployment"

Repository: rainlanguage/rain.orderbook

Length of output: 50383

🏁 Script executed:

#!/bin/bash
# Search for where "deployment-block is required" error is actually generated
rg -n "deployment.block is required" -C 10

Repository: rainlanguage/rain.orderbook

Length of output: 1208

🏁 Script executed:

#!/bin/bash
# Search for DeploymentCfg parsing to understand the dotrain section
rg -n "DeploymentCfg" crates/settings/src -A 3 -B 3 | head -150

Repository: rainlanguage/rain.orderbook

Length of output: 10590

🏁 Script executed:

#!/bin/bash
# Look at DeploymentCfg structure more carefully
cat crates/settings/src/deployment.rs | head -150

Repository: rainlanguage/rain.orderbook

Length of output: 5983

🏁 Script executed:

#!/bin/bash
# Check if deployment-block is mentioned in DeploymentCfg at all
rg -n "deployment.block" crates/settings/src/deployment.rs

Repository: rainlanguage/rain.orderbook

Length of output: 53

🏁 Script executed:

#!/bin/bash
# Let's verify once more by checking both the FIXED_LIMIT_SOURCE and troubleshooting sections side-by-side
echo "=== FIXED_LIMIT_SOURCE (lines 72-79) ==="
sed -n '72,79p' packages/orderbook/README.md
echo ""
echo "=== Troubleshooting section (lines 783-791) ==="
sed -n '783,791p' packages/orderbook/README.md
echo ""
echo "=== DeploymentCfg allowed keys ==="
rg "ALLOWED_DEPLOYMENT_KEYS" crates/settings/src/deployment.rs -A 1
echo ""
echo "=== OrderbookCfg allowed keys ==="
rg "ALLOWED_ORDERBOOK_KEYS" crates/settings/src/orderbook.rs -A 1

Repository: rainlanguage/rain.orderbook

Length of output: 1031

The troubleshooting snippet places deployment-block in the wrong YAML section.

The troubleshooting fix (lines 784–791) shows deployment-block under deployments:, but the parser only accepts it under orderbooks: as shown in the FIXED_LIMIT_SOURCE example (lines 72–79). The DeploymentCfg parser only allows "scenario" and "order" fields, while deployment-block is exclusive to OrderbookCfg. Following this guidance will not resolve the "deployment-block is required" error and will leave users confused.

Correct placement:

orderbooks:
  my-orderbook:
    deployment-block: 12345678
🧰 Tools
🪛 markdownlint-cli2 (0.21.0)

[warning] 784-784: Fenced code blocks should be surrounded by blank lines

(MD031, blanks-around-fences)

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@packages/orderbook/README.md` around lines 783 - 791, The README
troubleshooting snippet incorrectly places deployment-block under the
deployments section while the parser (DeploymentCfg) only accepts "scenario" and
"order"—deployment-block belongs to OrderbookCfg; update the example in the
README to move deployment-block under orderbooks (matching the
FIXED_LIMIT_SOURCE example) and adjust the YAML snippet and accompanying text to
show orderbooks: my-orderbook: deployment-block: 12345678 so users follow the
parser's expected structure.


**"Unknown binding"**

The Rainlang references a binding not defined in `scenarios.bindings`:
```yaml
scenarios:
default:
bindings:
my-binding: 0x1234...
```

### Float precision

**"LossyConversionToFloat"**

A numeric value cannot be precisely represented. Use `Float.parse()` for arbitrary precision:
```ts
const amount = Float.parse('1000000000000000000');
if (amount.error) throw new Error(amount.error.readableMsg);
```

### Transaction failures

**"execution reverted"**

Common causes:
- Insufficient token approval (call `vault.getApprovalCalldata()` first)
- Insufficient vault balance for withdrawals
- Order already removed
- Stale calldata (regenerate immediately before execution)

## Contributing

This SDK is part of the Rain Language ecosystem. For contributions and issues, please visit the [GitHub repository](https://github.com/rainlanguage/rain.orderbook).