Contracts — API Reference

Public Interface

1. initialize(env: Env, admin: Address, agent_pubkey: BytesN<32>)

Initializes the custom account contract once. Registers the admin address and the agent's Ed25519 public key.

2. set_policy(env: Env, policy: GuardPolicy)

Installs or updates the spending policy. Admin-authorized.

pub struct GuardPolicy {
    pub per_tx_cap: Option<i128>,
    pub window_cap: Option<i128>,
    pub window_duration_secs: Option<u64>,
    pub recipients: Vec<Address>,
    pub allow_any_recipient: bool,
    pub protocols: Vec<ProtocolRule>,
    pub active_window: Option<TimeWindow>,
    pub paused: bool,
    pub dms_grace_secs: Option<u64>,
}

3. revoke_policy(env: Env)

Removes policy. Reverts contract to default-deny state. Admin-authorized.

4. freeze(env: Env)

Panic button: immediately sets admin_frozen = true. Admin-authorized.

5. unfreeze(env: Env)

Clears admin_frozen and resets the dead-man switch heartbeat clock. Admin-authorized.

6. heartbeat(env: Env)

Liveness signal from agent. Agent-authorized self-call (require_auth). Updates last_heartbeat = now.

7. rotate_agent_key(env: Env, new_agent_pubkey: BytesN<32>)

Rotates the registered agent Ed25519 public key. Admin-authorized.

8. status(env: Env) -> AccountStatus

Read-only view query returning current initialization, admin freeze, and dead-man state.

---

Contract Error Codes

Code	Symbol	Meaning
1	AlreadyInitialized	initialize() called more than once
2	NotInitialized	Contract function invoked before initialization
3	AdminFrozen	Transaction blocked by admin panic-button freeze
4	HeartbeatExpired	Dead-man switch grace period lapsed
5	Paused	Admin pause switch active
6	OutsideActiveWindow	Current timestamp outside configured active window
7	NoPolicy	Default-deny: no policy installed
8	PerTxCapExceeded	Transfer amount exceeds per_tx_cap
9	WindowCapExceeded	Transfer amount exceeds rolling window cap
10	RecipientNotAllowed	Recipient address not in allowlist
11	UnknownContract	Protocol contract ID not in allowlist
12	FunctionNotAllowed	Contract function name not in allowlist