@meridian-capital/core 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,93 @@
-# Temporary Holding Version
+# @meridian-capital/core
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Meridian's chain facts, pure maths and API types, written once and shared by meridian-frontend (the
+site and its API functions), the internal dashboard and the contracts repo's `ts-scripts`. It
+exists so a token address, an RPC list, a liquidity formula or the shape of an API answer has one
+copy rather than three that drift.
+
+The source lives here, in meridian-frontend, which uses it straight from this folder. Everyone else
+installs it from npm once it is published (until then the dashboard keeps copies in its `src/data/*Wire.ts`): `pnpm add @meridian-capital/core` (or `bun add`), with `viem` beside it. It is public:
+nothing in it is a secret, and a public package needs no token to install.
+
+## Rules
+
+- **Runs anywhere.** No Bun or Node APIs (`fs`, `process`, `Buffer`) and no DOM. The same file runs
+  in the browser, in a Vercel edge function and under Bun.
+- **Nothing happens at import.** No env reads, no clients, no network. A caller that needs an RPC
+  passes the URL (`rpcUrls(process.env.ROBINHOOD_RPC_URL)`). A future read client takes `fetch` and
+  its key as arguments.
+- **No assets.** Token logos stay in `src/constants/tokens.ts`, which extends `TokenRecord` with
+  them. Edge functions cannot import a `.png`.
+- **viem is a peer dependency.** Only types and pure helpers come from it. The package never owns a
+  copy.
+- **Relative imports only inside the package, with a `.js` extension** (`./types.js`), so the built
+  `dist/` loads in Node and Vitest as well as in a bundler. It has no `@/` alias of its own.
+
+## What is in it
+
+| Module | What it holds |
+| --- | --- |
+| `types` | `Address`, `Amount` (base units), `Bps`, `Unix` |
+| `chain` | `CHAIN_ID` 4663, `MULTICALL3`, `EXPLORER_URL`, `MAINNET_RPCS`, `rpcUrls(keyed?)` |
+| `addresses` | `ContractAddresses` and `MAINNET_ADDRESSES`, the deployed Meridian contracts |
+| `tokens` | `TOKEN_RECORDS`: every token Meridian knows, with address, decimals, treasury category and whether it is a genesis deposit token, without logos; lookups by symbol and by address; `MCD_TOKEN` and `GMCD_TOKEN`, their fixed facts |
+| `format` | `shortAddress` |
+| `math/concentratedLiquidity` | `sqrtPriceAtTick`, `amountsForLiquidity`: Uniswap V3/V4 amounts in bigint, with no SDK; `sqrtPriceOf` as a float |
+| `math/pairPrice` | `priceFromReserves`, `reservesBySide`, `pairAddress` (V2 CREATE2), `mcdPriceUsd1e18` |
+| `math/launch` | where MCD's launch stands (`launchStage`) and the chain's clock off one read (`chainNow`) |
+| `api/yield` | The yield board's types, and what `api/yield-board`, `yield-pool-state`, `yield-price-history` and the feeds answer (`YieldBoardWire`, `PoolStateWire`, `PriceHistoryWire`, ...) |
+| `api/treasury` | The treasury rows as `valueTreasury` gives them, `TreasuryWire` as `api/treasury` answers, and `fromTreasuryWire` |
+| `api/holders` | MCD's holders, `McdHoldersWire` as `api/mcd-holders` answers, and `parseMcdHolders` |
+| `api/multisig` | The Safes and their transactions, `DescribedMultisigsWire` as `api/multisig` answers, and `parseMultisigs` / `parseDescribedMultisigs` |
+
+Tests sit next to the code (`*.test.ts`). The root `pnpm test` runs them.
+
+## How it is imported
+
+| From | Import |
+| --- | --- |
+| `src/` (the app, built by Vite) | `import { CHAIN_ID } from "@meridian-capital/core"`, through the alias in `vite.config.ts`, `vitest.config.ts` and `tsconfig.app.json` |
+| `api/` and every `src/` file an API function reaches | a relative path: `../packages/core/src/chain` |
+| The dashboard, `ts-scripts`, anything else | `import { CHAIN_ID } from "@meridian-capital/core"`, installed from npm: the built `dist/` (ESM and type declarations, for a bundler or Bun) |
+
+Vercel bundles `api/` without the Vite alias, so any file an API function reaches must use relative
+paths all the way down, including `src/data/onchain/yield.ts` and `src/utils/yield/merge.ts`.
+`tsconfig.node.json` typechecks `api/` with no `paths`, so an aliased import there fails
+`pnpm typecheck` before it can fail a deploy.
+
+## Releasing a version
+
+1. Change the code here, in a PR; meridian-frontend uses it at once.
+2. Bump `version` in `packages/core/package.json` (semver: a removed or renamed export is a major).
+3. Tag the PR's commit with that version and push the tag: `git tag core-v0.2.0 && git push origin
+   core-v0.2.0`. The tag, not a branch, starts `.github/workflows/publish-core.yml`, so a release
+   needs no merge first. The workflow checks the tag against the version, runs the package's
+   tests, builds it (`pnpm build:core`) and publishes it with the repository secret `NPM_TOKEN`.
+4. Each consumer takes it when it needs it: `pnpm up @meridian-capital/core`, or let Renovate open the PR.
+
+`pnpm build:core && cd packages/core && npm pack --dry-run` shows what a release would contain.
+
+## Taking it into the other repos
+
+- **The internal dashboard**: its `src/data/*Wire.ts` copies and the chain facts in
+  `src/constants/chains.ts` become imports from `@meridian-capital/core` (its `SafeTx`, `SafeAccount` and
+  `Multisigs` are core's `DescribedSafeTx`, `DescribedSafeAccount` and `DescribedMultisigs`).
+- **`ts-scripts`** (contracts repo), replacing these local copies:
+
+  | ts-scripts today | core |
+  | --- | --- |
+  | `lib/chain.ts` `CHAIN_ID`, `EXPLORER_URL`, `RPC_URLS` | `chain` (`rpcUrls(process.env.RPC_URL)`) |
+  | `lib/chain.ts` `WETH`, `USDG`, `USDG_DECIMALS`, factory and pool-manager addresses | `tokens`, `addresses` |
+  | `config/deployment.ts` contract addresses | `addresses` |
+  | `config/tokens.ts` `RobinhoodTokens` | `tokens` |
+  | `lib/uniswap-math.ts` `sqrtRatioAtTick`, `principal` (on `consolidate/research`, built on `@uniswap/v3-sdk`) | `math/concentratedLiquidity` `sqrtPriceAtTick`, `amountsForLiquidity` |
+
+  Keep `txUrl`/`addressUrl`, `defineChain` and the deploy blocks in ts-scripts until a second
+  caller needs them.
+
+Next to move in, in this order:
+- read clients that take `fetch` and keys as arguments: Blockscout logs, DefiLlama, Uniswap price
+  history, the Uniswap positions backend, Fables, Merkl, Safe reads;
+- the readers built on them: TWAP buys, Furnace events, the MCD holder scan.
+
+Signing, Safe proposals, keepers, Tenderly, quoters and disk caches stay in ts-scripts.

package/dist/addresses.d.ts

@@ -0,0 +1,36 @@
+import type { Address } from "./types.js";
+export interface ContractAddresses {
+    mcd: Address;
+    gmcd: Address;
+    genesisFarm: Address;
+    convertible: Address;
+    treasuryWallets: readonly Address[];
+    /** Uniswap V2 factory, for looking up MCD's pair against each Genesis asset. */
+    uniswapV2Factory: Address;
+    /** The position NFTs' contracts: where a listed position's owner and each wallet's count are checked. */
+    uniswapV3PositionManager: Address;
+    uniswapV4PositionManager: Address;
+    /** FablesFi's pool registry, which names the hook a range's ERC-6909 shares sit on, and the lens that reads them. */
+    fablesPoolRegistry: Address;
+    fablesLens: Address;
+    /** ArrowFarm's MasterChef, where the treasury stakes its ArrowFarm vault shares. */
+    arrowChef: Address;
+    /** StonkPress's genesis farm, where the treasury stakes single tokens and LP. */
+    stonkGenesisPool: Address;
+    furnace: Address;
+    /** Morpho Blue, where the treasury lends, and the markets it lends into, by id. */
+    morpho: Address;
+    morphoMarkets: readonly `0x${string}`[];
+    /** Uniswap V4's PoolManager, whose storage the yield board reads a pool's price and liquidity out of. */
+    uniswapV4PoolManager: Address;
+}
+/**
+ * Meridian's contracts on Robinhood Chain mainnet, and the other protocols' it reads. The treasury
+ * wallets are the ones the dashboard reads balances and positions for, not Meridian contracts.
+ * The Uniswap V3 / V4 entries are Uniswap's own deployment on the chain; `uniswapV4PoolManager` is
+ * the one the yield board reads pool state out of. `fablesPoolRegistry` maps a pool id to the hook
+ * holding its liquidity, and `fablesLens` is the lens Fables' own portfolio page reads them through.
+ * `stonkGenesisPool` is StonkPress's genesis farm. `morphoMarkets` are the Morpho markets the
+ * treasury lends into.
+ */
+export declare const MAINNET_ADDRESSES: ContractAddresses;

