Contracts

What is a contract in Traverse?

A contract is a TOML file that defines everything about a capability. It is the single source of truth for that capability — not documentation, not a comment in code. The runtime reads the contract and enforces it at every boundary.

Here is a complete contract for a table-availability capability:

# table-availability.toml
[capability]
id      = "table-availability"
version = "1.2.0"

[execution]
binary_format     = "wasm"
entrypoint        = "check_availability"
preferred_targets = ["wasmtime"]

[constraints]
network_access    = false
filesystem_access = false

[inputs]
[[inputs.fields]]
name     = "date"
type     = "string"
required = true

[[inputs.fields]]
name     = "party_size"
type     = "integer"
required = true

[[inputs.fields]]
name     = "preferred_time"
type     = "string"
required = false

[outputs]
[[outputs.fields]]
name = "available"
type = "boolean"

[[outputs.fields]]
name = "slots"
type = "array"

[events.emits]
topics = ["availability.checked"]

[events.consumes]
topics = ["reservation.cancelled"]

What each section does

  • [capability] — the identity. The id is kebab-case and unique in the registry. The version is semver. Together they form the canonical address of this capability.
  • [execution] — how to run it. binary_format is always "wasm". entrypoint is the Rust function name. preferred_targets lists the WASM runtimes the capability is tested against.
  • [constraints] — what the sandbox allows. By default, no network access and no filesystem access. If a capability tries to reach the network without this set to true, the runtime refuses the call.
  • [inputs] — the input schema. Each field has a name, a type, and a required flag. The runtime validates every incoming call against this schema before execution starts.
  • [outputs] — the output schema. The runtime validates the WASM binary's return value against this schema after execution. Callers can trust the output shape without checking it themselves.
  • [events.emits] — topics this capability publishes to. Declared upfront, not discovered at runtime.
  • [events.consumes] — topics this capability listens on. Declared so the runtime can set up subscriptions correctly.

The contract is enforced, not documented

This is the key point. The contract is not a README. It is not a Swagger doc that might drift from the code. The runtime reads the contract and uses it as the validation spec for every call. Inputs that do not match the schema fail before the WASM binary loads. Outputs that do not match the schema fail after the binary returns.

If the contract says party_size is required and the caller omits it, the call fails immediately with a clear error. The capability code never runs. This makes the contract the enforcement point, not just the description.

You can read more about authoring contracts in the capability authoring guide.