Simulation
Every proposed action is previewed before you can sign it - a fail-closed, advisory dry run that never authorizes anything by itself.
Before you're ever asked to sign anything, Botanary previews it. Simulation answers two questions at once: would your own rules or a delegation's policy allow this, and would the chain itself accept it right now.
What gets checked
A simulation runs two checks together:
- An advisory policy check - for something you're doing directly, your account's own rules; for a delegated action, that delegation's policy instead. A delegation ID that doesn't belong to your account resolves to nothing, so there's no way to preview against someone else's delegation.
- A real simulated call - for a send, this replays the exact calldata that would actually be submitted, not an approximation of it.
Both have to pass for the preview to say the action will succeed. When an on-chain simulator result is available, its verdict is preferred over the advisory check's - the closer answer wins.
Fail-closed, always
If the simulator can't be reached, or a policy check can't be completed, the preview reports failure. It never throws an error that could be swallowed, and it never quietly reports success when it isn't sure.
Simulation is advisory - it tells you what's expected to happen. It never authorizes anything by itself; the chain still re-asserts every bound at the actual enforcement point, in validation or in execution.
Scoped to what's actually being proposed
A delegated action's preview checks against that specific delegation's policy plus its live remaining spend, and its warning text says plainly that an out-of-scope call will be rejected by Smart Sessions in validation - the preview isn't guessing, it's describing what the chain will actually do. A preview for granting a delegation, changing your rules, or freezing your account doesn't have an "amount out" at all - there's nothing to convert, so it only answers whether the chain will accept the operation. A swap preview goes further once an operation is actually built: it replays the real batched call (the token approval and the router call together), not just the quote.
Delegation grants and mandate builds are always previewed automatically before you're asked to sign - a mandate's preview checks the actual executor call path, not just the underlying session being enabled. Every preview expires 60 seconds after it's generated.
Decline reasons, grouped by where they're enforced
A decline reason tells you which layer actually stopped the action, and each layer surfaces its own kind of reason:
| Layer | Example reasons | When it fires |
|---|---|---|
| Account rules (AgentGuard) | cap_exceeded, per_action_exceeded, recipient_not_allowed, contract_not_allowed, contract_denied, account_frozen | your own action, execution phase |
| Delegation policy (Smart Sessions) | policy_violation, delegation_revoked, no_policies_set | a delegated action, validation phase |
| Mandate policy (mandate executor) | mandate_revoked, venue_not_allowed, selector_not_allowed, arg_cap_exceeded, arg_not_allowed | a mandate action, execution phase |
| Build-time only | chain_capability_unavailable, route_unavailable | no on-chain revert involved at all |
Smart Sessions' own on-chain revert is generic - it doesn't identify which specific policy refused, only that one did. The informative version of a decline reason comes from the build-time simulation, not from the on-chain revert itself; the revert is what's binding, but it isn't where the specific reason comes from.
A Smart Sessions decline is dropped before the operation is ever included - there's no on-chain trace of it at all. A mandate decline, by contrast, reverts after inclusion: the operation lands on-chain, no funds move, and the attempt itself is now real, visible evidence.