Hartii developer docs

Agent Terminal

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:

  1. Target allowlist: the Hartii TokenFactory, a token's own registered bonding curve (verified live against TokenFactory.curveOf), the HartiiSwap router, WQUAI, and the Gallery NFT factory.
  2. Per-selector rules — approve is only allowed against a token this vault can actually trade (WQUAI, a Hartii launch token registered in TokenFactory, or a HartiiSwap LP pair), must carry value == 0, and its spender must be either the router or that token's own registered curve; transfer/transferFrom are always forbidden; router calls must pay address(this) (the vault); a router swap call (swapExactETHForTokens, swapExactTokensForETH, swapExactTokensForTokens) additionally has its path checked: 2–3 hops only, and every consecutive hop must have a real registered HartiiSwap pair (same factory.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, curve buy/sell/withdrawCreatorFees, WQUAI.deposit/withdraw, and deployCollection are allowed; anything else reverts selector.
  3. 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

FunctionEffect
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

solidity
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 balanceOf on 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

TierHBOME balance needed
0Below the minimum, or the registry is not active, or the account is excluded or a contract
1At least the minimum
2At least 2 times the minimum
3At least 5 times the minimum
4At 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 reach target QUAI, 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

solidity
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 owner

Also 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".

Quai Network mainnet · chain 9 · Cyprus-1. Figures marked "read on" a date were read from the chain that day; re-read before relying on them.