The bindings escape hatch

@aephia/sage/bindings re-exports the generated @staratlas/dev-sage client unchanged. It exists so that a missing feature in this SDK is an inconvenience rather than a wall.

This surface is deliberately not documented here

Everything under bindings is generated from the on-chain program by Codama and is owned upstream. Reproducing it here would add several thousand pages describing code this project does not maintain, and those pages would go stale the moment the bindings are regenerated. Read the @staratlas/dev-sage package for that surface.

This is the one public entry with a hand-written page instead of a generated one. Every other entry is documented from its source in the reference.

What you get

The full generated surface: account decoders, instruction builders, PDA helpers, and the types they use — roughly 48 account types and 239 instructions at the pinned version.

What you give up

Reaching into bindings steps outside every guarantee the rest of the SDK makes:

• No validation. The SDK checks program ownership, discriminators, data shape, and minimum length before decoding. Generated decoders do not, so a wrong or truncated account decodes into plausible nonsense instead of raising.
• No caching. Reads go straight to your RPC every time, with no shared snapshot and no provenance.
• No stable types. Generated types change when the bindings are regenerated for a new program version. The SDK’s own snapshot types are insulated from that; yours will not be.
• No read-only guarantee. The generated client includes instruction builders. This SDK never signs or submits, but nothing stops code written against bindings from doing so.

When to use it

When you need an account type or field the SDK has not adapted yet, and you would otherwise be blocked. That is the whole purpose, and using it for that is not a workaround — it is the designed path.

If you find yourself using it repeatedly for the same thing, that is a signal the SDK should adapt it properly. Open an issue describing the account and the read you need.

Why some accounts need discovery

Several SAGE account types have no derivable address — the Game account, crafting processes, claim stake instances, and loot among them. Their addresses are assigned at creation rather than computed from known inputs.

That is why some lookups need a known address, a scan, or an indexer, while others can be derived on the spot. It is a property of the game’s data model, not a gap in the SDK.