package/dist/addresses.js

@@ -0,0 +1,31 @@
+/**
+ * Meridian's contracts on Robinhood Chain mainnet, and the other protocols' it reads. The treasury
+ * wallets are the ones the dashboard reads balances and positions for, not Meridian contracts.
+ * The Uniswap V3 / V4 entries are Uniswap's own deployment on the chain; `uniswapV4PoolManager` is
+ * the one the yield board reads pool state out of. `fablesPoolRegistry` maps a pool id to the hook
+ * holding its liquidity, and `fablesLens` is the lens Fables' own portfolio page reads them through.
+ * `stonkGenesisPool` is StonkPress's genesis farm. `morphoMarkets` are the Morpho markets the
+ * treasury lends into.
+ */
+export const MAINNET_ADDRESSES = {
+    mcd: "0x378A50eaC56f45Fb74e4cE7F1962dbCA33515c14",
+    gmcd: "0x296182D54dc5cBe6d960b9cFe3882dD5c87d51fd",
+    genesisFarm: "0xE5BffCF30D18c27Dac29b2EDF8a608b2E2BB52F7",
+    convertible: "0xf948Cd016956A942AAd10C3181e6B6fb49e30ef4",
+    treasuryWallets: [
+        "0xD57056275A348E7C71dD80C8ddf6d82B1C808749",
+        "0xF186674191b6CC037c699Ec066CDB14971cfE797",
+        "0xcF2d75B69e723246722B7D4cCdA7DDC762B2fC55",
+    ],
+    uniswapV2Factory: "0x8bcEaA40B9AcdfAedF85AdF4FF01F5Ad6517937f",
+    uniswapV3PositionManager: "0x73991a25C818Bf1f1128dEAaB1492D45638DE0D3",
+    uniswapV4PositionManager: "0x58daec3116aae6D93017bAAea7749052E8a04fA7",
+    uniswapV4PoolManager: "0x8366a39CC670B4001A1121B8F6A443A643e40951",
+    fablesPoolRegistry: "0x159A113E012593D9B3cC63ad45E30F0467e13Ef3",
+    fablesLens: "0xE44c0BAb43BdD47e7Ab40236bC183dCc77A9ED6c",
+    arrowChef: "0x0591F89386eBfF9AA52903939774E218eA25eC55",
+    stonkGenesisPool: "0x935661973d9379b792bcb110d1eebd05034b838f",
+    furnace: "0x25E06c975219C91cf05Ba3cC4030A542317b0Fc6",
+    morpho: "0x9D53d5E3bd5E8d4Cbfa6DB1ca238AEA02E651010",
+    morphoMarkets: ["0xaa586d26a6fe62d9c0f0948fede6e2130500ac7a655587447e2d4a37e6330589"],
+};

