AgentVault contract reference
Roles
- Owner — the wallet that created the vault (
AgentVaultFactory.createVault's caller). Full control, never capped:ownerExecute,withdraw,withdrawToken,withdrawNFT,setAgent,setCaps,pause/unpause,revoke. - Agent — a key set by the owner. May only call
execute(target, value, data), and only within the allowlist and caps below.
execute(address target, uint256 value, bytes data)
Agent-only, reverts while paused. Checks, in order:
- Target allowlist: the Hartii
TokenFactory, a token's own registered bonding curve (verified live againstTokenFactory.curveOf), the HartiiSwap router,WQUAI, and the Gallery NFT factory. - Per-selector rules —
approveis only allowed against a token this vault can actually trade (WQUAI, a Hartii launch token registered inTokenFactory, or a HartiiSwap LP pair), must carryvalue == 0, and its spender must be either the router or that token's own registered curve;transfer/transferFromare always forbidden; router calls must payaddress(this)(the vault); a router swap call (swapExactETHForTokens,swapExactTokensForETH,swapExactTokensForTokens) additionally has itspathchecked: 2–3 hops only, and every consecutive hop must have a real registered HartiiSwap pair (samefactory.getPair(...)lookup the approvable-token check uses) — anything longer or routed through a non-existent pair reverts before the router is even called;TokenFactory.launch, curvebuy/sell/withdrawCreatorFees,WQUAI.deposit/withdraw, anddeployCollectionare allowed; anything else revertsselector. - Caps —
value(native QUAI sent) must be ≤maxPerTx, and the sum over the last 24 hourly buckets must be ≤maxPerDay. The buckets are clock hours, so this is not a strictly rolling 24-hour window. Only native QUAI value is metered: tokens and WQUAI held in the vault are not covered by the caps (see Security).
Emits AgentAction(address indexed target, bytes4 indexed selector, uint256 value).
Owner functions
| Function | Effect |
|---|---|
setAgent(address) | Replace the agent key. |
setCaps(uint256 maxPerTx, uint256 maxPerDay) | maxPerTx must be ≤ maxPerDay; both must be > 0 while an agent is set. |
pause() / unpause() | Agent calls revert while paused. |
revoke() | Clears the agent and pauses in one call. |
withdraw(address to, uint256 amount) | QUAI. |
withdrawToken(address token, address to, uint256 amount) | Any ERC-20. |
withdrawNFT(address collection, address to, uint256 id) | Any ERC-721. |
ownerExecute(address target, uint256 value, bytes data) | Unrestricted — the owner's own escape hatch. |
Revert reasons
not agent, paused, target, selector, recipient, spender, value, per-tx cap,
daily cap, transfer forbidden, caps, not owner, initialized, reentrant, path (a
router swap's path was not 2–3 hops), hop (a router swap path had a hop with no real HartiiSwap
pair).
AgentVaultFactory
function createVault(address agent, uint256 maxPerTx, uint256 maxPerDay) external payable returns (address vault);
function vaultsOf(address owner) external view returns (address[] memory);
event VaultCreated(address indexed vault, address indexed owner, address indexed agent);The target allowlist (TokenFactory, HartiiSwap router, WQUAI, the Gallery NFT factory) is fixed
in the factory's constructor at deploy time and is the same for every vault it creates.
HartiiBiomeAccess (proposed, not deployed)
It is the on-chain record of the smallest HBOME balance that counts as a Member, and of which feature needs which
tier. The hosted parts of the personal holder trader are meant to read it. HBOME is
0x001fA4fdb848BB8C98B0d6Cd85257EfcCAe3b425.
What it does and does not do
- It holds nothing. It has no payable function, no transfer, no approval and no withdrawal. It only reads
balanceOfon HBOME. - It counts ordinary wallets only. A contract account always has tier 0. A contract that is still being built has no code yet, so this check alone is not proof of an ordinary wallet. The hosted service also checks a signed message.
- Some addresses always have tier 0: the zero address, the registry, HBOME, the owner, and up to 64 more set at deployment. The owner can change the extra exclusions at any time. The first four cannot be removed.
- It has no proxy and no upgrade path. Ownership moves in two steps.
Tiers
| Tier | HBOME balance needed |
|---|---|
| 0 | Below the minimum, or the registry is not active, or the account is excluded or a contract |
| 1 | At least the minimum |
| 2 | At least 2 times the minimum |
| 3 | At least 5 times the minimum |
| 4 | At least 10 times the minimum |
The minimum
- Activation. Only the owner can activate, once. It cannot happen until 7 days after the launch time given at deployment. The owner posts 24 hourly samples: a price, a timestamp, a block number and a block hash. They must fall in consecutive hours with rising block numbers, and the newest must be no more than 2 hours old. The reference price is the median of the 24 prices. A price is QUAI wei for one whole HBOME.
- Formula.
calculateMinimum(price, target)is the number of whole HBOME needed to reachtargetQUAI, rounded up, then held between 500,000 and 25,000,000 HBOME. The target must be between 100 and 5,000 QUAI. It is 500 QUAI at activation. - Changes. The owner proposes a new minimum with a price and a target, and it must equal what the formula
gives. A raise can be at most double and takes effect after 7 days. A cut can be to at most half (rounded up) and
takes effect after 1 day. Only one change can wait at a time. Anyone can run
executeMinimum()once the delay ends. The owner can cancel.
Features
The owner sets the tier a feature needs, from 1 to 4. Raising a tier waits 7 days. Lowering one waits 1 day. Anyone
can run executeFeature once the delay ends. A feature id is a bytes32. The personal holder trader uses
keccak256("trader"), which is 0x500a689e179661a7c8788772b2798c2bceebb5bf88f74cc1a3de6caaa68b0944.
hasAccess(account, feature) is true only when the feature has a tier and the account's tier meets it.
Interface
constructor(address token, address owner, uint256 launchTime, address[] memory excluded);
uint256 public constant FLOOR = 500_000 ether;
uint256 public constant CEILING = 25_000_000 ether;
uint256 public constant INCREASE_DELAY = 7 days;
uint256 public constant DECREASE_DELAY = 1 days;
// reads
function active() external view returns (bool);
function minimum() external view returns (uint256);
function referencePrice() external view returns (uint256);
function targetQuai() external view returns (uint256);
function tierOf(address account) external view returns (uint8); // 0 to 4
function hasAccess(address account, bytes32 feature) external view returns (bool);
function featureTier(bytes32 feature) external view returns (uint8);
function calculateMinimum(uint256 price, uint256 target) external pure returns (uint256);
// writes
struct Sample { uint256 price; uint256 timestamp; uint256 blockNumber; bytes32 blockHash; }
function activate(Sample[24] calldata samples) external; // owner
function proposeMinimum(uint256 next, uint256 price, uint256 target) external; // owner
function executeMinimum() external; // anyone, after the delay
function cancelMinimum() external; // owner
function proposeFeature(bytes32 feature, uint8 tier) external; // owner
function executeFeature(bytes32 feature) external; // anyone, after the delay
function cancelFeature(bytes32 feature) external; // owner
function setExcluded(address account, bool value) external; // owner
function transferOwnership(address next) external; // owner
function acceptOwnership() external; // pending ownerAlso public: token, launchTime, owner, pendingOwner, excluded(address), pendingMinimum() and
pendingFeatures(feature).
Events: ReferenceSample, Activated, MinimumProposed, MinimumChanged, MinimumCancelled,
FeatureProposed, FeatureSet, FeatureCancelled, ExcludedSet, OwnershipTransferStarted and
OwnershipTransferred.
Revert reasons: owner, token, owner address, launch time, exclusion count, price, target, active,
activation time, sample, sample block, sample hour, sample order, stale samples, inactive, pending,
peg, unchanged, increase bound, decrease bound, delay, feature, permanent exclusion, pending owner.
What you would have to trust
- Prices are owner attestations, not an oracle. The contract checks order, hourly spacing, the median and the bounds. It cannot prove that the prices are true or final. The deployment scripts say so, and they require independent verification of every sample.
- One owner key. The owner can change exclusions at once and controls every proposal until ownership moves. A multisig is a deployment condition that is still open. It does not exist today.
- Rehearsal. An Orchard rehearsal of the full lifecycle, with real elapsed time, is open.
- Deployment. The deployment script only prepares an unsigned transaction. It loads no key and sends nothing. The Orchard rehearsal script is read-only. On mainnet the script requires the canonical HBOME token and the HBOME curve in the exclusion list.
Until a registry is deployed and wired in, the public read GET /api/hbome/tier?address=<owner wallet address>
answers HTTP 503 with configured: false and reason: "registry-not-configured".