@johannc-dev/zyrk 0.0.0-stage → 0.2.0

package/dist/sdk.d.ts

@@ -0,0 +1,1129 @@
+/**
+ * `@johannc-dev/zyrk` 0.2: what a hosted program imports.
+ *
+ * This module is bundled into the program: it has no dependency and its
+ * runtime part is a handful of small, neutral helpers (reading a row of an
+ * {@link HourBatch}, building a trade id). It ships tooling, never a strategy.
+ */
+export type Json = null | boolean | number | string | Json[] | {
+    [key: string]: Json;
+};
+/**
+ * What a program sends (results, state, job arguments, logs, emits): JSON,
+ * read-only arrays accepted, `undefined` properties dropped as by
+ * `JSON.stringify`.
+ */
+export type JsonInput = null | boolean | number | string | readonly JsonInput[] | {
+    readonly [key: string]: JsonInput | undefined;
+};
+/** A base58 Solana address (mint, wallet, pool). */
+export type Address = string;
+/**
+ * A history window, `[sinceMs, untilMs)` in milliseconds since the epoch,
+ * at most 31 days long.
+ */
+export interface Window {
+    readonly sinceMs: number;
+    readonly untilMs: number;
+    /**
+     * Accept hours with gaps or rejected operations instead of failing with
+     * `partial_coverage`. Such batches have `complete: false`.
+     */
+    readonly allowPartial?: boolean;
+    /** Fill `HourBatch.signatures` (88 characters per trade: ask only if needed). */
+    readonly withSignatures?: boolean;
+    /**
+     * Fill `HourBatch.market`: pool reserves, fee rates, signer, priority fee
+     * and flags of each trade (75 more bytes per trade, counted in the read
+     * limit). Without it these fields are neither read nor sent.
+     */
+    readonly withMarket?: boolean;
+    /**
+     * Also return pool events as rows with `side` {@link Side.event} and their
+     * kind in `market.event` (implies `withMarket`). Token reads: every event of
+     * the mint (creation, migration, pool creation, liquidity added or
+     * removed). Wallet reads: the tokens the wallet created. Event rows have
+     * `op` 65535; skip them (`side[i] === Side.event`) when you sum trades.
+     */
+    readonly withEvents?: boolean;
+    /**
+     * Fill `HourBatch.order` (on-chain order: transaction index, event rank,
+     * block time) and deliver each batch in on-chain order instead of provider
+     * order. 15 bytes per trade.
+     */
+    readonly withOrder?: boolean;
+    /**
+     * Fill `HourBatch.tx`: the transaction of each trade (an id shared by the
+     * trades of one transaction, kept after signatures are dropped) and its
+     * place in it. Does not change the batch order. 7 bytes per trade.
+     */
+    readonly withTx?: boolean;
+}
+/** Options of `ctx.data.walletTrades` and `ctx.data.tokenTrades`. */
+export interface TradeQuery extends Window {
+    /** Only buys or only sells. Default: both. */
+    readonly side?: "buy" | "sell";
+}
+/** `HourBatch.side` values. */
+export declare const Side: {
+    readonly buy: 0;
+    readonly sell: 1;
+    readonly event: 2;
+};
+/** `HourBatch.protocol` values. */
+export declare const Protocol: {
+    readonly pumpfun: 0;
+    readonly pumpswap: 1;
+};
+/** Bits of `HourBatch.order.flags`. A trade has `known` or one `unknown*` reason. */
+export declare const OrderFlag: {
+    /** `txIndex` and `eventIndex` are set. */
+    readonly known: 1;
+    /** Joined by the trade's signature. */
+    readonly bySignature: 2;
+    /**
+     * An identical trade (same slot, pool, trader and amounts) sits in another
+     * transaction of the slot: which of the two is which is not certain.
+     */
+    readonly ambiguous: 4;
+    /** An amount of the trade equals none of its chain event's. */
+    readonly amountDiffers: 8;
+    /** The slot's block was searched; no transaction fits the trade. */
+    readonly unknownNoMatch: 16;
+    /** Order not known yet: open hour, hour not ordered yet, slot not covered. */
+    readonly unknownNotCovered: 32;
+    /** Nothing to join (no slot, or no operation with a chain event). */
+    readonly unknownNoKey: 64;
+    /**
+     * The finalized chain has no block at the trade's slot (skipped slot,
+     * abandoned fork): the provider published a trade that did not happen.
+     * Drop it from a backtest.
+     */
+    readonly notFinalized: 128;
+};
+/** `order.txIndex` value when unknown. */
+export declare const NO_TX_INDEX = 4294967295;
+/** `order.eventIndex` value when unknown. */
+export declare const NO_EVENT_INDEX = 65535;
+/**
+ * On-chain order of each trade of a batch (`withOrder: true`). With it, the
+ * batch is sorted by `(slot, txIndex, eventIndex)`, trades of unknown order
+ * last within their slot. `(slot, txIndex)` names the transaction.
+ */
+export interface OrderColumns {
+    /** Index of the transaction in its block (votes included, as `getBlock`); {@link NO_TX_INDEX} when unknown. */
+    readonly txIndex: Uint32Array;
+    /**
+     * Rank of the trade's event among the Pump.fun/PumpSwap events of its
+     * transaction, in execution order; {@link NO_EVENT_INDEX} when unknown.
+     */
+    readonly eventIndex: Uint16Array;
+    /** Block time from the chain in ms (1 s resolution); `NaN` when unknown. */
+    readonly blockTimeMs: Float64Array;
+    /** {@link OrderFlag} bits. */
+    readonly flags: Uint8Array;
+}
+/** `tx.id` value when the transaction is unknown. */
+export declare const NO_TX_ID = 4294967295;
+/**
+ * Bits of `HourBatch.tx.flags`. A trade has one grouping bit
+ * (`bySignature`, `byChain` or `unknown`) and, when grouped, one index bit
+ * (`chainIndex` or `providerIndex`).
+ */
+export declare const TxFlag: {
+    /** Grouped by its signature (live, sealing or provider archive). */
+    readonly bySignature: 1;
+    /** Grouped by its on-chain `(slot, txIndex)`, for an hour stored without signatures. */
+    readonly byChain: 2;
+    /** `index` is the on-chain event rank: exact execution order. */
+    readonly chainIndex: 4;
+    /**
+     * `index` is the provider's order. The provider groups the events of a
+     * transaction by type (transfers, trades, liquidity, fees): not exact,
+     * though it matched the chain for 99.9 % of the pairs of trades measured.
+     */
+    readonly providerIndex: 8;
+    /** No transaction known: `id` is {@link NO_TX_ID}. */
+    readonly unknown: 16;
+};
+/**
+ * The transaction of each trade of a batch (`withTx: true`). Trades of one
+ * batch with the same `id` are in the same transaction (a route through
+ * several pools, a bundle-like multi-operation transaction): `id` is unique
+ * within the hour (the provider line of the transaction's first row), so
+ * `(hour, id)` names it. Order the trades of one transaction by `index`
+ * when they share the same index bit of `flags`, else by `(line, op)`.
+ */
+export interface TxColumns {
+    /** Transaction id within the hour; {@link NO_TX_ID} when unknown. */
+    readonly id: Uint32Array;
+    /** Place of the trade in its transaction (see {@link TxFlag}); 65535 when unknown. */
+    readonly index: Uint16Array;
+    /** {@link TxFlag} bits. */
+    readonly flags: Uint8Array;
+}
+/** Value of an address column (`pool`, `trader`) when the address is absent. */
+export declare const NO_ADDRESS = -1;
+export declare const HOUR_MS = 3600000;
+/** Wrapped SOL, the usual quote mint. */
+export declare const SOL_MINT: Address;
+/**
+ * The trades of one hour of a window, as columns: entry `i` of every array
+ * describes trade `i`. Rows are in provider order `(hour, line, op)`, or in
+ * on-chain order with `withOrder: true` (see {@link OrderColumns}).
+ *
+ * Arrays are read-only views of server memory, valid for the whole
+ * execution. Copy what you keep (`Array.from`, `slice`) only if you need to
+ * modify it. Floats use `NaN` for an absent value.
+ */
+export interface HourBatch {
+    /**
+     * Hour of the file the trades are stored in: `hour * 3_600_000` is its
+     * first millisecond. The provider files a trade by its reception, so a few
+     * trades may carry a `timeMs` just outside this hour (still in the window).
+     */
+    readonly hour: number;
+    /** `sealed`: final. `live`: the open hour, may still change once sealed. */
+    readonly source: "sealed" | "live";
+    /**
+     * No gap and no rejected operation in this hour for this read. With
+     * `allowPartial`, an hour of the window with a coverage gap and no trade
+     * still comes, empty (`length: 0`) and `complete: false`.
+     */
+    readonly complete: boolean;
+    /** Operations of this hour that could not be normalized (not in the batch). */
+    readonly skipped: number;
+    /** Number of trades: the length of every column. */
+    readonly length: number;
+    /** Dictionary of this batch. `mint`, `pool`, `trader`, `quoteMint` index it. */
+    readonly addresses: readonly Address[];
+    readonly line: Uint32Array;
+    readonly op: Uint16Array;
+    readonly slot: Float64Array;
+    readonly timeMs: Float64Array;
+    /** Reception time for live trades; `NaN` when unknown. */
+    readonly receivedMs: Float64Array;
+    /** `0` buy, `1` sell (see {@link Side}). */
+    readonly side: Uint8Array;
+    /** `0` pumpfun (bonding curve), `1` pumpswap (AMM) (see {@link Protocol}). */
+    readonly protocol: Uint8Array;
+    readonly mint: Uint32Array;
+    /** `-1` when absent. */
+    readonly pool: Int32Array;
+    /** `-1` when absent. */
+    readonly trader: Int32Array;
+    readonly quoteMint: Uint32Array;
+    readonly tokenRaw: BigUint64Array;
+    readonly tokenDecimals: Uint8Array;
+    readonly quoteRaw: BigUint64Array;
+    readonly quoteDecimals: Uint8Array;
+    readonly tokenAmount: Float64Array;
+    readonly quoteAmount: Float64Array;
+    /** Raw provider price (quote per token). Often the only price present. */
+    readonly price: Float64Array;
+    readonly priceSol: Float64Array;
+    readonly priceUsd: Float64Array;
+    readonly quotePriceUsd: Float64Array;
+    readonly usdValue: Float64Array;
+    /** Only with `withSignatures: true`; `null` when not stored for a trade. */
+    readonly signatures?: readonly (string | null)[];
+    /** Only with `withMarket: true`. */
+    readonly market?: MarketColumns;
+    /** Only with `withOrder: true`; the batch is then in on-chain order. */
+    readonly order?: OrderColumns;
+    /** Only with `withTx: true`. */
+    readonly tx?: TxColumns;
+}
+/** `MarketColumns.event` values. */
+export declare const MarketEvent: {
+    /** A trade. */
+    readonly none: 0;
+    /** The token left its bonding curve: `pool` is the new pumpswap pool, reserves are its own. */
+    readonly migrate: 1;
+    readonly createPool: 2;
+    /** Liquidity added by `trader`: amounts added, reserves after. */
+    readonly add: 3;
+    /** Liquidity removed by `trader`: amounts removed, reserves after. */
+    readonly remove: 4;
+    /**
+     * The token was created: `market.signer` signed it, `market.creatorFeeRecipient`
+     * is the creator named by the bonding curve (they differ for 17 % of
+     * creations). The creator's initial buy, if any, is the trade of the same
+     * `line`, flagged {@link MarketFlag.creatorInitialBuy}.
+     */
+    readonly create: 5;
+    /**
+     * Fee distributions (provider `distributeFees` rows, `withEvents` token
+     * reads). `quoteMint` is the mint paid (`feeMint`; SOL for `sol`),
+     * `quoteRaw` the total paid by the row (at `quoteDecimals`: the mint's
+     * decimals when known, else those the amounts are written with),
+     * `tokenRaw` 0, `trader` the recipient when the row has a single one
+     * ({@link NO_ADDRESS} otherwise). Fees to the token's holders, up to 8
+     * recipients per row.
+     */
+    readonly feeHolders: 6;
+    /** Creator fees paid to the shareholders of a fee-sharing token. */
+    readonly feeShareholders: 7;
+    /**
+     * Creator fees collected by the creator. Usually without token
+     * ({@link MarketFlag.feeWithoutToken}): such rows are in no token read.
+     */
+    readonly feeCreator: 8;
+    /** Fees claimed by a social account. */
+    readonly feeSocial: 9;
+    /** A fee distribution of another type. */
+    readonly feeOther: 10;
+};
+/** Bits of `MarketColumns.flags`. */
+export declare const MarketFlag: {
+    /** `tokenReserve` and `quoteReserve` are set. */
+    readonly reserves: 1;
+    /** `virtualTokenReserve` and `virtualQuoteReserve` are set. */
+    readonly virtualReserves: 2;
+    /**
+     * The provider row holds several operations on this pool (e.g. a buy and
+     * a sell in one transaction): its reserves are the state after the whole
+     * row, not after this operation.
+     */
+    readonly multiOpRow: 4;
+    /**
+     * Token reads only: the previous trade of this pool in the batch, with
+     * this trade's token amount, does not give this trade's token reserve. An
+     * event between them is missing (liquidity, migration, a row the provider
+     * did not send) or the provider order differs from the chain order.
+     */
+    readonly chainBreak: 8;
+    /** No earlier trade of this pool in the batch to check against. */
+    readonly chainUnchecked: 16;
+    /** The creator's initial buy, made by the `create` of the token. */
+    readonly creatorInitialBuy: 32;
+    /** `cashbackEnabled` of the provider row. */
+    readonly cashback: 64;
+    /** `mayhemMode` of the provider row. */
+    readonly mayhem: 128;
+    /**
+     * A fee distribution that names no token (`mint` is the empty address):
+     * creator fees collected from the creator's vault, which pools the fees
+     * of all the creator's tokens. No read returns such rows today (they are
+     * in no token read): reserved for a read of fee recipients.
+     */
+    readonly feeWithoutToken: 256;
+    /**
+     * PumpSwap pool inverted on-chain (token is the on-chain quote): fees are
+     * taken in tokens. The reserve is the provider's, which leaves them out: a
+     * buy of X leaves `ceil(X * 25 / 10000)` more tokens in the pool, and the
+     * trader receives 0.30 % less than `tokenRaw`. `chainBreak` accounts for it.
+     */
+    readonly invertedPool: 512;
+};
+/**
+ * Pool state and fees of each trade (`withMarket: true`), entry `i` for
+ * trade `i`. Reserves are raw integers (token at `tokenDecimals`, quote at
+ * `quoteDecimals`): the state of the pool **after** the provider row of the
+ * trade. `0` when absent (see `flags`). Rates in basis points, `NaN` when
+ * absent.
+ */
+export interface MarketColumns {
+    /** Real reserves (provider `tokensInPool`, `quoteInPool`). */
+    readonly tokenReserve: BigUint64Array;
+    readonly quoteReserve: BigUint64Array;
+    /**
+     * Pumpfun: the virtual reserves of the bonding curve, the ones its
+     * constant product uses. Pumpswap: the provider's virtual reserves, when
+     * it gives them.
+     */
+    readonly virtualTokenReserve: BigUint64Array;
+    readonly virtualQuoteReserve: BigUint64Array;
+    /** Provider `poolFeeRate` × 10 000. */
+    readonly poolFeeBps: Float64Array;
+    /** Provider `solRouteFeeRate` × 10 000. */
+    readonly routeFeeBps: Float64Array;
+    /** Provider `holderRewardsRate` × 10 000. */
+    readonly holderRewardsBps: Float64Array;
+    /** Index in `addresses` of the creator fee recipient; `-1` when absent. */
+    readonly creatorFeeRecipient: Int32Array;
+    /** Index in `addresses` of the transaction signer; `-1` when absent. */
+    readonly signer: Int32Array;
+    /** Priority fee of the transaction in lamports; `2n ** 64n - 1n` when absent. */
+    readonly priorityFeeRaw: BigUint64Array;
+    /** {@link MarketFlag} bits. */
+    readonly flags: Uint16Array;
+    /** {@link MarketEvent}: `0` for a trade. */
+    readonly event: Uint8Array;
+}
+/**
+ * Latest known token metadata (`/v1/tokens/{mint}/info`, also `metadata` of
+ * `tokenTotals`): provider values copied verbatim from the newest row of the
+ * mint that is cheap to reach, `null` when the row lacks them. `name`,
+ * `symbol` and `uri` of stored hours come from the hour's `tokens.t2` (the
+ * newest hour that has them), cut at 128, 64 and 512 UTF-8 bytes.
+ */
+export type TokenMetadata = {
+    readonly name: string | null;
+    readonly symbol: string | null;
+    readonly uri: string | null;
+    /** Provider value in token units (may be fractional). */
+    readonly supply: number | null;
+    readonly decimals: number | null;
+    readonly tokenProgram: string | null;
+    readonly mintAuthority: string | null;
+    readonly freezeAuthority: string | null;
+    readonly quoteMint: string | null;
+    readonly quoteName: string | null;
+    readonly quoteSymbol: string | null;
+    readonly quoteUri: string | null;
+    /** Time, slot and signature of the row the values come from. */
+    readonly asOfMs: number | null;
+    readonly slot: number | null;
+    readonly signature: string | null;
+    /** `"open"`: the hour being written; `"sealed"`: a stored hour. */
+    readonly source: "sealed" | "open";
+    /** Time of the row `name`/`symbol`/`uri` come from (absent: no names known). */
+    readonly namesAsOfMs?: number | null;
+    /** One of `name`/`symbol`/`uri` was longer than its limit and was cut. */
+    readonly namesTruncated?: boolean;
+};
+/** `ctx.data.tokenInfo`: metadata and creation, no volumes. */
+export type TokenInfo = {
+    readonly mint: Address;
+    readonly known: boolean;
+    /** `null` when the creation is not in the first retained block. */
+    readonly createdMs: number | null;
+    readonly creation: Json;
+    readonly metadata: TokenMetadata | null;
+};
+/**
+ * Parameters of `/v1/volume/search`, with the same names and units
+ * (`since`/`until` in **seconds**, multiples of 60). Paging is handled by
+ * `ctx.data.volumeSearch`: there is no `cursor`.
+ */
+export interface VolumeSearchParams {
+    readonly since: number;
+    readonly until: number;
+    /** Decimal amounts of the quote, as strings (e.g. `"10.5"`). */
+    readonly min?: string;
+    readonly max?: string;
+    /** Quote mint. Default: SOL. */
+    readonly quote?: Address;
+    readonly currency?: "quote";
+    /** Page size. */
+    readonly limit?: number;
+    readonly allow_partial?: boolean;
+}
+export type JobStatus = "queued" | "running" | "succeeded" | "failed" | "cancelled" | "expired" | "acknowledged";
+/** Why an execution failed. `kind` is stable; test `code`, not `message`. */
+export interface JobFailure {
+    readonly kind: "program" | "limit" | "infrastructure" | "permission";
+    readonly code: string;
+    readonly message: string;
+}
+/**
+ * Where a job stands. Continuations are followed: `id` is the id you asked
+ * for, the status is that of the last execution of its chain.
+ */
+export type JobResult = {
+    readonly id: string;
+    readonly status: "queued" | "running";
+} | {
+    readonly id: string;
+    readonly status: "succeeded";
+    readonly result: Json;
+} | {
+    readonly id: string;
+    readonly status: "failed";
+    readonly error: JobFailure;
+} | {
+    readonly id: string;
+    readonly status: "cancelled" | "expired" | "acknowledged";
+};
+/** The job is over: its status will not change any more. */
+export declare function isFinal(result: JobResult): boolean;
+export interface StartJob {
+    /** A function of this program. */
+    readonly function: string;
+    readonly args: JsonInput;
+    /** Called with {@link CompletionArgs} when the job ends. */
+    readonly onComplete?: string;
+}
+export type Trigger = {
+    readonly kind: "trade";
+    readonly mint?: Address;
+    readonly wallet?: Address;
+} | {
+    readonly kind: "volume";
+    /**
+     * Quote volume threshold, raw units, decimal string: volume since
+     * creation, or over the last `windowMs` when given.
+     */
+    readonly thresholdRaw: string;
+    readonly mint?: Address;
+    readonly quote?: Address;
+    /**
+     * Sliding window, 1 000 to 3 600 000 ms: fires on the trade that brings
+     * the token's volume of the last `windowMs` from below the threshold to
+     * at least it; again only after it fell back below.
+     */
+    readonly windowMs?: number;
+} | {
+    readonly kind: "priceVariation";
+    readonly mint?: Address;
+    readonly mode: "rise" | "fall" | "both";
+    /**
+     * 1.01 to 11, at most four decimals: `rise` is end ≥ start × factor,
+     * `fall` end ≤ start ÷ factor. See {@link priceFactor} for percents.
+     */
+    readonly factor: number;
+    /** 15 000 to 3 600 000. */
+    readonly durationMs: number;
+} | {
+    readonly kind: "interval";
+    /** 1 000 to 86 400 000. */
+    readonly everyMs: number;
+} | {
+    /**
+     * Pool events of the live feed ({@link PoolEvent}): of `mint`, or of
+     * every token without it; of the listed kinds, or every kind.
+     */
+    readonly kind: "poolEvent";
+    readonly mint?: Address;
+    /** Non-empty, no duplicate. */
+    readonly events?: readonly PoolEventKind[];
+};
+/** Names of the pool events ({@link MarketEvent} keys other than `none`). */
+export type PoolEventKind = Exclude<keyof typeof MarketEvent, "none">;
+export interface Subscription {
+    /** Function called with a {@link Delivery}. */
+    readonly function: string;
+    readonly trigger: Trigger;
+    /** After an interruption: `latest` skips to now, `replay` catches up. */
+    readonly recovery: "latest" | "replay";
+    /** 1 to 10 000, default 1 000 (the runtime caps replay at 1 000). */
+    readonly maxReplayEvents?: number;
+}
+/**
+ * A trade as published by the live feed, in the JSON shape of the public API
+ * (`/v1/tokens/{mint}/operations`). Only the fields most programs read are
+ * typed; the others are kept as they come.
+ */
+export interface MarketOperation {
+    readonly id: string;
+    readonly mint: Address;
+    readonly trader: Address | null;
+    readonly pool: Address | null;
+    readonly side: "buy" | "sell";
+    readonly protocol: "pumpfun" | "pumpswap";
+    readonly token: {
+        readonly raw: string;
+        readonly amount: string;
+        readonly decimals: number;
+    };
+    readonly quote: {
+        readonly mint: Address;
+        readonly raw: string;
+        readonly amount: string;
+        readonly decimals: number;
+    };
+    readonly time: {
+        readonly ms: number;
+        readonly receivedMs: number | null;
+    };
+    /** `ord` is `"hour:line:op"`, the id used by {@link HourBatch}. */
+    readonly order: {
+        readonly ord: string;
+        readonly slot: number;
+    } | null;
+    /** The trade's transaction, as {@link TxColumns} (absent from older servers). */
+    readonly tx?: OperationTx;
+    readonly publishSeq: number | null;
+    readonly cumulativeQuoteRawAfter: string | null;
+    readonly [field: string]: unknown;
+}
+/**
+ * A pool event as published by the live feed: the same values as the
+ * `withEvents` row of {@link HourBatch} for the same provider row (`order.ord`
+ * is its `"hour:line:65535"` id, `code` its `market.event`).
+ */
+export interface PoolEvent {
+    readonly type: "poolEvent";
+    readonly kind: PoolEventKind;
+    /** {@link MarketEvent} value. */
+    readonly code: number;
+    readonly id: string;
+    readonly mint: Address;
+    /** For a migration, the new pumpswap pool. */
+    readonly pool: Address;
+    readonly protocol: "pumpfun" | "pumpswap";
+    /** The liquidity provider of `add` / `remove`; `null` otherwise. */
+    readonly trader: Address | null;
+    readonly signature: string | null;
+    /** Amounts added or removed; `"0"` for other kinds. */
+    readonly token: {
+        readonly raw: string;
+        readonly amount: string;
+        readonly decimals: number;
+    };
+    readonly quote: {
+        readonly mint: Address;
+        readonly raw: string;
+        readonly amount: string;
+        readonly decimals: number;
+    };
+    readonly time: {
+        readonly ms: number;
+        readonly receivedMs: number | null;
+    };
+    readonly order: {
+        readonly ord: string;
+        readonly slot: number;
+    };
+    /** The event's transaction, as {@link TxColumns} (absent from older servers). */
+    readonly tx?: OperationTx;
+    readonly publishSeq: number;
+    /** The pool after the row: raw reserves (decimal strings), fees, signer. */
+    readonly market: {
+        readonly tokenReserveRaw: string | null;
+        readonly quoteReserveRaw: string | null;
+        readonly virtualTokenReserveRaw: string | null;
+        readonly virtualQuoteReserveRaw: string | null;
+        readonly signer: Address | null;
+        readonly [field: string]: unknown;
+    };
+    readonly [field: string]: unknown;
+}
+/**
+ * The transaction of a published operation: `(hour, id)` names it, as
+ * {@link TxColumns}. `id` and `index` are `null` when unknown; `flags` are
+ * the {@link TxFlag} names.
+ */
+export interface OperationTx {
+    readonly id: number | null;
+    readonly index: number | null;
+    readonly flags: readonly (keyof typeof TxFlag)[];
+}
+/** Names of {@link TxFlag} bits, in bit order (the `tx.flags` of an operation). */
+export declare function txFlagNames(flags: number): (keyof typeof TxFlag)[];
+/**
+ * Same transaction: trades `i` and `j` of batches read `withTx: true`
+ * (possibly two batches of the same hour).
+ */
+export declare function sameTransaction(a: HourBatch, i: number, b: HourBatch, j: number): boolean;
+export type SubscriptionEvent = {
+    readonly kind: "trade";
+    readonly operation: MarketOperation;
+    /** Replays only: the chain position is unknown, provider order used. */
+    readonly orderFallback?: true;
+} | {
+    readonly kind: "poolEvent";
+    readonly event: PoolEvent;
+    readonly orderFallback?: true;
+} | {
+    readonly kind: "volume";
+    readonly operation: MarketOperation;
+    /** With `windowMs` only: the window and its volume after this trade. */
+    readonly windowMs?: number;
+    readonly windowQuoteRaw?: string;
+    readonly orderFallback?: true;
+} | {
+    readonly kind: "interval";
+    readonly scheduledAt: number;
+} | {
+    readonly kind: "priceVariation";
+    readonly signal: Json;
+} | {
+    readonly kind: "priceStatus";
+    readonly status: Json;
+} | {
+    readonly kind: "gap";
+    /**
+     * `retention`, `replay_limit`, `missing_events`, `source_reset`,
+     * `price_coverage`, `window_not_observed` (windowed `volume`: trades
+     * whose window was not observed)…; replays: `history_gap`,
+     * `not_sealed` (with `fromMs`, `toMs`).
+     */
+    readonly reason: string;
+    readonly [field: string]: unknown;
+};
+/** Arguments of a subscription handler. */
+export interface Delivery {
+    readonly kind: "events";
+    readonly subscription: string;
+    readonly events: readonly SubscriptionEvent[];
+    /** Present only in a replay: the simulated clock and the replay. */
+    readonly replay?: ReplayInfo;
+}
+/** `Delivery.replay`: what a replayed delivery adds. */
+export interface ReplayInfo {
+    readonly id: string;
+    /** 1 for the first delivery of the replay. */
+    readonly delivery: number;
+    /** Simulated time: the time of the last event of this delivery. */
+    readonly clockMs: number;
+    readonly sinceMs: number;
+    readonly untilMs: number;
+    readonly simulated: true;
+}
+/** The time a handler should use: simulated in a replay, real in live. */
+export declare function deliveryNow(delivery: Delivery): number;
+/** Body of `ctx.subscriptions.replay` and `POST programs/{p}/replay`. */
+export interface ReplayRequest {
+    /** The same spec as a live subscription (`recovery` is optional here). */
+    readonly subscription: Omit<Subscription, "recovery"> & {
+        readonly recovery?: Subscription["recovery"];
+    };
+    readonly sinceMs: number;
+    /** In the past; window up to 24 h with tokens, 1 h for every token. */
+    readonly untilMs: number;
+    /**
+     * Up to 100 tokens when the trigger names none; neither: every token.
+     */
+    readonly mints?: readonly Address[];
+    /** `subscription` of the deliveries (default `"replay"`). */
+    readonly name?: string;
+    readonly speed?: "max";
+    /**
+     * Events per delivery, 1 to 1,000 (default: 32, as live). Larger batches
+     * make a replay faster; the function then receives up to `batchSize`
+     * events per call, which live never sends. The argument, output and op
+     * limits of these deliveries are multiplied by ⌈batchSize / 32⌉ (CPU,
+     * wall time and memory stay live's). Not for `interval` (one tick per
+     * delivery).
+     *
+     * Use it for long replays or many tokens where speed matters, with a
+     * function that handles each event quickly and independently: up to ~2×
+     * faster (every token × 1 h, copy-trading function: 108 s → 53 s with
+     * 1000). A heavy function keeps smaller batches (per-delivery CPU, wall and
+     * memory do not grow). Decisions are the same whatever the batch size.
+     */
+    readonly batchSize?: number;
+    /**
+     * `ctx.storage` of a replay is its own space (empty at start, in the
+     * account's `short` quota, deleted at the end). `keepStorage` copies, at
+     * the end of a successful replay, the objects of its area `from` (default:
+     * `to`), or only `keys` (up to 1000), to the account's area `to`, within
+     * that area's quota (refused as a whole: see `ReplayRecord.keptStorage`).
+     */
+    readonly keepStorage?: {
+        readonly to: "long" | "durable";
+        readonly from?: "short" | "long" | "durable";
+        readonly keys?: readonly string[];
+    };
+}
+/**
+ * One item of a replay's live feed (`GET replays/{id}/emits?after_seq=N`,
+ * `client.replayEmits`): a `ctx.emit`, or the final record of an execution
+ * (after its emits). Reading after `seq` N frees 1..N.
+ */
+export type ReplayFeedItem = {
+    readonly seq: number;
+    readonly kind: "emitted";
+    readonly executionId: string;
+    readonly function: string;
+    readonly attempt: number;
+    readonly createdAt: number;
+    readonly data: Json;
+} | {
+    readonly seq: number;
+    readonly kind: "execution";
+    readonly execution: {
+        readonly id: string;
+        readonly status: JobStatus;
+        readonly result?: Json;
+        readonly error?: {
+            readonly code: string;
+            readonly message: string;
+        };
+        readonly logs: readonly Json[];
+        readonly [field: string]: unknown;
+    };
+};
+export interface ReplayRecord {
+    readonly id: string;
+    readonly program: string;
+    readonly status: "running" | "cancelling" | "succeeded" | "failed" | "cancelled";
+    readonly sinceMs: number;
+    readonly untilMs: number;
+    readonly progress: {
+        readonly simulatedMs: number;
+        /** 0 to 1. */
+        readonly fraction: number;
+        readonly eventsRead: number;
+        readonly eventsDelivered: number;
+        readonly deliveries: number;
+        readonly gaps: number;
+        readonly orderFallbacks: number;
+        readonly historyReadBytes: number;
+    };
+    readonly usage: {
+        readonly cpuMs: number;
+        readonly readBytes: number;
+        readonly attempts: number;
+    };
+    readonly error: {
+        readonly code: string;
+        readonly message: string;
+    } | null;
+    readonly lastExecution: string | null;
+    /** What `keepStorage` copied at the end, or why nothing was. */
+    readonly keptStorage?: {
+        readonly copied: true;
+        readonly objects: number;
+        readonly bytes: number;
+    } | {
+        readonly copied: false;
+        readonly error: {
+            readonly code: string;
+            readonly message: string;
+        };
+    };
+    readonly [field: string]: unknown;
+}
+/** Arguments of an `onComplete` handler. */
+export interface CompletionArgs {
+    readonly kind: "completion";
+    readonly executionId: string;
+    readonly status: JobStatus;
+}
+export declare function isDelivery(args: unknown): args is Delivery;
+export declare function isCompletion(args: unknown): args is CompletionArgs;
+export interface ExecutionInfo {
+    readonly id: string;
+    /** Shared by an execution, its continuations, children and retries. */
+    readonly workflow: string;
+    readonly program: string;
+    /** SHA-256 of the bundle. */
+    readonly version: string;
+    /** 1 for the first attempt. */
+    readonly attempt: number;
+}
+/** Lakebed's `StoragePutOptions` (every field optional here). */
+export interface StoragePutOptions {
+    /** `type/subtype`; parameters are dropped. Default: `text/plain` for a string, else `application/octet-stream`. */
+    readonly contentType?: string;
+    /** Up to 16 entries; names `[a-z0-9-]{1,64}`, values printable ASCII (≤ 1024). Served as `x-meta-<name>` over HTTP. */
+    readonly metadata?: Readonly<Record<string, string>>;
+    /** Fail with `already_exists` instead of replacing an object. */
+    readonly ifAbsent?: boolean;
+    /**
+     * Write only if the object still has this etag (`"*"`: any existing
+     * object), else `precondition_failed`. Checked atomically with the write.
+     */
+    readonly ifMatch?: string;
+}
+/** Lakebed's `StorageObjectHead`, plus where the object stands in time. */
+export interface StorageObjectHead {
+    readonly key: string;
+    readonly size: number;
+    readonly contentType: string;
+    readonly metadata: Readonly<Record<string, string>>;
+    /** ISO 8601 of the last write. */
+    readonly lastModified: string;
+    /** Last write (ms since epoch). Reads do not change it. */
+    readonly writtenAt: number;
+    /** `writtenAt` + the area's lifetime: the object is gone after it. `null` in `durable`. */
+    readonly expiresAt: number | null;
+    /** Changes at every write (HTTP `ETag`). */
+    readonly etag: string;
+}
+/** Lakebed's `StorageReadResult`. With a range, `body` is that range and `size` the whole object's. */
+export interface StorageReadResult extends StorageObjectHead {
+    readonly body: Uint8Array;
+}
+/** Lakebed's `StorageObjectSummary` (what `list` answers), plus expiry. */
+export interface StorageObjectSummary {
+    readonly key: string;
+    readonly size: number;
+    readonly contentType: string;
+    readonly lastModified: string;
+    readonly expiresAt: number | null;
+}
+/**
+ * What `list` answers: Lakebed's array of summaries, plus `cursor` (pass it
+ * as `after` for the next page, `null` at the end) and `truncated`.
+ */
+export type StorageListPage = StorageObjectSummary[] & {
+    readonly cursor: string | null;
+    readonly truncated: boolean;
+};
+/** Lakebed's `StorageLedgerUsage` for one area of the account, with its limits. */
+export interface StorageUsage {
+    readonly area: "short" | "long" | "durable";
+    readonly initialized: boolean;
+    /** committed + reserved + uncertain + deleting: what the quota counts. */
+    readonly usedBytes: number;
+    readonly reservedBytes: number;
+    /** Uploads in progress. */
+    readonly uncertainBytes: number;
+    readonly committedBytes: number;
+    readonly deletingBytes: number;
+    readonly objects: number;
+    readonly reservations: readonly {
+        readonly key: string;
+        readonly size: number;
+        readonly state: "reserved" | "writing" | "deleting";
+        readonly updatedAt: string;
+    }[];
+    readonly quotaBytes: number;
+    /** Lifetime of an object after its last write; `null` in `durable` (never expires). */
+    readonly ttlMs: number | null;
+    readonly maxObjectBytes: number;
+}
+/** Bytes to store: a string is stored as UTF-8. */
+export type StorageBody = Uint8Array | ArrayBuffer | ArrayBufferView | string;
+/** Writes one object piece by piece; nothing is visible before `close()`. */
+export interface StorageWriter {
+    write(chunk: StorageBody): Promise<void>;
+    /** Makes the object visible (replacing any previous one). */
+    close(): Promise<StorageObjectHead>;
+    /** Drops what was written (also done when the execution ends). */
+    abort(): Promise<void>;
+}
+/**
+ * One storage area of the account, shared by all its programs and readable
+ * over HTTP (`/v1/functions/storage/{area}/{key}`). Keys are 1 to 512 bytes
+ * of UTF-8 without control characters (`/` is an ordinary character: use it
+ * for prefixes). Each object expires a fixed time after its last write;
+ * reads do not extend it. Writes are immediate and not undone if the
+ * execution fails afterwards.
+ */
+export interface StorageArea {
+    /** Lakebed's `put`. Answers the new head. */
+    put(key: string, body: StorageBody, options?: StoragePutOptions): Promise<StorageObjectHead>;
+    /** Lakebed's `get`; `range` reads part of a large object. `null` when absent or expired. */
+    get(key: string, range?: {
+        offset?: number;
+        length?: number;
+    }): Promise<StorageReadResult | null>;
+    head(key: string): Promise<StorageObjectHead | null>;
+    /** Idempotent. With `ifMatch`, only if the object still has that etag (`precondition_failed`). */
+    delete(key: string, options?: {
+        ifMatch?: string;
+    }): Promise<void>;
+    /**
+     * Lakebed's `list`: keys starting with `prefix`, in byte order, at most
+     * `maxObjects` (1000). For the next page, pass the last key as `after`.
+     */
+    list(prefix?: string, options?: {
+        maxObjects?: number;
+        after?: string;
+    }): Promise<StorageListPage>;
+    usage(): Promise<StorageUsage>;
+    /** Helpers. */
+    getText(key: string): Promise<string | null>;
+    getJSON(key: string): Promise<Json>;
+    /** Stored as `application/json`. */
+    putJSON(key: string, value: JsonInput, options?: Omit<StoragePutOptions, "contentType">): Promise<StorageObjectHead>;
+    writer(key: string, options?: StoragePutOptions): Promise<StorageWriter>;
+}
+export interface Context {
+    readonly execution: ExecutionInfo;
+    readonly data: {
+        /**
+         * Trades of a wallet, one hour per batch, oldest first. Each `next()` reads
+         * one hour: break out of the loop to stop reading.
+         */
+        walletTrades(wallet: Address, query: TradeQuery): AsyncIterable<HourBatch>;
+        /** Trades of a token, one hour per batch, oldest first. */
+        tokenTrades(mint: Address, query: TradeQuery): AsyncIterable<HourBatch>;
+        /** Same JSON as `/v1/tokens/{mint}/totals` (with `metadata`). */
+        tokenTotals(mint: Address, options?: {
+            quote?: Address;
+        }): Promise<Json>;
+        /**
+         * Same JSON as `/v1/tokens/{mint}/info`: latest known metadata and the
+         * creation, at most two blocks read (no volumes).
+         */
+        tokenInfo(mint: Address): Promise<TokenInfo>;
+        /** Pages of `/v1/volume/search`, in its JSON shape. */
+        volumeSearch(params: VolumeSearchParams): AsyncIterable<Json>;
+    };
+    /** Private JSON state of the program, kept between executions. */
+    readonly state: {
+        /** `null` when the key is absent. */
+        get(key: string): Promise<Json>;
+        set(key: string, value: JsonInput): Promise<void>;
+        delete(key: string): Promise<void>;
+    };
+    readonly jobs: {
+        /** Starts a function of this program in parallel; returns its id. */
+        start(job: StartJob): Promise<string>;
+        /**
+         * Waits until every listed job is final, or until `timeoutMs`. Results are
+         * in the order of `ids`; on timeout, some are still `queued`/`running`.
+         * Waiting costs no CPU but counts in the 60 s wall time.
+         */
+        wait(ids: string | readonly string[], options?: {
+            timeoutMs?: number;
+        }): Promise<JobResult[]>;
+        /** Current status of a job of this account, without waiting. */
+        result(id: string): Promise<JobResult>;
+        /**
+         * Ends this execution and schedules the same function again with `args`
+         * (same version, same workflow budget). Use as `return ctx.jobs.continue(…)`.
+         */
+        continue(args: JsonInput): Promise<string>;
+    };
+    /**
+     * Files of the account, kept between executions: `short` (1 GiB, 24 h
+     * after the last write), `long` (500 MiB, 7 days after the last write) and
+     * `durable` (50 MiB, never expires).
+     */
+    readonly storage: {
+        readonly short: StorageArea;
+        readonly long: StorageArea;
+        /** 50 MiB, never expires: open positions, order journals. */
+        readonly durable: StorageArea;
+    };
+    readonly subscriptions: {
+        set(name: string, subscription: Subscription): Promise<void>;
+        remove(name: string): Promise<void>;
+        /**
+         * Replays history to a function of this program, in the live delivery
+         * format. Refused inside a replay.
+         */
+        replay(request: ReplayRequest): Promise<ReplayRecord>;
+    };
+    /** Calls another function of this program now, in this execution and budget. */
+    invoke(name: string, args: JsonInput): Promise<Json>;
+    /** Adds a diagnostic to the execution record (counts in the output limit). */
+    log(value: JsonInput): Promise<void>;
+    /** Publishes a provisional event on the account stream (counts in the output limit). */
+    emit(value: JsonInput): Promise<void>;
+    readonly webhook: {
+        /**
+         * Sends `payload` to the account's webhook URL now (not when the
+         * execution ends). JSON, at most 16 KiB, counted in the output limit; at
+         * most 32 calls per execution. Rejects with `webhook_not_configured`,
+         * `webhook_limit` or `webhook_payload_too_large`, and with
+         * `webhook_queue_full` when 1000 messages wait, unless
+         * `{ onFull: "drop" }`: the message is then dropped (counted in
+         * `dropped` of the delivery log) and the call answers `dropped: true`.
+         * A retried execution sends again: the message carries `executionId`,
+         * `attempt` and `index` to tell.
+         */
+        send(payload: JsonInput, options?: {
+            onFull?: "fail" | "drop";
+        }): Promise<{
+            id: string;
+            seq: number;
+            dropped: false;
+        } | {
+            id: null;
+            seq: null;
+            dropped: true;
+        }>;
+    };
+}
+type HandlerReturn = JsonInput | void | Promise<JsonInput | void>;
+/**
+ * A function of the program. `args` can be annotated with a narrower type;
+ * validate it anyway: callers send any JSON.
+ */
+export type Handler = {
+    bivarianceHack(ctx: Context, args: Json): HandlerReturn;
+}["bivarianceHack"];
+export interface Program {
+    readonly functions: Readonly<Record<string, Handler>>;
+    /** Bump it with a `migration` when the shape of the state changes. */
+    readonly stateVersion?: number;
+    /** Name of a function receiving `{ from, to, state }` and returning the new state. */
+    readonly migration?: string;
+    /** Declared at deploy; `ctx.subscriptions` can change them later. */
+    readonly subscriptions?: Readonly<Record<string, Subscription>>;
+}
+/** Marker read by the sandbox at deploy: programs without it are refused. */
+export declare const SDK_MARKER = "__zyrkSdk";
+export declare const SDK_VERSION = "0.2";
+export declare function defineProgram<const T extends Program>(program: T): T;
+/** Id of trade `i`: `"{hour}:{line}:{op}"`, unique and stable. */
+export declare function tradeId(batch: HourBatch, i: number): string;
+export interface TradeKey {
+    readonly hour: number;
+    readonly line: number;
+    readonly op: number;
+}
+/** Parses `"{hour}:{line}:{op}"`; throws a `RangeError` on anything else. */
+export declare function parseTradeId(id: string): TradeKey;
+/** Provider order of two trade ids, for `Array#sort`. */
+export declare function compareTradeIds(a: string, b: string): number;
+/**
+ * Id of a live-feed operation, in the {@link tradeId} format (`operation.id`
+ * as delivered by funrun, else `order.ord`); `null` without order.
+ */
+export declare function operationTradeId(operation: MarketOperation): string | null;
+/**
+ * `priceVariation` factor for a percent change: `priceFactor(20)` is 1.2
+ * (rise of 20 %), `priceFactor(-10)` is 1.1111 (fall of 10 %: 1 / 0.9,
+ * rounded down to four decimals so that an exact 10 % fall fires). Throws a
+ * `RangeError` outside 1.01 to 11 (+1 % to +1 000 %, −1 % to −90.9 %).
+ */
+export declare function priceFactor(percent: number): number;
+/** Entry `index` of the batch dictionary; `null` for {@link NO_ADDRESS}. */
+export declare function addressAt(batch: HourBatch, index: number): Address | null;
+/**
+ * Index of `address` in the batch dictionary, or {@link NO_ADDRESS}. Compare
+ * columns to it to test many rows without building strings.
+ */
+export declare function addressIndex(batch: HourBatch, address: Address): number;
+export declare function mintOf(batch: HourBatch, i: number): Address;
+export declare function traderOf(batch: HourBatch, i: number): Address | null;
+export declare function poolOf(batch: HourBatch, i: number): Address | null;
+export declare function quoteMintOf(batch: HourBatch, i: number): Address;
+export declare function sideOf(batch: HourBatch, i: number): "buy" | "sell";
+export declare function protocolOf(batch: HourBatch, i: number): "pumpfun" | "pumpswap";
+/**
+ * On-chain order of trades `i` and `j` of batches with `withOrder: true`
+ * (possibly two batches), for `Array#sort`: slot, transaction, event; a
+ * trade of unknown order after the known ones of its slot. Batches of
+ * consecutive hours can overlap by a few slots (the provider files a trade
+ * by its reception): sort across batches with this when that matters.
+ */
+export declare function compareChainOrder(a: HourBatch, i: number, b: HourBatch, j: number): number;
+/** First millisecond of an hour number. */
+export declare function hourStartMs(hour: number): number;
+/** One trade as an object. Convenient, but slower than reading the columns. */
+export interface Trade {
+    readonly id: string;
+    readonly hour: number;
+    readonly line: number;
+    readonly op: number;
+    readonly slot: number;
+    readonly timeMs: number;
+    readonly receivedMs: number | null;
+    readonly side: "buy" | "sell";
+    readonly protocol: "pumpfun" | "pumpswap";
+    readonly mint: Address;
+    readonly pool: Address | null;
+    readonly trader: Address | null;
+    readonly quoteMint: Address;
+    readonly tokenRaw: bigint;
+    readonly tokenDecimals: number;
+    readonly quoteRaw: bigint;
+    readonly quoteDecimals: number;
+    readonly tokenAmount: number;
+    readonly quoteAmount: number;
+    readonly price: number | null;
+    readonly priceSol: number | null;
+    readonly priceUsd: number | null;
+    readonly quotePriceUsd: number | null;
+    readonly usdValue: number | null;
+    readonly signature: string | null;
+}
+/** Row `i` of a batch as a {@link Trade} (`NaN` becomes `null`). */
+export declare function tradeAt(batch: HourBatch, i: number): Trade;
+/**
+ * Stable codes of errors thrown inside a program by `ctx` calls. Test
+ * `error.code`; `message` is for humans and may change.
+ */
+export type SdkErrorCode = "invalid_window" | "partial_coverage" | "history_preparing" | "storage_busy" | "history_unavailable" | "read_limit" | "read_time_limit" | "invalid_argument" | "unknown_function" | "execution_not_found" | "state_value_too_large" | "state_limit" | "children_limit" | "subscription_limit" | "price_subscription_limit" | "output_limit" | StorageErrorCode | (string & {});
+/** Lakebed's `StorageErrorCode`, plus `already_exists`, `value_changed`, `io_limit`, `upload_limit`, `precondition_failed`. */
+export type StorageErrorCode = "quota_exceeded" | "too_large" | "not_found" | "invalid_request" | "forbidden" | "unavailable" | "blocked_type" | "already_exists" | "value_changed" | "io_limit" | "upload_limit" | "precondition_failed";
+/** HTTP status of each storage code (Lakebed's for its seven). */
+export declare const STORAGE_STATUS_BY_CODE: Readonly<Record<StorageErrorCode, number>>;
+/** Error thrown by a `ctx` call. `retryAfterMs` comes with `storage_busy`/`history_preparing`. */
+export interface SdkError extends Error {
+    readonly code: SdkErrorCode;
+    readonly retryAfterMs?: number;
+}
+/** `true` when `error` was thrown by a `ctx` call (optionally with this `code`). */
+export declare function isSdkError(error: unknown, code?: SdkErrorCode): error is SdkError;
+export {};