Agent Vault Contract API
Overview of functions and security model of the AgentVault contract.
This page explains the on-chain functions a vault owner can call directly, plus the VaultOperator execution model used for agent-driven swaps.
VaultOperator Context
VaultOperator is an execution role in Authority used to submit swap transactions generated from agent decisions. The operator exists because agent logic is off-chain, while swaps must be executed by an on-chain caller.
In AgentVault, operator authority is intentionally narrow:
- Can call
swapV4(...)to execute Uniswap v4 swaps. - Can call
finalizeVaultClosure()only after owner has initiated closure. - Cannot call owner fund-management functions.
- Cannot withdraw ETH/WETH/tokens to itself.
- Cannot call
xcall(...). - Cannot change settings, strategies, or ownership.
Least-Privilege Security Model
Swaps are constrained on-chain by contract checks:
swapV4is gated byonlyVaultOperator.- Vault owner can pause swaps at any time with
pauseVault(true). - Protocol can globally disable operators via
Authority.vaultOperatorsDisabled. - Swaps are blocked once the experiment is completed (
ExperimentCompletedrevert). - Pair must include WETH.
- Non-WETH side must be a token registered in
Authority(protocol-registered token set). - Minimum output (
minAmountOut) is enforced. - Swap settlement returns output to the same vault (
address(this)), not an arbitrary recipient.
Owner-Callable Functions
| Function | Signature | Purpose | Key Requirements |
|---|---|---|---|
| Update settings | updateSettings((uint256, uint256, uint8, uint8, uint8, uint8, uint8) settings_) | Update agent risk/trading preferences | Owner only; validated bounds |
| Add strategy | addStrategy(string strategy, uint64 expiry, uint8 prio) returns (uint256) | Add strategy metadata | Owner only; non-empty; max length; valid expiry/priority |
| Disable strategy | disableStrategy(uint256 id) | Disable one strategy | Owner only |
| Disable all strategies | disableAllActiveStrategies() | Disable all active strategies | Owner only |
| Deposit ETH | depositETH() payable | Wrap ETH into vault WETH | Owner only; msg.value > 0 |
| Withdraw ETH | withdrawETH(uint256 amount_) | Unwrap WETH and withdraw ETH | Owner only; sufficient WETH |
| Recover forced ETH | recoverEth(uint256 amount_) | Withdraw raw ETH held by vault | Owner only; sufficient ETH balance |
| Enter presale | enterPresale(uint256 presaleId, uint256 amount) | Contribute vault WETH to presale | Owner only; sufficient WETH |
| Swap staked NFT | shmewieSwap(uint256 newAgentId_) | Replace staked Agent NFT | Owner only; new id must differ |
| Pause/unpause swaps | pauseVault(bool paused_) returns (bool) | Enable/disable operator swap execution | Owner only; vault not in closure |
| Initiate closure | closeVault() | Start closure workflow | Owner only; vault not in active presale |
| Close after experiment | closeVaultAfterExperiment() | Owner-complete closure after graduation | Owner only; experiment complete |
| Withdraw graduated token | withdrawGraduatedToken() | Transfer graduated token balance to owner | Owner only; graduated token set |
| Arbitrary call (post-experiment) | xcall(address target_, bytes data_) payable returns (bytes) | Owner-directed integrations after experiment | Owner only; experiment completed |
Read Functions
vaultOwner()agentId()paused()vaultClosureStep()(0=active,1=closure initiated,2=closure finalized)agentSettings()strategyCount()isStrategyActive(uint256)getStrategy(uint256)getActiveStrategies()getActiveStrategyIds()AGENT(),AUTHORITY(),PRESALE(),WETH(),POOL_MANAGER()
Settings and Strategies
Agent Settings
updateSettings(AgentSettings settings_) validates all fields on-chain:
| Field | Type | Allowed Range | Notes |
|---|---|---|---|
maxTradeAmount | uint256 | 500 to 10_000 | BPS (5% to 100%) |
slippageBps | uint256 | 10 to 5_000 | BPS (0.10% to 50%) |
tradingActivity | uint8 | 1 to 5 | slider value |
assetRiskPreference | uint8 | 1 to 5 | slider value |
tradeSize | uint8 | 1 to 5 | slider value |
holdingStyle | uint8 | 1 to 5 | slider value |
diversification | uint8 | 1 to 5 | slider value |
Strategy Constraints
addStrategy(string strategy, uint64 expiry, uint8 prio) rules:
- Strategy text must be non-empty.
- Max strategy length is
1024bytes. expirymust be0(no expiry) or a future unix timestamp.- Priority enum values:
0 = Low1 = Med2 = High- Maximum active strategies at once:
8.
Active strategy definition:
enabled == true- and (
expiry == 0orexpiry > block.timestamp)
When adding a strategy at the active limit, the vault attempts to prune expired active strategies first; if still full, the call reverts.