contracts WIT interface and imports only the host capabilities it needs.
Key concepts and tips before starting:
Repository structure
wit/deps/ define the host ABI your contract links against. They’re vendored from the Trinity release the public testnet runs (testnet-v1.0.12): host:interfaces@2.4.0 and host:tenant@2.0.0.
The three functions
Files
world.wit — declare your interface + host imports
tenant-base world: who is calling, logging, and your own maps. With no http import, nothing this contract holds can be sent anywhere — the host refuses to load a contract that imports an interface its world doesn’t provide.
Cargo.toml — compile to a WASM component
The customer record
examples/customer.json is what store accepts — a fictional customer with the fields a bank keeps for KYC and lending decisions:
logic.rs deserialises this into a CustomerRecord with deny_unknown_fields, then checks dates, country codes and currency. Validation errors name the field, never the value.
lib.rs — dispatch each function
crate::host::* and the exported interface under crate::exports::* — both generated by the macro from wit/. In the repository this sits inside a #[cfg(target_arch = "wasm32")] module, so cargo test can run the logic natively.
Who is calling: tenant-context
Three accessors decide everything about access:
So the vault keys every record by
hex(calling_user_did). store and forget refuse when is_delegated() is true, and check reads only the record of calling_user_did. Which functions an agent may call at all is decided by the customer’s grant before your code runs — the contract’s own checks are a second line.
logic.rs — the yes/no rules
check takes { "rules": { … } } and answers only the rules present:
“Today” is
cluster_timestamp_secs(), the cluster’s agreed time, so every node gives the same answer. The response is one boolean per rule asked:
Key design rules
- Export functions on the
contractsinterface. Each takesgeneric-inputand returnsresult<list<u8>, string>— JSON bytes on success, an error string on failure. There is nodispatchfunction and noContractErrorenum. kv-storecalls take the fullz:<tid>:<map>name. Build it at runtime by hex-encodingtenant_context::tenant_did(), which returns raw bytes. The map must exist before the contract reads or writes it — you create it in Step 3.- Key a customer’s data by
calling_user_did(), never by a DID taken from the input, so an agent can only ever reach the customer who granted it. - Return answers, not values, and never put a value in a log line, an error or a
customlabel. - Import only the host interfaces you use — they are your contract’s entire capability set.
Going further
When your contract needs to reach the outside world, it moves to a world with HTTP:- Outbound HTTP is authorized by the user, not the contract
- Seed an API key into the secrets map
- Placeholders in outbound calls — send a customer’s details to an API without your contract ever holding them
- Flight Booking — a complete contract that does all three, on top of this setup