Notes for AI agents

Start with the CLI and TUI for executable commands and encrypted wallets, or the TypeScript SDK for an application integration. The reviewed releases are @daoships/cli@0.1.0-alpha.3 and @daoships/sdk@0.1.0-alpha.4.

npm install -g @daoships/cli
daoships --schema
daoships --json network list

The CLI schema exposes all 88 commands and their inputs. Writes preview by default; execution requires explicit send/consent flags and a stable operation ID. Use the launch guide and coverage matrix for the supported workflows and evidence. This page explains the protocol details an integration still needs to handle correctly.

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:

import { assertActionSucceeded, parseProcessReceipt, type Receipt } from '@daoships/sdk';
 
export function verifyProcessing(receipt: Receipt, dao: string, proposalId: number, closingDefeat: boolean) {
  if (receipt.status !== 1) throw new Error('Transaction did not confirm successfully.');
  if (!closingDefeat) assertActionSucceeded(receipt, dao, proposalId);
  const outcome = parseProcessReceipt(receipt, dao, proposalId);
  if (closingDefeat && outcome !== 'defeated') throw new Error('Expected a defeated closure.');
  return outcome;
}

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,total_shares::text&id=eq.${daoId}`,
  { headers: { apikey: KEY, "Accept-Profile": "mainnet" } },
);

The SDK's typed indexer projections apply the text casts before JSON parsing and reject lossy values. Prefer those projections over writing a response pre-parser. If a value was already parsed as an unsafe JavaScript number, converting it to BigInt cannot restore lost precision.

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.

Use parseTokenAmount for human decimal input and exact decimal strings in CLI JSON. The SDK rejects excess fractional precision instead of silently rounding to a different amount.

List reads are a bounded window, not a complete set

PostgREST returns a capped page. Reading one page is not evidence that no other rows exist. The SDK returns nextOffset and provides iterate; follow them until exhaustion. A short page can be a server-imposed cap rather than the end of the data.

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

The indexer merges DAO name, description and avatar columns, but other profile fields come from the selected full record. Use buildDaoProfileUpdate with the assembled current profile to preserve fields that should remain unchanged. A dao.navigators post replaces the endorsement set: omitting a navigator can de-sanction it. Read and preserve the complete intended set.

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.

Block reads and voting snapshots need the chain's clock

A shardless provider.getBlock('latest') is rejected with Invalid shard. Use explicit shard context. DaoShipsProvider also fixes transaction nonce normalization in the pinned quais release:

import { DaoShipsProvider } from '@daoships/sdk';
import { Shard } from 'quais';
 
const provider = new DaoShipsProvider(
  'https://orchard.rpc.quai.network/cyprus1', 15000, { usePathing: false },
);
try {
  const block = await provider.getBlock(Shard.Cyprus1, 'latest');
  console.log(block?.woHeader.number);
} finally { provider.destroy(); }

For proposal submission, use DaoShipsChain.prepareSubmit. It verifies the parent work object and uses the parent's timestamp minus one for historical votes, while keeping state and simulation pinned to the selected block. Quai's EVM timestamp is the parent's time. Local clock time and a fixed safety buffer are not a correct replacement for this snapshot.

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), where block.timestamp is the EVM clock described above. Current votes can differ after minting, delegation or claims. The SDK applies the effective sponsorship threshold and prepares the exact offering; use that result and refresh it before signing.

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
• daoships-sdk — typed protocol APIs and tests
• daoships-cli — one-shot commands, TUI and encrypted wallets

Versioned ABI bundles ship in @daoships/sdk/abis; optional navigator bytecode ships in @daoships/sdk/bytecode. Use the CLI schema or installed daoships --schema for the executable interface. Source repositories remain available for protocol inspection.