Notes for AI agents

This page is not a tutorial. Launch from TypeScript is the tutorial, and everything here assumes you have read it.

This page is about where you will be confidently wrong.

DAO Ships runs on Quai Network, which is sharded, and reads through an indexer, which is a cache. Both break assumptions carried over from single-shard EVM chains and from direct eth_call reads. Most of those breakages do not raise. They return a plausible value, and the code carries on.

The ordering is deliberate: worst-first by how silently it fails, not by topic. A loud error you will diagnose in minutes. A silent one you will ship.

1. Silent failures

A receipt with status: 1 does not mean the proposal's action ran

This is the single most expensive assumption you can make.

processProposal can complete successfully — status-1 receipt, no revert, gas spent — in three materially different states. Only one of them is what you want.

event ProcessProposal(uint256 proposal, bool passed, bool actionFailed, address processor);

Assert on the event, not on the receipt:

const receipt = await tx.wait();
if (receipt.status !== 1) throw new Error("reverted");
 
const log = receipt.logs
  .map((l) => { try { return daoShip.interface.parseLog(l); } catch { return null; } })
  .find((l) => l?.name === "ProcessProposal");
 
if (!log) throw new Error("no ProcessProposal event");
if (!log.args.passed) throw new Error("proposal did not pass (retention veto?)");
if (log.args.actionFailed) throw new Error("proposal passed but the action reverted");

The retention veto kills proposals that won their vote

DAOShip re-checks token supply at process time. If members ragequit during the grace period and supply falls below a floor set during voting, the proposal is defeated no matter how the vote went:

if (passed && minRetentionPercent > 0) {
    uint256 retentionRequired =
        (prop.maxTotalSharesAndLootAtVote * minRetentionPercent) / BASIS_POINTS_DIVISOR;
    if (sharesToken.totalSupply() + lootToken.totalSupply() < retentionRequired) {
        passed = false;
    }
}

Two details make this worse than it looks:

• The denominator is different from quorum's. Quorum measures against maxTotalSharesAtSponsor — shares only, snapshotted at sponsorship. Retention measures against maxTotalSharesAndLootAtVote — shares and loot, a high-water mark that rises during voting. A predictor that reuses the quorum snapshot for retention will be wrong.
• It is terminal. STATUS_PROCESSED is set before the veto is evaluated, and processProposal reverts with AlreadyProcessed() on a second call. The proposal can never be re-processed. Afterwards state() returns Defeated.

state() does not tell you whether the action executed

state() is authoritative for lifecycle position, and you should trust it over any cached status. But a proposal whose action reverted still has STATUS_PASSED set, so:

state(id) == Processed   // even when actionFailed == true

There is no ActionFailed value in the on-chain enum. The indexer has an action failed status; the contract does not. For execution outcome, read the flags:

function getProposalStatus(uint32 id) external view returns (bool[4] memory);
// [0] cancelled  [1] processed  [2] passed  [3] actionFailed

Large numbers from the indexer silently become zero

PostgREST serialises NUMERIC columns as bare JSON numbers. JSON.parse turns them into doubles. A 1000-share balance is 1e21, well past Number.MAX_SAFE_INTEGER, so it both loses precision and re-serialises as the string "1e+21" — which BigInt() then rejects. The balance reads as 0, and a proposal gets built against a treasury you think is empty.

Cast large numerics to text in the request:

const res = await fetch(
  `${SUPABASE_URL}/rest/v1/ds_daos?select=id,shares_total_supply::text&id=eq.${daoId}`,
  { headers: { apikey: KEY, "Accept-Profile": "mainnet" } },
);

If you cannot control every select, pre-process the raw response body before parsing it — quote integer literals that cannot round-trip through a double, leaving everything else byte-identical. Do not JSON.parse first; by then the damage is done.

A duration string that fails to parse becomes "use the default"

0 is the contract's USE-DEFAULT sentinel for expiration windows, not "expires immediately". Any client-side parse that yields null-then-zero silently substitutes the DAO default, and the transaction succeeds with a window nobody asked for. Validate that your parse produced a number before sending it, and treat 0 as an explicit, deliberate choice.

The same shape bites on token amounts: "1,000" throws inside BigInt, and "0.0000000000000000001" truncates to 0n — which will happily mint a founding member zero shares.

List reads are a bounded window, not a complete set

PostgREST returns a capped page. Past that cap rows do not paginate — as far as your query is concerned, they do not exist. A DAO's 201st proposal is not on page 2; it is gone, with no indicator that anything was dropped.

