@hyperbridge/simplex 0.16.11 → 0.16.13

package/dist/index.d.ts

@@ -2,8 +2,8 @@ import { EventEmitter as EventEmitter$1 } from 'node:events';
 import { HexString, ERC7821Call, ChainConfig, Order, TokenInfo, IntentsCoprocessor, ExecutionResult, IntentGateway, FillOptions, FillerConfig as FillerConfig$1 } from '@hyperbridge/sdk';
 import { PublicClient, Hash, AbiEvent, BlockNumber, BlockTag, GetLogsParameters, GetLogsReturnType, WalletClient, Transport, Chain } from 'viem';
 import { LocalAccount, Account } from 'viem/accounts';
-import { L as LoggerContext, a as LogLevel, b as Logger, A as ActivityStore, c as ActivityInsert, d as ActivityEvent, O as OrderHistoryPage, W as WalletTx, e as LimitOrderStore, f as LimitOrder, g as LimitOrderFilter, B as BidStore, S as SimplexDataStore, h as LimitOrderFill, i as StoredBid, j as LogSink, k as BidStats, l as StateStore } from './types-B5zkFhxR.js';
-export { m as ActivityType, n as BidInsert, o as LimitOrderFillInsert, p as LimitOrderHold, q as LimitOrderInsert, r as LimitOrderPosting, s as LimitOrderSide, t as LimitOrderStatus, u as OperatorNotification, R as RuntimeState, v as WalletTxKind, w as addLogSink, x as configureLogger, y as getLogger } from './types-B5zkFhxR.js';
+import { L as LoggerContext, a as LogLevel, b as Logger, A as ActivityStore, c as ActivityInsert, d as ActivityEvent, O as OrderHistoryPage, W as WalletTx, e as LimitOrderStore, f as LimitOrder, g as LimitOrderFilter, B as BidStore, S as SimplexDataStore, h as LimitOrderFill, i as StoredBid, j as LogSink, k as BidStats, l as StateStore, I as InventoryStore } from './types-BISgqJhM.js';
+export { m as ActivityType, n as BidInsert, o as InventorySnapshot, p as LimitOrderFillInsert, q as LimitOrderFillRecord, r as LimitOrderHold, s as LimitOrderInsert, t as LimitOrderPosting, u as LimitOrderSide, v as LimitOrderStatus, w as OperatorNotification, R as RuntimeState, x as WalletTxKind, y as addLogSink, z as configureLogger, C as getLogger } from './types-BISgqJhM.js';
 import { ChannelCredentials } from '@grpc/grpc-js';
 import { EventEmitter } from 'events';
 import Decimal$1, { Decimal } from 'decimal.js';