package/dist/api/holders.d.ts

@@ -0,0 +1,94 @@
+import type { Address, Amount, Unix } from "../types.js";
+/**
+ * MCD's holders as meridian-frontend's `api/mcd-holders` serves them: every address holding one MCD
+ * or more, named, and where its MCD sits. MCD travels in base units (18 decimals) as decimal strings;
+ * `parseMcdHolders` revives them.
+ */
+/** Where a holder's MCD sits: loose in the wallet, behind Uniswap V2 LP it holds, or staked in a farm. */
+export type McdHoldingKind = "wallet" | "lp" | "staked";
+export interface McdHolding {
+    kind: McdHoldingKind;
+    /** "Uniswap V2 MCD/USDG", "StonkPress MCD", "StonkPress MCD/WETH LP"; null for the wallet. */
+    venue: string | null;
+    /** The pair or the farm; null for the wallet. */
+    contract: Address | null;
+    /** The MCD behind it, base units. */
+    mcd: Amount;
+}
+export interface McdHolder {
+    address: Address;
+    /** The treasury's or a Meridian contract's name, else its ENS or DeBank name; null where none is known. */
+    name: string | null;
+    /** Set on the treasury's wallets and Meridian's contracts, so they are not read as the community. */
+    role: HolderRole | null;
+    /** The X handle, without the `@`. */
+    x: string | null;
+    /** Every holding added up. */
+    total: Amount;
+    /** Largest first; a kind with nothing in it is left out. */
+    holdings: McdHolding[];
+}
+/** Every address holding at least one MCD, read off the token's transfers and balances. */
+export interface McdHolders {
+    supply: Amount;
+    /** How many addresses MCD has ever been sent to; `holders` keeps those with one MCD or more. */
+    addresses: number;
+    /** Largest first. */
+    holders: McdHolder[];
+    block: number;
+    asOf: Unix;
+}
+/** A Uniswap V2 pair with MCD on one side. Its MCD is counted to the addresses holding its LP. */
+export interface McdPairWire {
+    address: string;
+    /** The other side's token and symbol, as the token answers it. */
+    quote: string;
+    quoteSymbol: string;
+    reserveMcd: string;
+    lpSupply: string;
+}
+/** A StonkPress genesis-farm pool that takes MCD, or the LP of an MCD pair. */
+export interface McdFarmPoolWire {
+    pid: number;
+    token: string;
+    /** The pair whose LP the pool takes; null when it takes MCD itself. */
+    pair: string | null;
+}
+/** A Meridian contract or the treasury, named so it is not read as a holder among the community. */
+export type HolderRole = "treasury" | "protocol";
+export interface McdHolderWire {
+    address: string;
+    /** Who the address is, where known: the treasury's or a Meridian contract's name, else its ENS or DeBank name. */
+    name?: string;
+    /** Set on the treasury's wallets and Meridian's contracts. */
+    role?: HolderRole;
+    /** The holder's X handle, without the `@`. */
+    x?: string;
+    /** MCD in the wallet. */
+    wallet: string;
+    /** The MCD behind the pair LP the wallet holds, per pair. */
+    lp: {
+        pair: string;
+        mcd: string;
+    }[];
+    /** The MCD behind what the wallet has staked in the farm, per pool. */
+    staked: {
+        pid: number;
+        mcd: string;
+    }[];
+}
+export interface McdHoldersWire {
+    /** The block every balance was read at, and when, unix seconds. */
+    block: number;
+    asOf: number;
+    /** `MCD.totalSupply()`. */
+    supply: string;
+    /** How many addresses MCD has ever been sent to; `holders` keeps those with at least one MCD. */
+    addresses: number;
+    farm: string;
+    pairs: McdPairWire[];
+    farmPools: McdFarmPoolWire[];
+    holders: McdHolderWire[];
+}
+/** The wire's decimal strings to amounts, each holding named after its venue, largest first. */
+export declare function parseMcdHolders(wire: McdHoldersWire): McdHolders;