Walk pages explicitly with Range headers (or .range() in the JS client) until the source is exhausted, and track whether you hit your own ceiling so you can say so rather than presenting a partial list as complete.

Partial metadata updates erase the fields you omit

Profile and navigator metadata are posted as whole documents via Poster, not merged field by field. Posting a dao.profile record containing only name wipes the banner, icon, and theme. Omitting a navigator from a dao.navigators post de-sanctions it. Always read the current document, modify it, and post the whole thing back.

2. Things that are true of the environment, not the contracts

None of this is discoverable from Solidity, because none of it is a property of the contracts.

Sign with quais, and only quais

Quai transactions are protobuf-serialised. ethers and viem cannot produce a valid one, and there is no adapter. This is not a convenience preference — a transaction signed by either library is malformed on the wire.

The shard path in the RPC URL is mandatory

https://rpc.quai.network/cyprus1          ✅  Quai mainnet, chain ID 9
https://orchard.rpc.quai.network/cyprus1  ✅  Orchard testnet, chain ID 15000
https://rpc.quai.network                  ❌  404

Addresses must be EIP-55 checksummed

The quai_* RPC namespace rejects non-checksummed input outright with address has invalid checksum. Indexer rows are stored lowercase. quais.Contract and AbiCoder normalise for you, but raw provider methods do not — so any path that goes indexer row → getCode / call / getBalance needs quais.getAddress(x) first.

getBlock('latest') fails without shard context

A shardless provider.getBlock('latest') is rejected with Invalid shard. Where you need a timepoint, derive it from local clock time and pad for skew — biasing in whichever direction is conservative for your call. For getPriorVotes, that means further into the past:

// getPriorVotes needs a timepoint strictly in the past. The 60s buffer absorbs clock
// skew and keeps this a conservative lower bound — it under-counts at worst.
const timepoint = BigInt(Math.floor(Date.now() / 1000) - 60);

getCode through a wallet provider can lie

quais.BrowserProvider.getCode() silently returns '0x' for every lookup against Pelagus on Quai testnets — reporting that correctly deployed contracts do not exist. If you are behind an EIP-1193 wallet rather than a direct provider, call the RPC method yourself:

const code = await rawProvider.request({ method: "quai_getCode", params: [addr, "latest"] });

Gas estimation is unreliable in two specific ways

processProposal estimates low, because estimation follows the try/catch failure path rather than the inner delegatecall chain — budget roughly +50%. And Pelagus wraps all estimateGas failures as code 4001 ("user rejected") with the revert data stripped, so a failed estimate tells you nothing about why. Do not treat an estimation failure as proof the transaction is invalid.

One address in the system belongs to nobody here

The QuaiVault singleton is deployed by the Quai Vault project, appears in no DAO Ships repository, and can change without a commit anywhere in this org. Read it from QuaiVaultFactory.implementation() rather than caching it.

3. Getting an address to work at all

Generate a Cyprus-1 key with the HD wallet, not from random bytes:

import { quais } from "quais";
 
const wallet = quais.QuaiHDWallet.createRandom();
const account = await wallet.getNextAddress(0, quais.Zone.Cyprus1);

A random 32-byte private key produces a Cyprus-1 address roughly 0.2% of the time. Naive key generation appears to work in testing — you will get an address, it will be well-formed, and every transaction from it will fail.

A usable signer satisfies both quais.isQuaiAddress(addr) and zone 0x00. Assert it once at startup rather than discovering it at the first write.

4. Contract addresses: hardcode two, derive the rest

Do not maintain a table of nine addresses. From DAOShipAndVaultLauncher you can reach seven of the remaining eight on-chain:

DAOShipAndVaultLauncher (published)
├── .daoShipLauncher()    → DAOShipLauncher
│     ├── .daoShipSingleton() → DAOShipSingleton
│     ├── .sharesSingleton()  → SharesERC20Singleton
│     └── .lootSingleton()    → LootERC20Singleton
├── .multisendCallOnly()  → MultiSendCallOnly
└── .quaiVaultFactory()   → QuaiVaultFactory
      └── .implementation()   → QuaiVault singleton

Only Poster is unreachable — it is standalone infrastructure with no back-reference — so it is the second address you hardcode. Current values for both networks are in Contracts & addresses, which is canonical.

5. Ways to be wrong loudly

These raise. They are here because the error message points somewhere unhelpful.

hashOperation has an extra encode layer

keccak256(abi.encode(_transactions))   // ✅ what the contract does
keccak256(_transactions)               // ❌ the obvious guess