@@ -158,6 +158,11 @@ interface FillerConfig {
      * See `bidValiditySeconds` in filler-toml for why this bound matters.
      */
     bidValiditySeconds?: number;
+    /**
+     * Order size in USD below which `order.fees` must cover the execution cost.
+     * Defaults to 20. See `minOrderSizeUsd` in filler-toml.
+     */
+    minOrderSizeUsd?: number;
     /**
      * Overfill protection knobs. If omitted, defaults are used
      * (maxOverfillBps=500, maxConsecutiveClamps=3).
@@ -343,6 +348,11 @@ declare class FillerConfigService {
      * Hyperbridge-side retraction does not reach the destination chain.
      */
     getBidValiditySeconds(): number;
+    /**
+     * The order size, in USD, below which `order.fees` must cover the execution cost.
+     * Defaults to 20. An order at or above it is filled whatever fees it carries.
+     */
+    getMinOrderSizeUsd(): number;
     /** Ceiling bps above user-requested output. Default 500 (5%). */
     getMaxOverfillBps(): bigint;
     /** Consecutive clamped evaluations before the strategy halts. Default 3. */
@@ -1595,6 +1605,85 @@ declare class BalanceProvider extends EventEmitter$1 {
     private trackHyperbridgeBalance;
 }
 
+/** The stretch of time a summary covers. Each is cut into buckets of one size. */
+type ProfitPeriod = "7d" | "30d" | "12w" | "12m" | "all";
+type ProfitBucket = "day" | "week" | "month" | "year";
+/** What a stretch of fills came to, in dollars at the latest rate. Unpriced tokens are left out. */
+interface ProfitFigures {
+    /** What the stretch's fills added to inventory, less what they took out of it. */
+    profitUsd: number;
+    /** The inventory held when the stretch began. Null when nothing within reach of then records it. */
+    startInventoryUsd: number | null;
+    /** `profitUsd` over `startInventoryUsd`, as a percentage. Null without a starting inventory. */
+    returnPct: number | null;
+    /**
+     * What moved in and out over the stretch other than through fills, net: deposits, withdrawals,
+     * fees and vault yield. Null when the indexer has no reading for both ends of the stretch.
+     */
+    transfersUsd: number | null;
+    boughtUsd: number;
+    soldUsd: number;
+    buys: number;
+    sells: number;
+}
+interface ProfitBucketFigures extends ProfitFigures {
+    /** When the bucket starts, in milliseconds since the epoch. */
+    start: number;
+}
+/** One book's buys against its sells over the period, in the book's own tokens. */
+interface BookProfit {
+    book: string;
+    base: string;
+    quote: string;
+    /** Base bought and sold in the period. */
+    bought: number;
+    sold: number;
+    /** Quote per base, averaged over the period's buys and its sells. Null for a side with none. */
+    averageBuy: number | null;
+    averageSell: number | null;
+    /** How far the average sell sits above the average buy, as a percentage. Null without both. */
+    spreadPct: number | null;
+    /** What the period's fills did to the base and the quote held: positive is more than before. */
+    baseChange: number;
+    quoteChange: number;
+    /** The rate the book's tokens are valued at: midway between its latest buy and latest sell. */
+    rate: number | null;
+    /** Both changes in dollars. Null when the book's tokens have no dollar price. */
+    profitUsd: number | null;
+}
+/** The inventory a period began with, token by token. */
+interface StartingInventory {
+    /** The instant it describes, in milliseconds since the epoch. */
+    at: number;
+    /** A stored snapshot, or the balances as they stand now. Either is adjusted by what happened between. */
+    source: "snapshot" | "balances";
+    /** When that record was taken. */
+    recordedAt: number;
+    usd: number;
+    tokens: Array<{
+        symbol: string;
+        amount: number;
+        usd: number | null;
+    }>;
+}
+interface Profitability {
+    period: ProfitPeriod;
+    bucket: ProfitBucket;
+    /** The start of the first bucket and the moment the summary was taken, in milliseconds. */
+    from: number;
+    to: number;
+    totals: ProfitFigures;
+    /** One entry per bucket, oldest first, including buckets nothing happened in. */
+    series: ProfitBucketFigures[];
+    books: BookProfit[];
+    /** Null when there is no snapshot, and the period began more than {@link BALANCES_REACH_MS} ago. */
+    startInventory: StartingInventory | null;
+    /** Fills in the period priced at their order's rate, because they kept no record of what they took in. */
+    estimatedFills: number;
+    /** Tokens the period touched that have no dollar price, and so are in none of the dollar figures. */
+    unpricedTokens: string[];
+}
+
 /**
  * Wire contracts between the UI server and the browser bundle. The server
  * types its response literals with these and `ui/src` imports them type-only,
@@ -1822,6 +1911,16 @@ interface FillerTomlConfig {
          * Configured in seconds but written on-chain in blocks, converted per destination chain.
          */
         bidValiditySeconds?: number;
+        /**
+         * The order size, in USD, below which `order.fees` must cover the execution cost
+         * (fill gas plus, cross-chain, the relayer fee). Defaults to 20.
+         *
+         * An order worth at least this much is filled whatever fees it carries: the margin
+         * in the limit order that prices it pays for the gas. On a smaller order that
+         * margin is too thin to, so the fees have to. Set to 0 to never check fees. An
+         * order nothing can put a dollar figure on is treated as below it.
+         */
+        minOrderSizeUsd?: number;
         /**
          * Remote access: an outbound SSH tunnel to a rendezvous relay so a phone's
          * SSH client can reach the local web UI. Off unless `enabled = true`; the
@@ -2024,6 +2123,8 @@ interface BidPlan {
     fillerOutputs: TokenInfo[];
     /** The take signed beside each output: the escrow this bid's fill earns. */
     fillerInputs: TokenInfo[];
+    /** The decimals `fillerInputs[leg]` is counted in: the input token's, on the order's source chain. */
+    inputDecimals?: number;
     fundingCalls: ERC7821Call[];
     partialFill: boolean;
     profit: number;
@@ -2113,6 +2214,17 @@ declare class CacheService {
     isPartialFill(orderId: string): boolean;
     setPartialFill(orderId: string, partial: boolean): void;
     clearPartialFill(orderId: string): void;
+    /**
+     * Whether the strategy's completed evaluation let a bid through without holding
+     * `order.fees` to the execution cost, because the order is at or above the
+     * operator's minimum size.
+     *
+     * Written and cleared the way {@link isPartialFill} is, for the same reason: the
+     * caller exempts such an order from its profit floor.
+     */
+    isFeeCheckWaived(orderId: string): boolean;
+    setFeeCheckWaived(orderId: string, waived: boolean): void;
+    clearFeeCheckWaived(orderId: string): void;
     getFeeTokenWithDecimals(chain: string): {
         address: HexString;
         decimals: number;
@@ -2670,6 +2782,52 @@ interface Book {
     base: string;
     quote: string;
 }
+/** Live price levels. All prices and sizes are decimal integer strings at 1e18. */
+interface OrderbookLevel {
+    fillChain: string;
+    priceBucket: string;
+    price: string;
+    worstPrice: string;
+    baseSize: string;
+    quoteSize: string;
+    orderCount: number;
+    solverCount: number;
+}
+interface OrderbookSnapshot extends Book {
+    /** Best first: bids descending, asks ascending. */
+    bids: OrderbookLevel[];
+    asks: OrderbookLevel[];
+    /** True backing liquidity, in quote for bids and base for asks. */
+    bidLiquidity: string;
+    askLiquidity: string;
+    /** Price bucket width, quote per 1 base at 1e18; null when the orderbook does not report one. */
+    granularity: string | null;
+}
+/** One solver's order inside a price level. Prices and sizes are decimal integer strings at 1e18. */
+interface OrderbookLevelOrder {
+    solver: string;
+    commitment: string;
+    fillChain: string;
+    price: string;
+    /** What the order publishes as depth, in the token its side pays out: quote for bids, base for asks. */
+    advertisedSize: string;
+    /** The signed output before any balance cap, in the same token as `advertisedSize`. */
+    quotedAmount: string;
+    /** True when the solver's balance, not the quote, binds `advertisedSize`. */
+    resized: boolean;
+    expiresAt: string;
+    acceptedSources: string[];
+}
+interface OrderbookLevelQuery {
+    side: "BID" | "ASK";
+    fillChain: string;
+    priceBucket: string;
+    sourceChain?: string;
+}
+interface OrderbookFilters {
+    sourceChain?: string;
+    fillChain?: string;
+}
 interface TokenMinSize {
     symbol: string;
     size: string;
@@ -2820,6 +2978,14 @@ declare class OrderbookClient {
     constructor(url: string, requestTimeoutMs: number, loggers?: LoggerContext);
     /** The limits to validate against before posting, plus the books on offer. */
     limits(): Promise<OrderbookLimits>;
+    /** The public book across all solvers, restricted to the selected route. */
+    snapshot(id: string, filters?: OrderbookFilters): Promise<OrderbookSnapshot | null>;
+    /**
+     * The orders behind one price level. The orderbook filters orders by side and route but not by
+     * price bucket, so this walks the side's orders on the level's fill chain and keeps the bucket.
+     * Null when the book does not exist.
+     */
+    levelOrders(id: string, level: OrderbookLevelQuery): Promise<OrderbookLevelOrder[] | null>;
     submitOrder(userOp: HexString): Promise<SubmitOrderResult>;
     /**
      * The entry this solver holds at `commitment`, or null when it holds none.
@@ -2994,6 +3160,10 @@ declare class LimitOrderService {
      */
     private withdraw;
     private signAndCancel;
+    /** Public market levels read through the configured orderbook client. */
+    orderbookSnapshot(book: string, filters?: OrderbookFilters): Promise<OrderbookSnapshot | null>;
+    /** Every solver's order behind one public price level. */
+    orderbookLevelOrders(book: string, level: OrderbookLevelQuery): Promise<OrderbookLevelOrder[] | null>;
     /**
      * The pairs an order can be written against, the smallest payout each token may carry, and
      * the tokens the orderbook registers on each chain.
@@ -3320,6 +3490,13 @@ declare class IntentFiller {
     private verifyOrderOnSource;
     private handleNewOrder;
     private evaluateOrder;
+    /**
+     * The destination chain's latest block number, the clock `order.deadline` is read on.
+     *
+     * Null when the read fails. That is not an answer about the order, so evaluation goes
+     * on: the gas estimate simulates the same deadline check and refuses an expired order.
+     */
+    private destinationHead;
     /**
      * Whether the strategy's evaluation concluded in a deliberate partial fill.
      *
@@ -3330,6 +3507,12 @@ declare class IntentFiller {
      * and filled them.
      */
     private fillsPartially;
+    /**
+     * Whether the strategy's evaluation let a bid through without the fee check, because
+     * the order is at or above the operator's minimum size. Read from a flag the strategy
+     * sets only once it has an answer, as {@link fillsPartially} is.
+     */
+    private feeCheckWaived;
     private executeOrder;
     private handleOrderFilledOnChain;
     /**
@@ -3521,7 +3704,8 @@ declare class FXFiller implements FillerStrategy {
      * - Treat a payout below the ask as a partial fill, which only orders
      *   without output calldata and without an earlier partial fill allow.
      * - Cap each payout by the filler's balance plus funding-venue withdrawals,
-     *   then gate it on fees (full fills) and the same-asset spread.
+     *   then gate it on fees (full fills of orders below `minOrderSizeUsd`) and the
+     *   same-asset spread.
      * - Cache the resulting bids for later use in `executeOrder`.
      */
     calculateProfitability(order: Order): Promise<number>;
@@ -3724,6 +3908,10 @@ interface FillerRuntime {
     rebalancingService?: RebalancingService;
     resolvedChains: ResolvedChainConfig[];
     fillerAddress: HexString;
+    /** The indexer this filler reads history from: order details, and what it held at past moments. */
+    indexerUrl: string;
+    /** A token's registry symbol and on-chain decimals, where either can be had. */
+    describeToken: TokenDescriber;
     watchOnly?: Record<number, boolean>;
     config: FillerTomlConfig;
     /** Where the config came from, when it came from a file. */
@@ -3932,6 +4120,7 @@ interface SimplexStatus {
 declare class LimitOrderController {
     private runtime;
     private emit;
+    private indexed?;
     constructor(runtime: FillerRuntime, emit: LimitOrderEmitter);
     private get service();
     list(filter?: LimitOrderFilter): Promise<LimitOrder[]>;
@@ -3948,12 +4137,32 @@ declare class LimitOrderController {
         fills: LimitOrderFill[];
         bids: StoredBid[];
     } | null>;
+    /**
+     * What the operator's buys and sells earned over `period`, bucketed on a clock
+     * `tzOffsetMinutes` behind UTC.
+     *
+     * Profit is the change the period's fills made to what the solver holds, and
+     * it is compared with the inventory the period began with. That inventory
+     * comes from the stored snapshots and, when the balances have been read in
+     * full, from what is held now, each carried to the period's start by what
+     * moved between. The indexer says what moved, deposits and withdrawals
+     * included, wherever it has followed the solver; elsewhere the fills and
+     * sends on record stand in. It answers whether or not an orderbook is
+     * configured, and whether or not the indexer does.
+     */
+    profitability(period: ProfitPeriod, tzOffsetMinutes?: number): Promise<Profitability>;
+    /** One reader for the life of the filler, so the readings it has already fetched are kept. */
+    private indexerInventory;
     /** The pairs the orderbook lists, the smallest payout each token may carry, and its tokens per chain. */
     books(): Promise<{
         books: Book[];
         minOrderSizes: TokenMinSize[];
         chains: ChainInfo[];
     }>;
+    /** Public bids and asks across solvers, optionally restricted to a route. */
+    orderbookSnapshot(book: string, filters?: OrderbookFilters): Promise<OrderbookSnapshot | null>;
+    /** Every solver's order behind one public price level. */
+    orderbookLevelOrders(book: string, level: OrderbookLevelQuery): Promise<OrderbookLevelOrder[] | null>;
     /** Creates the order, posts it, and reports what the orderbook made of it. */
     create(request: CreateLimitOrderRequest): Promise<PostedLimitOrder>;
     cancel(id: string): Promise<CancelledLimitOrder>;
@@ -4195,20 +4404,12 @@ declare class Simplex extends EventEmitter$1 {
     get internals(): FillerRuntime;
 }
 
-/**
- * Process-local data store — the default when `Simplex.start` is given no
- * `data` option.
- *
- * Nothing survives the process. That is fine for tests, short-lived embedded
- * fillers and watch-only observers, but a filler that submits bids should use a
- * durable store: a lost bid record is a Hyperbridge deposit nobody retracts.
- * Settled rows are evicted past a cap; live bids (deposits still reclaimable) are never dropped.
- */
 declare class MemoryDataStore implements SimplexDataStore {
     readonly bids: BidStore;
     readonly activity: ActivityStore;
     readonly state: StateStore;
     readonly limitOrders: LimitOrderStore;
+    readonly inventory: InventoryStore;
 }
 
 /**
@@ -4275,4 +4476,4 @@ declare class OrderScanner implements OrderScanner$1 {
     private closeNow;
 }
 
-export { ActivityEvent, ActivityInsert, ActivityStore, type AllowlistConfig, type AssetBalanceRow, AssetController, type AssetDefinition, type AuthorizationRequest, type BalanceIssue, type BalanceSnapshot, BidStats, BidStore, type BinanceConfig, type CancelledLimitOrder, type ChainBalanceRow, type ChainConfirmationPolicy, ChainController, type ChainInput, type ChainView, type CreateLimitOrderRequest, type CurveConfig, type CurvePoint, type DerivingSigner, type Eip7702Authorization$1 as Eip7702Authorization, type FillerConfigFile, type FillerTomlConfig, type HyperbridgeBalance, LimitOrder, LimitOrderController, LimitOrderFill, LimitOrderFilter, LimitOrderStore, LimitOrderValidationError, LogLevel, LogSink, Logger, LoggerContext, MemoryDataStore, type MpcVaultSignerConfig, OrderScanner, type OrderScanner$1 as OrderScannerContract, type OrderScannerHandlers, type OrderScannerOptions, type PairConfig, PairController, type PairView, type PostedLimitOrder, type PostingOutcome, type PrivateKeySignerConfig, type QueueConfig, RebalanceController, type RebalancingConfig, type ResolvedChainConfig, type ScannedFill, type ScannedOrder, type ScannerChainConfig, type SecretPhraseSignerConfig, type Signature, type Signer, type SignerConfig, type SignerTransaction, SignerType, Simplex, type SimplexConfig, SimplexDataStore, type SimplexEvents, type SimplexOptions, type SimplexStatus, type SolverWork, StateStore, StoredBid, type Subscription, type TurnkeySignerConfig, type TypedDataPayload, USD_STABLE_SYMBOLS, type UserProvidedChainConfig, type VaultBalanceRow, VaultController, type VaultSweepDeposit, type VaultSweepResult, type VaultSweepSkip, type VaultSweepSkipReason, type VaultSweepSubmission, type VaultToml, type VaultTomlConfig, WalletController, WalletTx, assertConfirmationCoverage, canDerive, createSigner, digestSigner, formatChainKey, isRegistrySymbol, mpcVaultSigner, normalizeSymbol, parseChainKey, pickAnchorStable, privateKeySigner, registrySymbols, secretPhraseSigner, turnkeySigner, validateAssetDefinitions, validateConfig, validatePairConfigs, validateSecretPhrase, validateSignerConfig, validateVaultToml, viemSigner };
+export { ActivityEvent, ActivityInsert, ActivityStore, type AllowlistConfig, type AssetBalanceRow, AssetController, type AssetDefinition, type AuthorizationRequest, type BalanceIssue, type BalanceSnapshot, BidStats, BidStore, type BinanceConfig, type BookProfit, type CancelledLimitOrder, type ChainBalanceRow, type ChainConfirmationPolicy, ChainController, type ChainInput, type ChainView, type CreateLimitOrderRequest, type CurveConfig, type CurvePoint, type DerivingSigner, type Eip7702Authorization$1 as Eip7702Authorization, type FillerConfigFile, type FillerTomlConfig, type HyperbridgeBalance, InventoryStore, LimitOrder, LimitOrderController, LimitOrderFill, LimitOrderFilter, LimitOrderStore, LimitOrderValidationError, LogLevel, LogSink, Logger, LoggerContext, MemoryDataStore, type MpcVaultSignerConfig, OrderScanner, type OrderScanner$1 as OrderScannerContract, type OrderScannerHandlers, type OrderScannerOptions, type PairConfig, PairController, type PairView, type PostedLimitOrder, type PostingOutcome, type PrivateKeySignerConfig, type ProfitBucket, type ProfitBucketFigures, type ProfitFigures, type ProfitPeriod, type Profitability, type QueueConfig, RebalanceController, type RebalancingConfig, type ResolvedChainConfig, type ScannedFill, type ScannedOrder, type ScannerChainConfig, type SecretPhraseSignerConfig, type Signature, type Signer, type SignerConfig, type SignerTransaction, SignerType, Simplex, type SimplexConfig, SimplexDataStore, type SimplexEvents, type SimplexOptions, type SimplexStatus, type SolverWork, type StartingInventory, StateStore, StoredBid, type Subscription, type TurnkeySignerConfig, type TypedDataPayload, USD_STABLE_SYMBOLS, type UserProvidedChainConfig, type VaultBalanceRow, VaultController, type VaultSweepDeposit, type VaultSweepResult, type VaultSweepSkip, type VaultSweepSkipReason, type VaultSweepSubmission, type VaultToml, type VaultTomlConfig, WalletController, WalletTx, assertConfirmationCoverage, canDerive, createSigner, digestSigner, formatChainKey, isRegistrySymbol, mpcVaultSigner, normalizeSymbol, parseChainKey, pickAnchorStable, privateKeySigner, registrySymbols, secretPhraseSigner, turnkeySigner, validateAssetDefinitions, validateConfig, validatePairConfigs, validateSecretPhrase, validateSignerConfig, validateVaultToml, viemSigner };