Skip to content

docs(node): warn QueryNodes truncates without next_key + add isActiveStatus helper#94

Open
Sentinel-Bluebuilder wants to merge 1 commit into
sentinel-official:developmentfrom
Sentinel-Bluebuilder:docs/chain-v3-quirks
Open

docs(node): warn QueryNodes truncates without next_key + add isActiveStatus helper#94
Sentinel-Bluebuilder wants to merge 1 commit into
sentinel-official:developmentfrom
Sentinel-Bluebuilder:docs/chain-v3-quirks

Conversation

@Sentinel-Bluebuilder

Copy link
Copy Markdown

Summary

Two chain v3 footguns that bite consumers on day 1. This PR addresses both with the smallest possible surface area: JSDoc warnings + one tiny exported helper.

1. QueryNodes / QueryNodesForPlan return next_key=null on truncation

Sentinel chain v3 does not emit pagination.next_key for these queries even when results are truncated. Consumers writing the obvious `while (next_key)` loop silently drop nodes.

Reproducible against mainnet:

```bash
curl 'https://lcd.sentinel.co/sentinel/node/v3/plans/36/nodes?pagination.limit=500'
| jq '{count: (.nodes | length), next: .pagination.next_key}'

=> { "count": 500, "next": null }

curl 'https://lcd.sentinel.co/sentinel/node/v3/plans/36/nodes?pagination.offset=500&pagination.limit=500'
| jq '.nodes | length'

=> 303 (so plan 36 actually has 803 nodes; the first call hid 303 of them)

```

The fix is pure JSDoc — direct callers to use a large `limit` or `offset`-based pagination instead of trusting `next_key`.

2. Status comes in three shapes — add an `isActiveStatus` helper

Subscription / session / node status is emitted as:

  • `"STATUS_ACTIVE"` in LCD JSON
  • numeric `1` over RPC
  • typed `Status.STATUS_ACTIVE` enum after ts-proto decode

Consumers who pick one shape and forget the others get silent zero results when their data source changes (e.g., switching from LCD to RPC). 10-line helper in `utils.ts`:

```ts
export function isActiveStatus(s: string | number | Status): boolean {
return s === Status.STATUS_ACTIVE || s === "STATUS_ACTIVE" || s === 1;
}
```

Strictly opt-in. No existing call site changes. `statusFromJSON` from the generated proto already handles the same conversion, but it lives in `protobuf/` and consumers don't typically reach there — this exposes the equivalent check from the public utils surface.

Test plan

  • `npx tsc --noEmit` passes
  • No runtime behavior change (JSDoc + new export only)
  • `isActiveStatus` returns true for all three shapes; false for inactive variants

…ctiveStatus helper

Two consumer footguns from chain v3 that bite on day 1:

1. `QueryNodes` and `QueryNodesForPlan` return `pagination.next_key=null`
   even when results are truncated. Consumers writing the obvious
   `while (next_key) { ... }` loop silently drop nodes. Add JSDoc
   warnings on the NodeExtension methods directing callers to use a
   large `limit` or `offset`-based pagination.

2. Subscription / session status comes back as the string
   `"STATUS_ACTIVE"` over LCD JSON, the numeric `1` over RPC, and the
   typed `Status.STATUS_ACTIVE` enum after ts-proto decode. Add an
   `isActiveStatus` helper in utils that accepts all three.

No behavior changes. JSDoc and one new exported helper.
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.

1 participant