Get it wrong and processProposal reverts with HashMismatch — which, because Pelagus strips custom-error data during estimation, most commonly surfaces to you as "missing revert data". That message means "your call reverted and we could not decode why", not "the node is broken".

processProposal needs different data per outcome

if (currentState == ProposalState.Defeated) {
    if (proposalData.length > 0) revert HashMismatch();   // must be empty
} else {
    if (keccak256(abi.encode(proposalData)) != prop.proposalDataHash) revert HashMismatch();
}

A passing proposal needs the original action bytes. A defeated one must be closed with empty 0x. Both are legitimate calls; picking the wrong branch reverts identically. Call state(id) immediately beforehand and branch on the answer rather than on a cached status.

Self-sponsorship reads prior votes

submitProposal decides whether to charge the offering using getPriorVotes(sender, block.timestamp - 1). If you check getCurrentVotes() instead, you over-count power that changed in the same block — mint, delegate, or claim — conclude no offering is due, send value: 0, and revert. Under-counting is safe; over-counting is not.

Governance config is seven fields, and the last one is uint32

["uint32", "uint32", "uint256", "uint256", "uint256", "uint256", "uint32"]
// votingPeriod, gracePeriod, proposalOffering, quorumPercent,
// sponsorThreshold, minRetentionPercent, defaultExpiryWindow

All percentages are basis points — 2000 is 20%. Passing 20 creates a near-zero threshold. Omitting the trailing field makes abi.decode revert during initialisation, and the launch fails with no clearer signal than a failed transaction.

CREATE2 salt mining is two-phase and the sender is not you

The salt sender is DAOShipAndVaultLauncher — it is msg.sender to both factories — not your EOA. That is the mistake that costs a launch.

The factories' differing salt parameter types (bytes32 on QuaiVaultFactory, uint256 on DAOShipLauncher) are not a second trap, despite looking like one: abi.encodePacked renders both as the same 32 big-endian bytes, so one implementation covers both. Pad short salts to a full 32 bytes and move on.

The vault's initCodeHash embeds the predicted DAOShip address as initialModules, so mining cannot be done in one pass:

1. Mine shares, loot, and DAOShip — independent of each other.
2. Mine the vault, using the DAOShip address from step 1.

Mine naively, then verify the result with a single calculateAllAddresses(...) call rather than reimplementing the vault initCodeHash. See Launch from TypeScript for the working code.

6. Reading the indexer

The indexer is a Supabase PostgREST instance, read-only at the database level, open to anyone with the publishable key. Full schema in Indexer & data layer.

Here is the key. It is published on purpose:

Endpoint   https://anpmmwvxzchumfclhvmr.supabase.co/rest/v1
Key        sb_publishable_BdCkzZNKGhfs1AJUWFsgWw_yh3OhLi2
Schema     Accept-Profile: mainnet   — Quai mainnet, chainId 9
           Accept-Profile: testnet   — Orchard testnet, chainId 15000

curl "https://anpmmwvxzchumfclhvmr.supabase.co/rest/v1/ds_daos?select=id,name,total_shares::text&limit=10" \
  -H "apikey: sb_publishable_BdCkzZNKGhfs1AJUWFsgWw_yh3OhLi2" \
  -H "Accept-Profile: mainnet"

Three things to get right:

• Select the schema per network. Pass Accept-Profile: mainnet (chain 9) or Accept-Profile: testnet (chain 15000). Getting this wrong reads real rows off the wrong chain, which looks healthy and is entirely wrong. Omitting it is harmless by comparison — PostgREST defaults to public, which holds no DAO Ships tables, so you get a loud PGRST205.
• Check freshness before trusting anything. ds_indexer_state reports how far behind head the indexer is. If it flags requires_full_reindex, stop — do not degrade gracefully, because every row you read may predate a reorg.
• Poll, do not subscribe. Realtime quota is shared with the human application. 30–60 second polling is the supported pattern.

Navigator trust is also indexer-derived, not on-chain: trust_status runs self_asserted → sanctioned → unsanctioned → fabricated. Only sanctioned navigators have their poll rows materialised, so a self_asserted navigator legitimately has zero — that is not a bug. fabricated means weight reconciliation found forged vote weights; never display it.

7. Vocabulary and where things live

Source, all public:

• daoships-contracts — Solidity, ABIs, deployment-addresses.json (six of nine; see §4)
• daoships-app — the web client. Most of this page was distilled from its source comments.
• daoships-indexer — schema and ingestion
• daoships-www — this site

ABIs can be fetched directly from raw.githubusercontent.com. There is no separate machine-readable bundle, and no versioned artifact endpoint — the repositories are the interface.