Guidance for coding agents (and humans) working in this repo. Everything here is grounded in the actual code/CI as of v0.12.1 — when in doubt, the referenced file is the source of truth.
rrelayer is an EVM transaction relay service written in Rust: an axum REST API + an in-process transaction engine (queues, nonce management, gas bumping) backed by Postgres, with pluggable signing providers (raw mnemonic, AWS KMS, AWS/GCP Secrets Manager, Privy, Turnkey, Fireblocks, PKCS#11, private keys). Clients are a CLI, a Rust SDK, and a TypeScript SDK.
- Every user-visible change MUST add a changelog entry in
documentation/rrelayer/docs/pages/changelog.mdxunder## Changes Not Deployed, in the same commit/PR as the change. "User-visible" = anything a user of the server, CLI, SDKs, config file, or docker image could notice: features, bug fixes, behavior changes, config options, API/SDK surface changes. Pure refactors, CI tweaks, and doc typo fixes are exempt. Format is strict — see section 4 before touching the file. - Pass the exact CI gates locally before pushing (CI =
.github/workflows/ci.yml):Clippy denies ALL warnings (onlycargo fmt --all # fix, then: cargo fmt --all -- --check cargo clippy -- -D warnings -A clippy::uninlined_format_args cargo test --exclude rust-sdk-playground --workspace
uninlined_format_argsis allowed). rustfmt usesrustfmt.toml(use_small_heuristics = "Max",reorder_imports,use_field_init_shorthand) — IDE-default formatting will fail the check; always runcargo fmt --allfrom the repo root. - Never put the string
Release v(orrelease/) in a commit message or PR title. CI greps master HEAD forRelease v[0-9]*\.[0-9]*\.[0-9]*to trigger the release pipeline, and skips normal builds on messages containingRelease v/release/. Branch namesrelease/*are reserved for releases. - The HTTP API has three hand-synced consumers. Any change to a route path,
request/response shape, or a serde rename in
crates/coremust be mirrored in the Rust SDK (crates/sdk), the TypeScript SDK (sdk/typescript), and the docs (documentation/rrelayer/docs/pages/integration/). There are no shared constants or codegen — grep is your safety net. - New API handlers must do their own auth. There is no route-level auth
middleware; a handler that skips the
AppStateauth helpers is publicly reachable. There are two, and picking the wrong one is a security bug — see the endpoint recipe in section 6.
| Path | What it is |
|---|---|
crates/core |
The server (rrelayer_core): axum API + transaction engine + DB + signing providers. Almost all behavior lives here. |
crates/cli |
The CLI (rrelayer_cli — the shipped binary; installers rename it to rrelayer). rrelayer start boots the core server in-process. |
crates/sdk |
The Rust SDK, published to crates.io as rrelayer. Depends on rrelayer_core for types. |
sdk/rust |
README pointer only — the Rust SDK is crates/sdk. Never add code here. |
sdk/typescript |
The TypeScript SDK, published to npm as rrelayer (versioned independently: npm 1.2.0 vs crates 0.12.1). |
crates/e2e-tests |
The real test suite: a standalone e2e-runner binary (~49 tests) that orchestrates anvil + Postgres + an embedded server. Not run in CI. |
playground/rust-sdk-playground |
Workspace member with compile-checked SDK usage snippets + runnable examples. Excluded from cargo test in CI, but it must still build and pass clippy. |
playground/* (example, local-node, base, sepolia, …) |
rrelayer project fixtures (rrelayer.yaml + docker-compose) used to run the server locally. playground/base is a TS consumer app using the published npm SDK. |
documentation/rrelayer |
Vocs docs site (npm). Contains the changelog and all user docs. CI never builds it — verify with npm run build. |
helm/rrelayer, providers/railway, Dockerfile, docker-compose.yml |
Deployment artifacts. Root docker-compose is dev Postgres only (port 5446). |
scripts/publish-rrelayer.sh |
Manual, interactive crates.io publish. Never run casually. |
Crate/package name traps: directory crates/sdk = crate rrelayer; crates/core
= rrelayer_core; crates/cli = rrelayer_cli (not on crates.io — ships as
GitHub Release binaries). Both SDKs are named rrelayer on their registries.
Rust (repo root unless noted):
cargo build # build the whole workspace
cargo build -p rrelayer_core # just the server crate
cargo fmt --all -- --check # CI fmt gate
cargo clippy -- -D warnings -A clippy::uninlined_format_args # CI lint gate
cargo test --exclude rust-sdk-playground --workspace # CI test gate (CI adds --release --target <triple>)Run the server locally (needs Docker; see section 8):
cp .env.example .env # once
docker-compose up -d # Postgres 16 on host port 5446
cd crates/cli && make start_local # = cargo run -- start --path ../../playground/local-node
# other fixtures: make start_example, start_e2e; manual CLI tests: make tx_send, network_list, ...E2E tests (from crates/e2e-tests; needs Docker + Foundry's anvil and forge
on PATH + a crates/e2e-tests/.env copied from its .env.example):
make run-tests-debug # full suite, raw provider, RUST_LOG=info
RRELAYER_PROVIDERS="raw" make run-tests-debug # explicit provider(s), comma-separated
make run-test TEST=transaction_send_eth # one test, by exact registered nameTypeScript SDK (from sdk/typescript; npm, not yarn/pnpm):
npm install
npm run build # tsc — the ONLY typecheck gate; CI never builds the TS SDK
npm run format # prettier (.prettierrc: single quotes, 80 cols); no ESLint
npm run "playground::transaction::send" # manual smoke scripts; need a live local serverDocs site (from documentation/rrelayer):
npm i && npm run dev # local dev server
npm run build # the only way to catch broken MDX/nav — CI never builds docs
npm run format # prettier; deliberately skips changelog.mdx via .prettierignoreFile: documentation/rrelayer/docs/pages/changelog.mdx. It is hand-maintained
(the CI automation for it is commented out in ci.yml — do not resurrect or
imitate that script; its binary filenames are outdated). It is also excluded from
prettier via documentation/rrelayer/.prettierignore — never reformat it.
Line 1 of the file is a # Changelog H1 — leave it alone. Immediately below it
is a fixed skeleton:
## Changes Not Deployed
---
### Features
---
### Bug fixes
---
### Breaking changes
---Insert exactly one bullet per change between the matching ### heading and the
--- line that follows it, surrounded by blank lines:
### Bug fixes
- fix: mark transactions as failed on intrinsic gas errors
---Rules:
- Bullets start at column 0 with
- feat:/- fix:and a short user-facing description, all lowercase even when the PR title is Title-Case (compare PRs #101/#102 to their bullets). Breaking changes are plain prose bullets with no prefix, describing old → new shape — the shipped precedent (0.5.0):- in the YAML changed from `automatic_top_up: Option<NetworkAutomaticTopUpConfig>` to `automatic_top_up: Option<Vec<NetworkAutomaticTopUpConfig>>`. See the breaking-change protocol in section 6. - One line per change; keep it short and user-facing (what changed, not how).
- Features under
### Features, fixes under### Bug fixes, breaking changes under### Breaking changes. Empty sections keep their skeleton — don't delete headings or---lines.
At release time the accumulated bullets move out of ## Changes Not Deployed
into a new release section inserted directly below the line all release branches are deployed through `release/VERSION_NUMBER` branches (newest release
first), and ## Changes Not Deployed is reset to the empty skeleton (see commit
aae21a7 for 0.12.0 as the reference diff; if a change landed without its bullet,
write it directly into the release section, as 0.12.1's 9838f8c did). Exact
shape — copy the previous release entry and edit, don't retype:
## 0.12.1 - 15th July 2026
-------------------------------------------------
github branch - https://github.com/joshstevens19/rrelayer/tree/release/0.12.1
- linux binary - https://github.com/joshstevens19/rrelayer/releases/download/v0.12.1/rrelayer_linux-amd64.tar.gz
- mac apple silicon binary - https://github.com/joshstevens19/rrelayer/releases/download/v0.12.1/rrelayer-arm64.tar.gz
- mac apple intel binary - https://github.com/joshstevens19/rrelayer/releases/download/v0.12.1/rrelayer-amd64.tar.gz
- windows binary - https://github.com/joshstevens19/rrelayer/releases/download/v0.12.1/rrelayer-amd64.zip
### Bug fixes
- fix: add better logs for config fileFormat traps (all load-bearing, verified against the file):
- Heading is
## X.Y.Z - <day><st|nd|rd|th> <Month> <YYYY>— novprefix on the version, day without leading zero (3rd July 2026,15th July 2026). - The underline under a release heading is exactly 49 hyphens on its own line;
the separators inside
Changes Not Deployedare---. Don't mix them up. - Binary filenames are intentionally inconsistent: linux has an underscore
(
rrelayer_linux-amd64.tar.gz), mac/windows use hyphens (rrelayer-arm64.tar.gz,rrelayer-amd64.tar.gz,rrelayer-amd64.zip). Download URLs DO use thevprefix (.../download/v0.12.1/...). Copy from the previous entry verbatim. - In release sections, include only the
###subsections that have content.
Boot: rrelayer start → crates/cli/src/commands/start.rs → loads project .env,
auto-runs docker compose up -d if Postgres is unreachable → rrelayer_core::start()
in crates/core/src/startup.rs, which: reads <project>/rrelayer.yaml
(crates/core/src/yaml.rs — the struct is SetupConfig but the file is always
rrelayer.yaml), applies DB migrations (crates/core/src/schema/), builds one
EvmProvider per network (crates/core/src/provider/ — this is where the signing
provider is selected), repopulates and spawns the per-relayer transaction queues
(crates/core/src/transaction/queue_system/), then starts the background tasks —
gas oracles (code in crates/core/src/gas/), webhooks, top-up, balance monitor —
via run_background_tasks (crates/core/src/background_tasks/), then serves axum
in start_api().
HTTP: routes are nested in startup.rs (crates/core/src/startup.rs:249-253) —
/auth, /networks, /relayers, /transactions, /signing, plus /health.
The full domain shape is exhibited by relayer/ and transaction/: api/ (one
endpoint per file + mod.rs router), db/ (read.rs, write.rs, builders.rs
— hand-written SQL, no ORM), types/ (one newtype per file, serde +
FromSql/ToSql), cache.rs, and a mod.rs with selective pub use
re-exports. Other domains use a subset (network/ has no db/; signing/ has
no types/ or builders.rs); copy the relayer/transaction shape for new domains
and wire new modules into crates/core/src/lib.rs.
Auth model: the global middleware only stamps whether Basic-auth credentials
(env RRELAYER_AUTH_USERNAME/RRELAYER_AUTH_PASSWORD — env vars, not the
yaml values, which are client-side) were valid. Handlers enforce auth themselves
via two AppState helpers (crates/core/src/app_state.rs):
validate_basic_auth_valid (strict — admin-only endpoints) and
validate_allowed_passed_basic_auth (short-circuits to Ok when any api_keys
are configured — only correct on relayer-scoped endpoints that subsequently call
validate_auth_basic_or_api_key, which accepts x-rrelayer-api-key from yaml
networks[].api_keys). Rate limiting is also in-handler
(RateLimiter::check_and_reserve_rate_limit + reservation.commit()).
Transaction lifecycle: Postgres enum relayer.tx_status:
PENDING → INMEMPOOL → MINED → CONFIRMED (plus FAILED/EXPIRED/CANCELLED/DROPPED/
REPLACED). Three tokio loops per relayer (queue_system/start.rs) move
transactions along, bumping gas per speed (SLOW/MEDIUM/FAST/SUPER) after
gas_bump_blocks_every blocks, capped by max_gas_price_multiplier and the
relayer's max_gas_price. TransactionsQueues is a single global
Arc<Mutex<...>> — long-held locks in that file stall all relayers.
Signing providers ("wallet managers") live in crates/core/src/wallet/, all
implementing WalletManagerTrait (wallet/mod.rs). CompositeWalletManager
routes wallet indexes ≥ u32::MAX - 1000 to raw private keys (stored as negative
wallet_index in relayer.record) — respect both conventions in any
wallet-index arithmetic.
crates/core/src/<domain>/api/<verb_noun>.rs— handlerpub async fn x(State(state): State<Arc<AppState>>, headers: HeaderMap, ...) -> Result<Json<Resp>, HttpError>. First line is auth, and the helper choice matters:- Admin-only endpoint (networks, relayer create/delete/pause/config, status):
state.validate_basic_auth_valid(&headers)?; - Relayer-scoped endpoint usable with API keys:
state.validate_allowed_passed_basic_auth(&headers)?;and then, after loading the relayer,state.validate_auth_basic_or_api_key(...)?. The first helper alone is a no-op when api_keys are configured — using it on an admin-only endpoint leaves that endpoint effectively unauthenticated. Tx/signing ops add the rate-limit reserve/commit pair.
- Admin-only endpoint (networks, relayer create/delete/pause/config, status):
- Register in the domain's
api/mod.rsrouter fn — names vary:create_transactions_routes,create_relayer_routes,create_network_routes,create_signing_routes,create_basic_auth_routes(seestartup.rs:249-253). A new route group needs its owncreate_*_routes()nested instart_api(). pub usenew request/response types through<domain>/mod.rsandcrates/core/src/lib.rs.- Mirror in the Rust SDK: raw method in
crates/sdk/src/api/<domain>/mod.rs(relative path string must match the axum nesting exactly), expose on the right facade incrates/sdk/src/clients.rs(Client= admin/basic-auth;RelayerClient= API-key-capable;AdminRelayerClient= relayer + admin), re-export new types fromcrates/sdk/src/lib.rs, add a compile-checked snippet inplayground/rust-sdk-playground/src/<domain>/. - Mirror in the TS SDK:
sdk/typescript/src/api/<domain>/<kebab-name>.ts(a standalone function;ApiBaseConfigis always the LAST param; go throughaxios-wrapper.ts, endpoint string without leading slash), barrel-export in the domainindex.ts, wire onto the matching client class insrc/clients/(clients/index.tsis a curated export list — new public symbols must be added there explicitly). TS interface fields must byte-match the Rust serde renames (#[serde(rename = "relayerId")]etc. — copy from the Rust struct, don't guess). - Docs: update BOTH
documentation/rrelayer/docs/pages/integration/sdk/<area>/node.mdxand.../rust.mdx, plusintegration/api/<area>.mdx, plus sidebar/anchor entries indocumentation/rrelayer/vocs.config.tsx. - Changelog bullet (section 4). Commit
feat: expose webhook types to Rust and Typescript SDKs (#97)(fd5b256) is the canonical example of steps 3 and 5–7 — mirroring types across both SDKs, docs twins,vocs.config.tsx, and the changelog in one PR (it does not add an endpoint itself).
Conventions shared by BOTH SDKs (keep new methods consistent):
- Mutating calls (send/cancel/replace/sign) take a trailing rate-limit key param
(Rust
rate_limit_key: Option<String>, TSrateLimitKey?) sent as thex-rrelayer-rate-limit-keyheader — both import aRATE_LIMIT_HEADER_NAMEconstant rather than hardcoding the string. - "Get one" endpoints map 404 → absent:
get_or_none→ApiResult<Option<T>>in Rust,Promise<T | null>in TS. Lists take aPagingContextand return aPagingResult<T>. remove_max_gas_priceis implemented asupdate_max_gas_price(0)— the server treats 0 as unset. Keep that convention for related gas-cap methods.
- New file
crates/core/src/schema/v1_0_3.rs(next version) with idempotent DDL (CREATE TABLE IF NOT EXISTS,ADD COLUMN IF NOT EXISTS, guardedCREATE TYPE) —apply_schemare-runs every migration on every boot with no version table; non-idempotent DDL bricks existing deployments. - Register it in
crates/core/src/schema/mod.rsafterv1_0_2. - Queries live in the owning domain's
db/module. Forrelayer.transaction, writes are duplicated torelayer.transaction_audit_logvia theTRANSACTION_TABLESconst intransaction/db/write.rs— column lists must stay valid for BOTH tables, and the row mapper intransaction/db/builders.rsmust learn the new column (misses panic at runtime, not compile time). - New Postgres schemas must also be added to the e2e reset lists:
crates/e2e-tests/src/infrastructure/embedded_rrelayer.rs(schemas_to_drop) and thereset-dbpsql list incrates/e2e-tests/Makefile.
- Add the field in
crates/core/src/yaml.rs(SetupConfigglobal,NetworkSetupConfigper-network) with the existing serde-default idioms.${ENV_VAR}interpolation is automatic for all strings — note it panics at startup if the var is unset. - Plumb through
startup.rs/AppState/ queue or background-task params as needed. - Update example configs in
crates/e2e-tests/config/*.yaml, the docs (documentation/rrelayer/docs/pages/config/index.mdxfull example + the specific subpage), and the changelog.
Every deployed rrelayer has a rrelayer.yaml that must survive a binary
upgrade. What breaks users:
- Changing a field's type or shape → existing configs fail to parse and the
server won't boot. This is the one shipped precedent (0.5.0:
automatic_top_upwent fromOption<NetworkAutomaticTopUpConfig>toOption<Vec<...>>). - Making an optional field required (or adding a required field) → parse
failure on boot. New fields must be
Option<...>or carry#[serde(default)]/#[serde(default = "fn")]. - Renaming or removing a field → the worst case:
SetupConfigdoes NOT usedeny_unknown_fields, so an old key in a user's config is silently ignored and behavior quietly falls back to defaults (e.g. a renamedpermissionskey would silently disable allowlists). No error, no log. - Changing a
default_*fn value or a${ENV_VAR}becoming required (missing env vars panic at startup) → silent or fatal behavior change on upgrade with no config edit.
Protocol:
- Prefer additive + optional. If renaming, keep the old name working via
#[serde(alias = "old_name")](no precedent inyaml.rsyet — you'd be setting it) or reject the old key explicitly inread()/validate()with a clear migration error. Never let an old key be silently ignored. - If the break is unavoidable: add a plain prose bullet under
### Breaking changesin the changelog describing old → new shape, in the 0.5.0 style above — this is exactly what that section exists for. - Update every in-repo
rrelayer.yamlinstance in the same PR:crates/e2e-tests/config/*.yaml,playground/*/rrelayer.yaml,helm/rrelayer/values.yaml(embeds a fullrrelayerConfig),providers/railway/example-app/rrelayer.yaml, and the docs examples underdocumentation/rrelayer/docs/pages/config/. - Note: pre-1.0, breaking changes ship in minor version bumps (0.5.0 did) — there is no major-version gate protecting users, which makes the changelog bullet the only migration signal they get.
The same "breaking" lens applies beyond yaml: HTTP route/response shapes and webhook payloads (external consumers + both SDKs), CLI flags/output that scripts parse, env var names, and DB migrations (must be idempotent AND cope with data written by older versions).
Grep fireblocks repo-wide to find every touchpoint. Short list: config struct +
SigningProvider field + validate() in yaml.rs; manager in
crates/core/src/wallet/<name>_wallet_manager.rs implementing WalletManagerTrait;
EvmProvider::new_with_<name>() in provider/evm_provider.rs; dispatch (incl.
composite path and has_main_signing_provider) in provider/mod.rs; the
private_key_only_networks filter in startup.rs; e2e: SigningProvider enum in
crates/e2e-tests/src/main.rs, config/<name>.yaml, funding addresses in
infrastructure/contract_interactions.rs, Makefile target; docs page under
config/signing-providers/ + vocs.config.tsx; changelog.
Variant in crates/cli/src/cli_interface.rs → handler module in
crates/cli/src/commands/<name>.rs (+ error enum in commands/error.rs, #[from]
variant in crates/cli/src/error.rs) → match arm in main.rs (follow the
resolve-path → load-env → ProjectLocation → SDK client → check_authenticate
recipe) → Makefile target in crates/cli/Makefile → update the pasted --help
blocks in documentation/rrelayer/docs/pages/getting-started/cli.mdx → changelog.
The CLI never talks HTTP directly — it consumes the Rust SDK, so new endpoints
need the SDK method first.
Async fn in crates/e2e-tests/src/tests/<domain>/, registered via
TestDefinition::new("snake_case_name", ...) in that domain's get_tests(); a
brand-new domain module must also be added to TestRegistry::get_all_tests() in
src/tests/registry.rs or it silently never runs. The name string is the
make run-test TEST=<name> key (exact match). Tests share one anvil + Postgres +
embedded server; the fixture values in config/raw.yaml (rate limits, allowlists,
funded addresses derived from the .env.example mnemonic) are load-bearing for
existing assertions, and registry order matters — the allowlist module
intentionally runs first.
.mdx under documentation/rrelayer/docs/pages/ (file path = URL route) + a
sidebar entry in documentation/rrelayer/vocs.config.tsx. The sidebar hardcodes
heading-slug anchors — renaming any MDX heading requires grepping
vocs.config.tsx for the old slug. Verify with npm run build.
- CI runs only ~9 inline unit tests (
crates/core/src/shutdown.rs,crates/core/src/safe_proxy.rs,crates/sdk/src/alloy_integration.rs). CI never runs the e2e suite, never builds the TS SDK, never builds the docs. A change can break all three and merge green. - Real coverage is
crates/e2e-tests(e2e-runnerbinary, run via its Makefile — see section 3). It must be run fromcrates/e2e-tests/(resolves config, contracts, docker-compose,.envfrom cwd). Raw provider needs no cloud credentials; kms/privy/turnkey/fireblocks/etc. need real secrets in.env. - The e2e crate has no
#[test]fns but IS a workspace member: compile errors in it fail every CI matrix leg. - New unit tests: keep them inline (
#[cfg(test)] mod testsat file bottom) and DB/network-free socargo test --workspacestays hermetic. sdk/typescript/jest.config.jsis dead (jest isn't installed, no test script, setup file missing). Don't add*.test.tsexpecting them to run; use theplayground::*scripts against a live server instead.- For runtime verification of server changes:
cd crates/cli && make start_localagainstplayground/local-node(has an anvil Makefile), then hithttp://localhost:8000or use CLI/SDK playground scripts.
- Prereqs: Rust stable (edition-2024 crates need a recent stable), Docker,
Foundry (
anvil/forge/cast) for anything chain-touching, Node ≥ 20 for TS SDK/docs. - Postgres ports by context — using the wrong one silently hits the wrong DB:
5446 root
docker-compose.yml(dev), 5447crates/e2e-testscompose (e2e), 5471playground/local-nodecompose, 5441 projects generated byrrelayer new.DATABASE_URLcomes from env/.env only — there is no DB setting inrrelayer.yaml. - Server auth env vars must match between the server process and clients:
RRELAYER_AUTH_USERNAME/RRELAYER_AUTH_PASSWORD(yamlapi_configvalues are what the CLI/SDK read, typically${...}-interpolated from the same.env). - The canonical, full
rrelayer.yamlexample iscrates/e2e-tests/config/raw.yaml(every feature exercised); smaller runnable ones live inplayground/*/rrelayer.yaml; the user-facing reference isdocumentation/rrelayer/docs/pages/config/. - Secrets hygiene:
.env(not.env.example),*.key,playground/**/keystores, andcrates/e2e-tests/rrelayer.yamlare gitignored — never commit real mnemonics, private keys, or cloud credentials. The only acceptable hardcoded mnemonic is anvil's well-knowntest test ... junkin local fixtures. LOCAL-SETUP.mdis stale (referencesrrelayer_server/andsetup.yaml; the real config file isrrelayer.yaml). Prefer this file +crates/cli/Makefile.Cargo.lockis gitignored — ALL dependency versions float between builds. The workspace root setsalloy = "1.1.3", but that is a caret (minimum) requirement, not a pin — fresh builds still pull the latest 1.x, and floating alloy has broken the build before (#78/#80). If a dependency break appears, pin it with an exact=x.y.zrequirement at the workspace root — never in a single crate's manifest (crates useworkspace = true).
- Move
Changes Not Deployedbullets into a new release section in the changelog (section 4.2) on arelease/X.Y.Zbranch and push it. - CI builds 4 platform binaries, seds
version =incrates/{cli,core,sdk}/Cargo.toml(+ root, currently a no-op), commitsRelease vX.Y.Z, opens the PR to master. Do NOT hand-bump crate versions. - Merging the PR (title must keep
Release vX.Y.Z) triggers the GitHub Release (tagvX.Y.Z, binary assets) and the ghcr.io docker image (:X.Y.Z+:latest). - crates.io publish is manual:
./scripts/publish-rrelayer.sh(core first, then the SDK). Known issue: the script's sed expectsrrelayer_core = { path = "../core", version = "..." }butcrates/sdk/Cargo.toml:29currently has noversionkey — the SDK publish will fail until that's restored. Keep that dep on one line in the script's format. - npm publish of the TS SDK is manual and independent: hand-bump
versioninsdk/typescript/package.json,npm publishfrom that dir. documentation/rrelayer/docs/public/install.shis the production installer; it hardcodes the release asset names andv-tag format fromci.yml. Renaming the binary, archives, or tags requires updating ci.yml (both build jobs), docker.yml, the Dockerfile, and install.sh together.
- Commits/PR titles: lowercase conventional prefix —
fix: ...,feat: ...,chore: ...,docs: ..., optional scope (feat(relayer): ...). PRs targetmasterand are squash-merged (the merge appends(#N)). Changelog bullets paraphrase the PR title in all-lowercase (section 4.1). - Branches:
fix/<kebab-slug>,feature/<kebab-slug>,issue-<N>.release/*is reserved. - Errors (Rust): thiserror enums per domain (
#[derive(Error, Debug)],#[error("...: {0}")],#[from]conversions), plusimpl From<XError> for HttpErrorvia thebad_request/forbidden/not_found/internal_server_errorhelpers incrates/core/src/shared/. Confineanyhowtocrates/e2e-tests— a few legacy uses exist in core (transaction_blob.rs,evm_provider.rsblob estimation); don't add more. Avoidunwrap()/expect()outside tests. - Logging:
tracing. Inside core useinfo!/error!; the CLI's server-start path uses therrelayer_info!/rrelayer_error!re-exports fromrrelayer_core; interactive CLI command output is plainprintln!; e2e-tests usestracingdirectly. - Newtypes: every domain scalar (RelayerId, TransactionId, GasPrice,
EvmAddress, ChainId, …) is a newtype with serde + FromSql/ToSql; follow
crates/core/src/transaction/types/as the template. - Long-running loops must be shutdown-aware:
tokio::select!onsubscribe_to_shutdown(),enter_critical_operation()guards around non-interruptible sections (crates/core/src/shutdown.rs). - Editions differ intentionally: cli/sdk/playground are edition 2024; core/e2e-tests are 2021. SDK uses thiserror 2.x, core uses 1.x. Don't harmonize.
- TS: prettier only (no ESLint), strict tsconfig, CommonJS/es2020. Never call
axios directly — always via
src/api/axios-wrapper.ts.
- Forgot the changelog bullet → re-read section 1, rule 1.
- New handler without auth, or
validate_allowed_passed_basic_authon an admin-only endpoint (it's a no-op when api_keys are configured) → publicly reachable. - Route/type change without touching
crates/sdk+sdk/typescript+ docs → three-way drift. - Non-idempotent migration → every existing deployment fails to boot.
relayer.transactioncolumn added buttransaction_audit_log/builders.rsmissed → runtime panic onrow.get.- New
TransactionStatusvariant needs the Rust enum +ALTER TYPEmigration forrelayer.tx_status+ queue-repopulation logic inqueue_system/start.rs. - Webhook
networks:filters match yaml network names, not chain ids — renaming a network silently detaches its webhooks. - Renaming/removing a
rrelayer.yamlfield is silent data loss for users: unknown keys are ignored (nodeny_unknown_fields), so old configs quietly fall back to defaults instead of erroring. Follow the breaking-change protocol in section 6. - Clippy
-D warnings+ unpinned stable toolchain: a new Rust release can fail CI on untouched code — that's not your change. - jemalloc feature asymmetry:
crates/climust compile with AND without--features jemalloc(Windows/arm64-linux builds omit it). - Local
docker build .needsmkdir -p docker-binaryfirst. - e2e Makefile
start-postgreshealth-checks the wrong port (5447 vs root compose 5446) — the runner brings up its own compose; don't fight it.verify-setup.shis stale and fails on the current tree; ignore it. - Prettier must never touch
changelog.mdx— it's in.prettierignorebecause a (currently disabled, expected to return) release step inci.ymlparses it with grep/sed line patterns. - Rate-limit
intervalparsing (rate_limiting/rate_limiter.rs) only recognizes"1m"— every other string silently defaults to 60s. Configs sayinginterval: "minute"work by accident; don't build on that parser without extending it. - Signing routes keep deprecated duplicate paths
(
/signing/:relayer_id/...alongside/signing/relayers/:relayer_id/...) for backward compatibility — don't remove them when touching that router. - New native/system dependencies (openssl-like crates) must be added to every
build environment: the apt steps in
ci.yml/docker.yml, the Windows vcpkg step, and both Dockerfile stages. The Windows matrix leg breaks first. - The e2e runner
pkills rrelayer andkill -9s whatever holds ports 3000/8545 on start/teardown — never run it while a local dev server is up. - TS SDK stale bits (existing state, don't trip on them): the
playground::viem::send-blobnpm script points at a file that doesn't exist, andclient.getRelayerClient()hardcodesproviderUrl: 'TODO'— usecreateRelayerClientwith an explicitproviderUrlfor provider-backed methods.
Run through this before opening any PR:
cargo fmt --all&&cargo clippy -- -D warnings -A clippy::uninlined_format_args&&cargo test --exclude rust-sdk-playground --workspaceall pass.- Changelog bullet added under
## Changes Not Deployed(section 4) — or the change is genuinely invisible to users (pure refactor/CI/doc-typo). If anything aboutrrelayer.yaml, routes, webhook payloads, or CLI flags changed shape: prose bullet under### Breaking changes+ every in-reporrelayer.yamlinstance updated (breaking-change protocol, section 6). - If any route, request/response type, or serde rename changed: Rust SDK, TS SDK,
and docs twins updated (rule 4),
npm run buildpasses insdk/typescript, and a playground snippet exists for new SDK surface. - If docs/MDX changed:
npm run buildpasses indocumentation/rrelayer(CI won't catch it). - If engine/DB/signing behavior changed: e2e suite run locally
(
make run-tests-debugincrates/e2e-tests) — CI can't catch regressions there. - Commit/PR title is lowercase
fix:/feat:/chore:style and contains noRelease v/release/substrings. - No secrets in the diff (
.envcontents, mnemonics, keys, cloud credentials).