Sails IDL Client
Goal
Keep Sails builders on the typed pipeline for IDL generation, Rust client generation, and integration wiring.
If a released contract evolves or a new deployed contract version is introduced, keep the generated-client path compatible with the approved cutover plan instead of assuming one regenerated client can replace all consumers immediately.
Default JS Or TS Path
- Treat the program
.idl as the source of truth for the interface.
- Generate the normal client with
sails-js or sails-cli so the workspace gets lib.ts and typed program or service classes instead of hand-written payload code.
- Pair the generated client with
GearApi from @gear-js/api for node connectivity.
- Use
parseIdl from the sails-js and sails-js-parser path only when you explicitly need dynamic runtime control rather than pre-generated files.
Build Script Path
- Check the repo's
build.rs before inventing a manual IDL step.
- For a dedicated Rust client crate, prefer the standard Sails build-helper path:
[build-dependencies] sails-rs = { version = "...", features = ["build"] }
fn main() { sails_rs::build_client::<Program>(); }
- Treat direct
sails-idl-gen plus sails-client-gen-v2 wiring as a manual fallback for non-standard layouts or explicitly custom generation needs.
- Do not assume a single fixed output location. Depending on the repo, generated
.idl and Rust client artifacts may land in OUT_DIR, the client crate output path, or another repo-defined location.
Generated Client Pitfalls
- Custom
BTreeMap key types: Public IDL-facing map keys should prefer primitive or tuple types (e.g. u64, (u32, u32), ActorId). Custom struct keys (e.g. BTreeMap<Pos, V>) may fail client-side decoding because the generated type may lack the required ordered-key traits. Stick to primitives or tuples unless generated-client support for that custom key type is confirmed.
Released Contract Evolution
- Treat each
.idl as the interface contract for one deployed program version.
- If a new deployed contract version changes the public surface, do not assume every consumer can switch at once.
- Keep old and new generated clients available during cutover when frontend, tests, scripts, or migration tooling still depend on the previous version.
- Regenerate clients as part of release work, but do not treat regeneration alone as compatibility validation.
Frontend IDL Handoff
When a Sails program's IDL is consumed by a frontend in a separate workspace or repo:
- Check in an IDL snapshot in the frontend project so the frontend toolchain can build independently.
- Document the refresh command: after regenerating the IDL from the Rust workspace, copy it to the frontend snapshot location and regenerate the TypeScript client.
- If the IDL is only generated in
OUT_DIR during Rust builds, it will not be available to the frontend at build time.
See ../../references/sails-idl-client-pipeline.md for the canonical frontend export pattern.
Inputs
../../references/sails-idl-v2-syntax.md — IDL v2 grammar, annotations, types, service/program declarations
../../references/sails-header-wire-format.md — Sails Header layout, interface/entry ID derivation, wire examples
../../references/sails-cheatsheet.md
../../references/sails-idl-client-pipeline.md
../../assets/task-plan-template.md
../../references/contract-interface-evolution.md
Route Here When
- Check
build.rs or generation wiring when it no longer generates the expected artifacts
- the client crate drifted from program changes
- Check output paths and artifact freshness before deeper debugging
- tests are building raw payloads instead of using generated clients
- local smoke needs a typed client path
Guardrails
- Keep generated artifacts aligned with the program contract before deeper debugging.
- Prefer generated client flows in tests and smoke runs when the workspace supports them.
- Do not treat
sails-js as a runtime target; it is the JavaScript client library used by generated and dynamic IDL-driven flows.
- Do not replace the standard path with raw ABI, ethers-style bindings, or hand-written SCALE payloads for a standard Vara Sails app.
- Do not treat missing codegen as a reason to bypass the Sails pipeline.
- Do not document
sails-idl-gen + sails-client-gen-v2 as the default dedicated-client path when the repo can use sails-rs build helpers.
1---2name: sails-idl-client3description: Use when a builder needs to wire or repair the standard Gear/Vara Sails IDL and generated client pipeline in app, client, or test crates. Do not use for raw payload-only testing, Vara.eth or ethexe codegen, or non-Sails repositories.4metadata:5 source: https://skillmd.com/skills/gear-foundation/sails-idl-client6---78# Sails IDL Client910## Goal1112Keep Sails builders on the typed pipeline for IDL generation, Rust client generation, and integration wiring.1314If a released contract evolves or a new deployed contract version is introduced, keep the generated-client path compatible with the approved cutover plan instead of assuming one regenerated client can replace all consumers immediately.1516## Default JS Or TS Path1718- Treat the program `.idl` as the source of truth for the interface.19- Generate the normal client with `sails-js` or `sails-cli` so the workspace gets `lib.ts` and typed program or service classes instead of hand-written payload code.20- Pair the generated client with `GearApi` from `@gear-js/api` for node connectivity.21- Use `parseIdl` from the `sails-js` and `sails-js-parser` path only when you explicitly need dynamic runtime control rather than pre-generated files.2223## Build Script Path2425- Check the repo's `build.rs` before inventing a manual IDL step.26- For a dedicated Rust client crate, prefer the standard Sails build-helper path:27 - `[build-dependencies] sails-rs = { version = "...", features = ["build"] }`28 - `fn main() { sails_rs::build_client::<Program>(); }`29- Treat direct `sails-idl-gen` plus `sails-client-gen-v2` wiring as a manual fallback for non-standard layouts or explicitly custom generation needs.30- Do not assume a single fixed output location. Depending on the repo, generated `.idl` and Rust client artifacts may land in `OUT_DIR`, the client crate output path, or another repo-defined location.3132## Generated Client Pitfalls3334- **Custom `BTreeMap` key types**: Public IDL-facing map keys should prefer primitive or tuple types (e.g. `u64`, `(u32, u32)`, `ActorId`). Custom struct keys (e.g. `BTreeMap<Pos, V>`) may fail client-side decoding because the generated type may lack the required ordered-key traits. Stick to primitives or tuples unless generated-client support for that custom key type is confirmed.3536## Released Contract Evolution3738- Treat each `.idl` as the interface contract for one deployed program version.39- If a new deployed contract version changes the public surface, do not assume every consumer can switch at once.40- Keep old and new generated clients available during cutover when frontend, tests, scripts, or migration tooling still depend on the previous version.41- Regenerate clients as part of release work, but do not treat regeneration alone as compatibility validation.4243## Frontend IDL Handoff4445When a Sails program's IDL is consumed by a frontend in a separate workspace or repo:4647- Check in an IDL snapshot in the frontend project so the frontend toolchain can build independently.48- Document the refresh command: after regenerating the IDL from the Rust workspace, copy it to the frontend snapshot location and regenerate the TypeScript client.49- If the IDL is only generated in `OUT_DIR` during Rust builds, it will not be available to the frontend at build time.5051See `../../references/sails-idl-client-pipeline.md` for the canonical frontend export pattern.5253## Inputs5455- `../../references/sails-idl-v2-syntax.md` — IDL v2 grammar, annotations, types, service/program declarations56- `../../references/sails-header-wire-format.md` — Sails Header layout, interface/entry ID derivation, wire examples57- `../../references/sails-cheatsheet.md`58- `../../references/sails-idl-client-pipeline.md`59- `../../assets/task-plan-template.md`60- `../../references/contract-interface-evolution.md`6162## Route Here When6364- Check `build.rs` or generation wiring when it no longer generates the expected artifacts65- the client crate drifted from program changes66- Check output paths and artifact freshness before deeper debugging67- tests are building raw payloads instead of using generated clients68- local smoke needs a typed client path6970## Guardrails7172- Keep generated artifacts aligned with the program contract before deeper debugging.73- Prefer generated client flows in tests and smoke runs when the workspace supports them.74- Do not treat `sails-js` as a runtime target; it is the JavaScript client library used by generated and dynamic IDL-driven flows.75- Do not replace the standard path with raw ABI, ethers-style bindings, or hand-written SCALE payloads for a standard Vara Sails app.76- Do not treat missing codegen as a reason to bypass the Sails pipeline.77- Do not document `sails-idl-gen` + `sails-client-gen-v2` as the default dedicated-client path when the repo can use `sails-rs` build helpers.