package/dist/api/holders.js

@@ -0,0 +1,24 @@
+/** The wire's decimal strings to amounts, each holding named after its venue, largest first. */
+export function parseMcdHolders(wire) {
+    const pairs = new Map(wire.pairs.map((p) => [p.address.toLowerCase(), p]));
+    const pools = new Map(wire.farmPools.map((f) => [f.pid, f]));
+    const holders = wire.holders.map((h) => {
+        const holdings = [
+            { kind: "wallet", venue: null, contract: null, mcd: BigInt(h.wallet) },
+            ...h.lp.map((x) => {
+                const pair = pairs.get(x.pair.toLowerCase());
+                return { kind: "lp", venue: `Uniswap V2 MCD/${pair?.quoteSymbol ?? "?"}`, contract: x.pair, mcd: BigInt(x.mcd) };
+            }),
+            ...h.staked.map((x) => {
+                const pool = pools.get(x.pid);
+                const lp = pool?.pair ? pairs.get(pool.pair.toLowerCase()) : undefined;
+                return { kind: "staked", venue: lp ? `StonkPress MCD/${lp.quoteSymbol} LP` : "StonkPress MCD", contract: wire.farm, mcd: BigInt(x.mcd) };
+            }),
+        ]
+            .filter((x) => x.mcd > 0n)
+            .sort((a, b) => (b.mcd > a.mcd ? 1 : b.mcd < a.mcd ? -1 : 0));
+        return { address: h.address, name: h.name ?? null, role: h.role ?? null, x: h.x ?? null, total: holdings.reduce((s, x) => s + x.mcd, 0n), holdings };
+    });
+    holders.sort((a, b) => (b.total > a.total ? 1 : b.total < a.total ? -1 : 0));
+    return { supply: BigInt(wire.supply), addresses: wire.addresses, holders, block: wire.block, asOf: wire.asOf };
+}

