gear-foundation/sails-architecture

Sails Architecture

Goal

Turn an approved spec into a Sails-specific architecture artifact before implementation starts.

If the work changes a released contract or introduces a new deployed contract version, the architecture note must also define compatibility expectations for public routes, replies, events, generated clients, and off-chain consumers such as frontend and indexer.

Inputs

• ../../assets/architecture-template.md
• ../../references/vara-domain-overview.md
• ../../references/sails-cheatsheet.md
• ../../references/gear-sails-production-patterns.md
• ../../references/sails-program-and-service-architecture.md
• ../../references/gear-messaging-and-replies.md
• ../../references/gear-gas-reservations-and-waitlist.md
• ../../references/awesome-sails-token-patterns.md
• ../../references/contract-interface-evolution.md
• ../../references/sails-header-wire-format.md — interface ID stability, entry ID derivation, route index

Write the result to docs/plans/YYYY-MM-DD-<topic>-architecture.md.

Execution Model Checks

• Model deferred work with delayed messages across future blocks, not off-chain cron as the default. A program can send a delayed message to itself or another actor when it must revisit state later.
• If the design depends on future execution budget, call out reserved gas or ReservationId usage and duration explicitly. Reservation keeps gas available for later sends, including delayed sends, but it is not free, permanent, or a value transfer.
• Treat the Waitlist as on-chain storage for messages awaiting processing or conditions, not as a normal mempool.
• Waitlisted messages incur rent or locked-fund costs over time, can expire at a maximum duration, and cannot be prolonged indefinitely.

Route Deeper When Needed

• If the architecture question is whether Gear or Sails exposes the right API family, review ../gear-gstd-api-map/SKILL.md first.
• If the architecture risk is mostly around replies, timeouts, delayed work, or reservations, review ../gear-message-execution/SKILL.md.
• If the architecture introduces a fungible token, token-backed accounting, or token-manager split, review ../../references/awesome-sails-token-patterns.md.
• If a service wraps a runtime builtin actor (staking broker, proxy broker, BLS helper, ETH bridge sender), review ../gear-builtin-actors/SKILL.md — state ownership, idempotency, and reply routing differ from program-to-program calls because the builtin has no memory or code.

Review Checklist

• Choose explicit service boundaries.
• Explain state ownership.
• Name the program constructor shape and the chosen storage pattern instead of implying them.
• Consider routing and events.
• If work is delayed, is it block-based and allowed to self-message later?
• If future automation matters, is reservation lifetime and gas budgeting explicit?
• If messages may sit in the Waitlist, does the design account for rent, expiry, and maximum duration?
• Are #[program] and #[service] boundaries explicit?
• Are routes, replies, and events stable enough for generated clients?
• If a delayed or self-call hits a Sails route, does the design keep generated clients or equivalent Sails Header-aware encoding in the contract?
• Does the design account for async Gear message flow and failure paths?
• If this changes a released contract, has the design classified the change as additive or breaking, and as interface-ID-preserving or interface-ID-breaking? (See ../../references/sails-header-wire-format.md for how interface IDs are derived.)
• Are all public methods annotated with #[export]?
• Are existing public routes, replies, and events preserved unless the architecture explicitly versions them?
• Does the note define contract version and status surface such as Active and ReadOnly when relevant?
• Does the design explain frontend and indexer impact for a new deployed contract version?
• If a cutover is required, does the note say how old and new versions coexist during rollout?
• If migration is required, does the note define export/import responsibilities instead of hiding them inside vague “upgrade” wording?

Released Contract Evolution Defaults

• If the work targets an already released contract, treat public routes, reply shapes, event payloads, and generated-client expectations as compatibility-sensitive surfaces.
• Prefer additive changes such as new routes, new services, or a new deployed contract version over mutating an existing public shape in place.
• If the user is preparing a new contract version, define how the old and new versions coexist during cutover.
• If the old version must stop accepting writes, make that lifecycle explicit in the architecture note.
• If state migration is required, define the split between V1, V2, and the off-chain migrator instead of implying an in-place code swap.

Future Migration Readiness

If the contract is expected to live beyond its first production release, the architecture note must describe how state could later be exported from V1.

At minimum:

• identify business-significant state stored in the program
• distinguish source-of-truth data from derived or rebuildable data
• describe whether future export would rely on full-state reads, selective state functions, or explicit export methods
• note any collections that will require deterministic chunking or canonical ordering
• state whether the contract may need a ReadOnly lifecycle mode in a future release

Guardrails

• If the spec is missing, stop and create it first.
• Prefer Sails service composition over ad hoc raw Gear layering.
• Treat generated clients as the default route contract for constructor and service calls.
• Do not assume delayed automation works without future gas availability.
• Do not treat Waitlist storage as free or indefinitely prolongable.
• Keep implementation detail out of the architecture note unless it changes the public contract.
• Do not change a released public route shape in place unless the architecture explicitly treats it as a breaking change.
• Do not change a released event payload in place without explicit versioning or cutover notes.
• Do not assume IDL regeneration alone makes a breaking interface change safe.
• Do not describe Gear/Sails evolution as an in-place hot swap of live contract code.