Skip to content

AGENTS.md

Latest commit

 

History

History
114 lines (94 loc) · 8.08 KB

AGENTS.md

File metadata and controls

114 lines (94 loc) · 8.08 KB
Raw

AGENTS.md - relayer-v2

This repository contains bots that execute critical Across protocol operations, including relaying, dataworker root bundle workflows, inventory rebalancing, and cross-chain finalization tasks.

How to use docs in this repo

Read docs in this order:

  1. This file (AGENTS.md) for top-level navigation and module map.
  2. Module docs (src/*/README.md or local AGENTS.md) for implementation and runtime details.
  3. docs/*.md for deeper architectural and protocol context.

Documentation maintenance

Document load-bearing things only: core functionality, significant features, module interfaces, config surfaces, and runtime flows a contributor must understand to make a safe change. Bug fixes, refactors, and routine maintenance normally need no doc change — say so and move on.

  • These files are a shared reference, not a personal log. Don't record investigation narrative, findings you happened to make along the way, or a history of what changed — that belongs in the PR description.
  • Keep doc edits terse. Prefer amending an existing line over adding a section, and cut anything that wouldn't change what a reader does.
  • When a change does clear the bar, update the affected AGENTS.md / README.md in the same change, not as a follow-up.
  • Before writing implementation plans, surface material ambiguities first and resolve them with the user.
  • Write deep-dive docs only when asked, or when a flow spans modules and no single README.md covers it. Prefer cross-module walkthroughs over single-file explanations.
  • Write deep-dive docs as "current behavior" references first, then add a concise "contributor recommendations" section.

Quick index

  • Relayer runtime and risk model: src/relayer/README.md
  • Rebalancer behavior and adapters: src/rebalancer/README.md
  • Refiller behavior: src/refiller/README.md
  • Dataworker root-bundle flow: src/dataworker/README.md
  • Deposit-address handler and withdraw lifecycle: src/deposit-address/README.md
  • Deposit-address service (Express + Pub/Sub push; replaces the polling handler): src/deposit-address-service/README.md
  • Gasless relayer (API polling, deposits-only mode, integrator filters): src/gasless/README.md
  • Shared runtime clients: src/clients/README.md
  • Cross-bot messaging transports (Redis pub/sub + GCP Pub/Sub publisher and push-request helpers): src/messaging/
  • Finalization-specific workflows: src/finalizer/* and src/cctp-finalizer/*
  • UMA and smart-contract context: docs/uma.md and docs/smart-contracts.md
  • Relayer fill and repayment deep dives: docs/relayer-fill-decision-flow.md and docs/repayment-selection.md
  • Inventory deep dives: docs/repayment-eligibility.md and docs/inventory-virtual-balance-model.md
  • Rebalancer config tuning from deposit flow: docs/rebalancer-config-from-deposit-flow.md
  • Rebalancer modularity deep dive: docs/rebalancer-mode-adapter-architecture.md
  • Deposit-address withdraw lifecycle Pub/Sub contract: docs/deposit-address-withdraw-pubsub.md

Bot types

The main bot types in src/:

  • dataworker: Proposes, disputes, and executes root bundles for relayer and depositor refunds.
  • relayer: Fills profitable deposits subject to configured risk and route constraints.
  • refiller: Refills inventory back to configured target balances.
  • rebalancer: Rebalances inventory across chains and exchange venues.
  • finalizer: Completes delayed cross-chain flows and multi-step bridge finalization tasks.
  • monitor: Runs monitoring and reporting checks.
  • gasless: Handles gasless relay flows.
  • deposit-address: Polls the across-indexer for counterfactual deposit-address transfers and executes the resulting deposits or refund withdraws.
  • deposit-address-service: Standalone Express service doing the same work driven by GCP Pub/Sub push instead of polling. Not part of the index.ts CLI dispatch — it runs as its own entrypoint, like cctp-finalizer. Intended to replace deposit-address.

Directory tree

relayer-v2/
├── src/                          # Runtime bot implementations and shared TypeScript modules.
│   ├── dataworker/               # Dataworker runtime and root-bundle proposal/dispute logic.
│   ├── relayer/                  # Deposit fill runtime and relayer-specific config/logic.
│   ├── refiller/                 # Refiller runtime for target-balance inventory replenishment.
│   ├── rebalancer/               # Cross-chain and venue-based inventory rebalancing logic.
│   ├── finalizer/                # Generic finalization runtime and chain-specific finalizer utilities.
│   │   └── utils/                # Per-chain/per-bridge finalization helper implementations.
│   ├── cctp-finalizer/           # CCTP-focused finalization runtime and utility modules.
│   ├── monitor/                  # Monitoring and operational health checks.
│   ├── gasless/                  # Gasless relay runtime.
│   ├── deposit-address/          # Counterfactual deposit-address handler (polling): deposit + refund-withdraw paths.
│   ├── deposit-address-service/  # Same work as a Pub/Sub-push Express service; own entrypoint, replaces the poller.
│   ├── hyperliquid/              # Hyperliquid-specific execution and integration flows.
│   ├── clients/                  # Shared clients for events, txs, inventory, pricing, and bridges.
│   │   ├── ProfitClient.ts       # Profitability evaluation for potential fills.
│   │   ├── InventoryClient.ts    # Inventory state, targets, and transfer planning.
│   │   ├── TransactionClient.ts  # Transaction submission, tracking, and receipt handling.
│   │   ├── TokenClient.ts        # Token metadata, balances, and allowance helpers.
│   │   ├── SpokePoolClient.ts    # SpokePool event/state client wrappers.
│   │   └── bridges/              # Bridge adapter selection and cross-chain transfer helpers.
│   ├── cache/                    # Redis-backed and in-memory cache helpers.
│   ├── messaging/                # Cross-bot messaging transports.
│   │   ├── redis/                # Redis pub/sub wrapper (handover signaling).
│   │   └── gcp/                  # GCP Pub/Sub publisher (lifecycle events) + push-request decode/auth.
│   ├── adapter/                  # Chain/exchange adapter abstractions.
│   ├── interfaces/               # Shared interfaces and cross-module types.
│   ├── libexec/                  # Websocket/event listener execution helpers.
│   ├── common/                   # Shared constants and common primitives.
│   │   └── abi/                  # Contract ABI artifacts and ABI-loading helpers.
│   └── utils/                    # General shared utility helpers.
├── contracts/                    # Utility contracts used by bots (plus mocks for tests).
├── deploy/                       # Contract deployment scripts.
├── scripts/                      # Operational scripts and one-off tooling.
├── test/                         # Unit/integration tests for bots and shared clients.
├── docs/                         # Deeper architecture and protocol documentation.
└── Dockerfile                    # Container runtime definition for bot execution.

Runtime execution flow

  • Main entrypoint: index.ts
  • CLI args choose bot type and runtime options.
  • --wallet controls wallet construction for on-chain operations.
  • Environment variables map into bot-specific configuration objects.
  • Bots are designed to run in Dockerized, often serverless, environments.

Operator scripts

  • scripts/ contains one-off and operator-facing tooling that reuses runtime clients/utilities without going through index.ts.
  • scripts/swapOnBinance.ts is an interactive CLI that deposits into the shared Binance account, optionally trades on Binance spot, and withdraws to a destination chain.

Memory/state model

Most bots are designed for stateless execution between runs. Persistent runtime state is stored in Redis when continuity is required across invocations.