package/dist/api/multisig.d.ts

@@ -0,0 +1,216 @@
+import type { Address, Amount, Unix } from "../types.js";
+/**
+ * The project's Safes as meridian-frontend's `api/multisig` serves them: each Safe's owners,
+ * threshold and nonce, its queue and history as Safe's Transaction Service lists them (its own field
+ * names, numbers as decimal strings), each transaction described in words, and every name the
+ * describer knows. `parseMultisigs` revives the Safes; `parseDescribedMultisigs` revives a read with
+ * its descriptions.
+ */
+/** `0` CALL, `1` DELEGATECALL: the Safe runs the target's code as itself. */
+export type SafeOperation = 0 | 1;
+/** One owner's signature on a Safe transaction, as Safe's Transaction Service holds it. */
+export interface SafeConfirmation {
+    owner: Address;
+    /** Hex; 65 bytes for an EOA, longer for a contract signature. Null when the service holds none (an on-chain approval). */
+    signature: Address | null;
+    /** The service's own label: `EOA`, `ETH_SIGN`, `APPROVED_HASH`, `CONTRACT_SIGNATURE`. */
+    signatureType: string | null;
+    submittedAt: Unix | null;
+}
+/** A call decoded by the Transaction Service off the target's verified ABI; the fallback for one the app has no ABI for. */
+export interface SafeDecodedCall {
+    method: string;
+    parameters: SafeDecodedParam[];
+}
+export interface SafeDecodedParam {
+    name: string;
+    type: string;
+    /** As the service gives it: a string, or an array of them. */
+    value: unknown;
+    /** A `multiSend` batch's calls, each with its own decoding where the service has one. */
+    valueDecoded?: {
+        operation: number;
+        to: Address;
+        value: string;
+        data: Address | null;
+        dataDecoded: SafeDecodedCall | null;
+    }[] | null;
+}
+/**
+ * A Safe multisig transaction: proposed (and maybe signed) off-chain through Safe's Transaction
+ * Service, or executed. Every field the Safe hashes is here, so the hash is rebuilt and checked
+ * before anything is signed or sent.
+ */
+export interface SafeTx {
+    safe: Address;
+    safeTxHash: Address;
+    nonce: number;
+    to: Address;
+    value: Amount;
+    data: Address | null;
+    operation: SafeOperation;
+    safeTxGas: Amount;
+    baseGas: Amount;
+    gasPrice: Amount;
+    gasToken: Address;
+    refundReceiver: Address;
+    proposer: Address | null;
+    submittedAt: Unix | null;
+    executed: boolean;
+    /** Null until executed. */
+    successful: boolean | null;
+    executedAt: Unix | null;
+    /** The execution's chain transaction. */
+    txHash: Address | null;
+    executor: Address | null;
+    confirmations: SafeConfirmation[];
+    decoded: SafeDecodedCall | null;
+}
+/** One watched Safe: its owners and threshold off the chain, its queue and history off the Transaction Service. */
+export interface SafeAccount {
+    address: Address;
+    name: string;
+    /** `VERSION()`; null if the read failed. */
+    version: string | null;
+    owners: Address[];
+    threshold: number;
+    /** The next nonce the Safe will execute. */
+    nonce: number;
+    /** Not executed, nonce at or past the Safe's: what can still be signed or executed. Lowest nonce first. */
+    queued: SafeTx[];
+    /** Executed, newest first. */
+    history: SafeTx[];
+    /** Why the queue or history could not be read, when it could not; the chain figures may still be good. */
+    error: string | null;
+}
+/** The project's multisigs. */
+export interface Multisigs {
+    chainId: number;
+    /** Safe{Wallet}'s prefix for the chain (`<shortName>:<address>`), for its links; null when unknown. */
+    shortName: string | null;
+    safes: SafeAccount[];
+    asOf: Unix;
+}
+export interface DescribedArg {
+    name: string;
+    value: string;
+}
+export interface DescribedCall {
+    /** One sentence. */
+    summary: string;
+    /** Who is called, named where known. */
+    target: string;
+    targetAddress: Address;
+    /** `transfer`, `multiSend`; null for a plain value transfer or an undecoded call. */
+    method: string | null;
+    args: DescribedArg[];
+    /** Every address the arguments name, in order, once each; the target is `targetAddress`. */
+    addresses: Address[];
+    operation: SafeOperation;
+    /** Native ETH sent with the call, base units. */
+    value: bigint;
+    /** Inner calls, for a batch or a multicall. */
+    calls: DescribedCall[];
+    /** Decoded off the app's ABIs or the service's; false means only the selector is known. */
+    decoded: boolean;
+}
+export interface TxDescription {
+    /** The headline: the one call's sentence, or a batch's count and first actions. */
+    title: string;
+    call: DescribedCall;
+    /** Things a signer should look at twice. */
+    warnings: string[];
+}
+/** A transaction as the Transaction Service lists it (`/api/v1/safes/{address}/multisig-transactions/`). */
+export interface ServiceTxWire {
+    safe: string;
+    to: string;
+    value: string;
+    data: string | null;
+    operation: number;
+    safeTxGas: string | number;
+    baseGas: string | number;
+    gasPrice: string | number;
+    gasToken: string | null;
+    refundReceiver: string | null;
+    nonce: string | number;
+    safeTxHash: string;
+    proposer?: string | null;
+    submissionDate?: string | null;
+    executionDate?: string | null;
+    isExecuted: boolean;
+    isSuccessful?: boolean | null;
+    transactionHash?: string | null;
+    executor?: string | null;
+    confirmations?: {
+        owner: string;
+        signature?: string | null;
+        signatureType?: string | null;
+        submissionDate?: string | null;
+    }[] | null;
+    dataDecoded?: SafeDecodedCall | null;
+}
+export interface SafeWire {
+    address: string;
+    name: string;
+    version: string | null;
+    owners: string[];
+    threshold: number;
+    nonce: number;
+    queued: ServiceTxWire[];
+    history: ServiceTxWire[];
+    error: string | null;
+}
+export interface MultisigsWire {
+    chainId: number;
+    shortName: string | null;
+    safes: SafeWire[];
+    asOf: number;
+}
+/** A described call on the wire: its ETH as a decimal string. */
+export type DescribedCallWire = Omit<DescribedCall, "value" | "calls"> & {
+    value: string;
+    calls: DescribedCallWire[];
+};
+export interface TxDescriptionWire extends Omit<TxDescription, "call"> {
+    call: DescribedCallWire;
+}
+/**
+ * What a read answers: the Safes, each transaction in words (`describeSafeTx`, run in the function
+ * against the app's ABIs and names, so a client needs neither), and every name the describer knows.
+ */
+export interface DescribedMultisigsWire extends MultisigsWire {
+    /** Each transaction in words, by its lower-cased `safeTxHash`. */
+    descriptions: Record<string, TxDescriptionWire>;
+    /** Lower-cased address → name: the Safes, the signers, Meridian's contracts, the tokens, known counterparties. */
+    names: Record<string, string>;
+    /** The treasury's wallets outside the Safes. */
+    wallets: {
+        address: string;
+        name: string;
+    }[];
+}
+export declare function describedCallWire(call: DescribedCall): DescribedCallWire;
+export declare function parseSafeTx(w: ServiceTxWire): SafeTx;
+export declare function parseSafe(w: SafeWire): SafeAccount;
+export declare function parseMultisigs(wire: MultisigsWire): Multisigs;
+/** A transaction with its description. */
+export interface DescribedSafeTx extends SafeTx {
+    description: TxDescription;
+}
+export interface DescribedSafeAccount extends Omit<SafeAccount, "queued" | "history"> {
+    queued: DescribedSafeTx[];
+    history: DescribedSafeTx[];
+}
+/** A read revived with every transaction's description, every name the describer knows and the treasury's other wallets. */
+export interface DescribedMultisigs extends Omit<Multisigs, "safes"> {
+    safes: DescribedSafeAccount[];
+    /** Lower-cased address → a name. */
+    names: ReadonlyMap<string, string>;
+    wallets: {
+        address: Address;
+        name: string;
+    }[];
+}
+/** The Safes, each transaction with the description the function gave it. A transaction with none is an error, never drawn blind. */
+export declare function parseDescribedMultisigs(wire: DescribedMultisigsWire): DescribedMultisigs;

