gear-gstd-api-map
Gear gstd API Map
Goal
Keep design work API-first: start from gstd, then drop to gcore or gsys only when you need to confirm limits, gas shape, or low-level behavior.
Inputs
../../references/gear-execution-model.md— execution model and block lifecycle../../references/gear-messaging-and-replies.md— message flow and reply semantics../../references/gear-gas-reservations-and-waitlist.md— gas reservations and waitlist../../references/gear-gstd-api-and-syscalls.md— full API surface and syscall mapping
Route Here When
- a spec or architecture note needs to know whether a Gear program can send, await replies, self-schedule, reserve gas, or create child programs
- a builder is choosing between typed payloads, raw bytes, staged push-plus-commit, or input-forwarding APIs
- a design depends on
#[gstd::async_main],_for_replyflows, delayed work,ReservationId, orprog::* - a debugging pass needs to confirm which
gr_*syscall family a high-level API actually reaches
Working Model
- Start from builder intent, not from raw syscalls.
- Choose the
gstdfamily:msg,exec,prog, reservations, or async helpers. - Prefer the highest-level API that preserves the contract: typed send and reply first, bytes only for intentional raw payload paths or codec debugging.
- Check design constraints: block-delayed execution, reply deposit, reservation lifetime, waitlist exposure, gas budget, and route-prefix stability for Sails clients.
- Drop to
gcoreto confirm wrapper behavior and togsysonly when you need exact syscall names, fallibility, or control-vs-get distinctions.
API Quick Reference
| Module | Key APIs | When to Use |
|---|---|---|
msg |
send, reply, send_delayed, send_for_reply, send_bytes, push-plus-commit |
Sending messages, replying, delayed dispatch, awaiting replies |
exec |
gas_available, block_height, wait, wait_for, wake, reply_deposit, exit |
Reading execution context, parking in waitlist, waking actors |
prog |
create_program, create_program_bytes, create-for-reply |
Creating child programs with optional delay and gas limits |
| reservations | ReservationId::reserve, .unreserve, reservation pools |
Future-block work that must keep a gas budget alive |
Guardrails
- Prefer
gstdas the default public API for standard Gear/Vara builders. - Treat raw
gsys::gr_*names as confirmation tools, not the first design vocabulary. - Keep design notes phrased in message flow, replies, blocks, and contracts, not in syscall sequences.
- If a Sails route depends on generated clients, preserve that route contract even for delayed or self-messaging paths.
- Stop if the task is really about runtime benchmarking, syscall-maintenance coverage, or ethexe-only behavior.
More from gear-foundation/vara-skills
vara-skills
Use when a builder needs the top-level router for the provisional standard Gear/Vara Sails skill pack across Codex, Claude, or OpenClaw. Do not use for Vara.eth or ethexe work, non-Sails programs, or broad protocol research.
197sails-new-app
Use when a builder is starting a new standard Gear/Vara Sails app and needs the correct greenfield sequence before implementation. Do not use for edits to an established repo, Vara.eth or ethexe targets, or non-Sails templates.
2sails-dev-env
Use when a builder needs to prepare or repair a local macOS, Linux, or Windows machine for standard Gear/Vara Sails Rust development before building, testing, or running a local node. Do not use for live-network deployment, app-specific feature work, or Vara.eth/ethexe-only setup.
2vara-wallet
Use when an agent needs to interact with Vara Network on-chain — deploy programs, call Sails methods, manage wallets, transfer tokens, monitor events. Not for building Sails programs (use vara-skills for that).
2sails-gtest
Use when a builder needs the standard Gear/Vara Sails gtest loop for feature verification, debugging, or regression coverage. Do not use for live-network-only validation, deployment-first workflows, or non-Sails programs.
2task-decomposer
Use when approved spec and architecture artifacts must become an ordered implementation plan for Gear or Vara work. Do not use when the architecture is still unsettled or when the request is only asking for a high-level idea.
2