sails-idl-client

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.