package/dist/api/multisig.js

@@ -0,0 +1,78 @@
+export function describedCallWire(call) {
+    return { ...call, value: call.value.toString(), calls: call.calls.map(describedCallWire) };
+}
+const ZERO = "0x0000000000000000000000000000000000000000";
+const unix = (date) => {
+    if (!date)
+        return null;
+    const ms = Date.parse(date);
+    return Number.isFinite(ms) ? Math.floor(ms / 1000) : null;
+};
+const big = (v) => (v == null || v === "" ? 0n : BigInt(v));
+const hexOrNull = (v) => (v && v !== "0x" ? v : null);
+export function parseSafeTx(w) {
+    const confirmations = (w.confirmations ?? []).map((c) => ({
+        owner: c.owner,
+        signature: hexOrNull(c.signature),
+        signatureType: c.signatureType ?? null,
+        submittedAt: unix(c.submissionDate),
+    }));
+    return {
+        safe: w.safe,
+        safeTxHash: w.safeTxHash,
+        nonce: Number(w.nonce),
+        to: w.to,
+        value: big(w.value),
+        data: hexOrNull(w.data),
+        operation: (w.operation === 1 ? 1 : 0),
+        safeTxGas: big(w.safeTxGas),
+        baseGas: big(w.baseGas),
+        gasPrice: big(w.gasPrice),
+        gasToken: (w.gasToken ?? ZERO),
+        refundReceiver: (w.refundReceiver ?? ZERO),
+        proposer: (w.proposer ?? null),
+        submittedAt: unix(w.submissionDate),
+        executed: w.isExecuted,
+        successful: w.isExecuted ? (w.isSuccessful ?? null) : null,
+        executedAt: unix(w.executionDate),
+        txHash: hexOrNull(w.transactionHash),
+        executor: (w.executor ?? null),
+        confirmations,
+        decoded: w.dataDecoded ?? null,
+    };
+}
+export function parseSafe(w) {
+    return {
+        address: w.address,
+        name: w.name,
+        version: w.version,
+        owners: w.owners,
+        threshold: w.threshold,
+        nonce: w.nonce,
+        queued: w.queued.map(parseSafeTx).sort((a, b) => a.nonce - b.nonce || (a.submittedAt ?? 0) - (b.submittedAt ?? 0)),
+        history: w.history.map(parseSafeTx).sort((a, b) => b.nonce - a.nonce),
+        error: w.error,
+    };
+}
+export function parseMultisigs(wire) {
+    return { chainId: wire.chainId, shortName: wire.shortName, safes: wire.safes.map(parseSafe), asOf: wire.asOf };
+}
+function describedCall(wire) {
+    return { ...wire, value: BigInt(wire.value), calls: wire.calls.map(describedCall) };
+}
+/** The Safes, each transaction with the description the function gave it. A transaction with none is an error, never drawn blind. */
+export function parseDescribedMultisigs(wire) {
+    const described = (tx) => {
+        const d = wire.descriptions[tx.safeTxHash.toLowerCase()];
+        if (!d)
+            throw new Error(`The multisig read sent no description for ${tx.safeTxHash}`);
+        return { ...tx, description: { ...d, call: describedCall(d.call) } };
+    };
+    const { safes, ...rest } = parseMultisigs(wire);
+    return {
+        ...rest,
+        safes: safes.map((s) => ({ ...s, queued: s.queued.map(described), history: s.history.map(described) })),
+        names: new Map(Object.entries(wire.names)),
+        wallets: wire.wallets.map((w) => ({ address: w.address, name: w.name })),
+    };
+}