Stargate Bridge

Registry surface for Stargate chain entries and path baselines

Stargate Bridge Registry Surface

Product boundary

• Stargate chain and path-baseline APIs, registry services, and operator seed/completeness tools are Pro capabilities.

The entire Stargate surface is Pro (commercial license, excluded from the OSS build), including the exec.stargate.send and exec.stargate.dst_observe executors. None of this ships in the AGPL-3.0-or-later OSS repo. OSS code reaches the Stargate registry only through the sanctioned pro_loader boundary. If you are reading this from the OSS distribution, these modules will not be present.

Operator flow: configure, approve, execute, observe, recover, stop

1. Configure the commercial deployment, Pro package/loader gate, MG_STARGATE_ENABLED, required EVM RPC endpoints, and registry records.
2. Approve the route under the normal QTG approval and allowlist controls.
3. Execute a path only after registry, quote, and signer checks succeed.
4. Observe source and destination evidence through the configured path.
5. Recover from durable execution evidence rather than guessing an ambiguous outcome.
6. Stop and escalate when recovery evidence is incomplete or contradictory.

---

1. Registry Pattern Overview

Stargate lane execution is split across three operator-managed registry layers:

Layer	Table / service	Role
Chain registry	stargate_chain_registry / StargateChainRegistryService	canonical chain key -> Stargate endpoint identity(EID), finality tuning, snapshot freshness metadata
Pool registry	stargate_pools	onchain-discovered pool/token inventory used by refresh and validation workflows
Path baseline	stargate_path_baseline / StargatePathBaselineService	latency, fee budget, drill-pass evidence, and enabled/disabled gating for each src/dst/asset path

From an operator perspective, this is the usual way to read it:

1. stargate_pools is the raw registry inventory produced by discovery/refresh.
2. stargate_chain_registry is the operator-owned registry that condenses pool rows into chain-level control-plane facts.
3. stargate_path_baseline is the allow/deny + SLO layer that declares actual template-path readiness.

In other words, chain_registry is the anchor for chain metadata, and path_baseline decides whether that path is allowed for operation.

---

2. Stargate Registry Admin

2.1 Auth boundary

This write surface reuses the existing HMAC admin purpose throughout. No new purpose was added.

• route module guard: require_admin_hmac()
• accepted roles: admin (route-registered; the _ALL route set covers admin/operator/agent)
• canonical route-purpose mapping source: interfaces/api/middleware/auth/hmac.py

Read-only routes (GET /v3/stargate/chains, GET /v3/stargate/path-baselines, and single-item lookups) require the admin or operator role, and the table below covers only the write/admin surface.

2.2 Admin route table

Method	Path	Request schema	Response summary	Purpose
POST	/v3/stargate/chains	ChainCreateRequest - chain, endpoint_identity, optional finality_age_seconds, operator_label	created ChainRegistryRow as JSON dict: canonical chain, endpoint_identity, snapshot metadata, timestamps	create chain registry row
PUT	/v3/stargate/chains/{chain}	ChainUpdateRequest - endpoint_identity, optional finality_age_seconds, operator_label	updated or touched ChainRegistryRow JSON	mutate existing chain registry row by canonical chain key
DELETE	/v3/stargate/chains/{chain}	ChainDeleteRequest - operator_label	deleted ChainRegistryRow snapshot returned before row removal	remove obsolete chain registry row with audit trail
POST	/v3/stargate/path-baselines	PathBaselineCreateRequest - src_chain, dst_chain, asset, optional latency/budget fields, enabled, optional disabled_reason, operator_label	created PathBaselineRow JSON: canonical path key, budgets, drill metadata, timestamps	create path baseline
PUT	/v3/stargate/path-baselines/{src_chain}/{dst_chain}/{asset}	PathBaselineUpdateRequest - optional latency/budget fields, enabled, optional disabled_reason, operator_label	updated or touched PathBaselineRow JSON	mutate baseline for an existing path key
DELETE	/v3/stargate/path-baselines/{src_chain}/{dst_chain}/{asset}	PathBaselineDeleteRequest - operator_label	deleted PathBaselineRow snapshot returned before row removal	remove obsolete or mistaken baseline
POST	/v3/stargate/path-baselines/{src_chain}/{dst_chain}/{asset}/drill-pass	PathBaselineDrillPassRequest - evidence_path, operator_label	PathBaselineRow JSON with last_drill_pass_at and last_drill_evidence_path updated	record latest successful operator drill evidence
POST	/v3/stargate/refresh-registry	refresh request with operator_label	refreshed registry snapshot	operator-review gate over discovery/refresh output
POST	/v3/stargate/set-trust	trust request (operator_label)	updated trust state	reviewed operator trust mutation
POST	/v3/stargate/preapprove	preapproval request (operator_label)	updated preapproval state	reviewed operator preapproval mutation
POST	/v3/stargate/revoke-preapprove	revoke request (operator_label)	updated preapproval state	reviewed operator preapproval revocation
GET	/v3/stargate/movements/{movement_id}/broadcast-attempts	—	broadcast attempt rows	read broadcast-ambiguity evidence

2.3 Field and schema notes

ChainRegistryRow response fields:

• chain
• endpoint_identity
• finality_age_seconds
• snapshot_version
• snapshot_stale
• stale_detected_at
• operator_label
• snapshot_at
• created_at
• updated_at

PathBaselineRow response fields:

• src_chain
• dst_chain
• asset
• expected_latency_seconds
• detection_latency_budget_seconds
• fee_native_budget
• enabled
• disabled_reason
• last_drill_pass_at
• last_drill_evidence_path
• baseline_source
• operator_label
• cost_policy_revision
• max_token_fee_bps
• max_quote_degradation_bps
• max_native_messaging_fee_wei
• max_source_gas_fee_wei
• enforced_options_raw_hex
• lz_receive_gas
• lz_receive_value
• enforced_options_observed_at
• last_unsafe_observed_at
• last_unsafe_reason
• src_pool_address_at_snapshot
• dst_eid_at_snapshot
• created_at
• updated_at

Route modules return asdict(row) payloads, so the JSON shape is the service dataclass shape directly. The create/update request schemas also accept the cost-evidence fields above — they are what “cost evidence enforcement” gates dispatch against.

2.4 Typical operator workflow

The most common operator sequence is below.

1. Seed chain registry from discovered pools. Pro operator tool seed_stargate_chain_registry (--operator-label ops.seed).
2. Seed path baselines from a reviewed JSON payload. Pro operator tool seed_stargate_path_baseline with the reviewed path-baselines.json (--operator-label ops.seed).
3. Check completeness against template coverage. Pro operator tool stargate_path_baseline_completeness.
4. Backfill or fix missing paths, then call POST /v3/stargate/path-baselines/{src}/{dst}/{asset}/drill-pass after a successful drill and evidence upload.
5. When a chain/path is retired, remove it through the corresponding DELETE admin route so the audit table records the removal operator.

CLI intent:

• seed_stargate_chain_registry backfills stargate_chain_registry from distinct (chain, eid) pairs in stargate_pools
• seed_stargate_path_baseline applies reviewed baseline JSON into stargate_path_baseline
• stargate_path_baseline_completeness reports missing or disabled template paths and exits non-zero when gaps remain

2.5 Idempotency and audit semantics

Admin writes are intentionally audit-heavy, but they do not emit pointless new versions when nothing changed.

chain_registry and path_baseline share the same mutation semantics:

• POST create: inserts row, writes create audit
• PUT with material field change: mutates row, increments version where applicable, writes update audit
• PUT with no material field change and same operator label: no-op, no new audit row
• PUT with no material field change but different operator label: writes touch audit so operator custody change is visible
• DELETE: writes delete audit first, then removes the live row

Delete audit convention matters:

• audit row captures the last live snapshot before removal
• before_json and after_json both contain that snapshot
• row deletion happens after the audit insert so Postgres foreign-key enforcement is satisfied

This pattern lets the operator reconstruct “what was deleted” from the audit log alone, without depending on permissive database behavior.

2.6 Failure semantics

Common route outcomes:

• 404: unknown chain or missing baseline (StargateChainRegistryNotFound, BaselineMissingError)
• 409: EID collision on chain registry upsert (StargateChainEidConflict)
• 403: HMAC purpose is not admin or all

The admin API is deliberately small: it exposes registry ownership, not free discovery. Discovery/refresh flows feed the admin surface; refresh-registry, set-trust, preapprove, and revoke-preapprove are operator review gates mounted in stargate_admin.py over discovery output.

2.7 Pool verification endpoint binding

Refreshing a pool verifies one configured RPC endpoint at a time. It first requires an exact, strictly encoded eth_chainId, then a valid nonempty eth_getCode response for the pool. The first candidate that meets both tests is fixed for every later token, LayerZero endpoint/EID, shared-decimals, ERC-20-decimals, and block read. The block read is itself a strict lowercase JSON-RPC quantity inside the selected-endpoint error boundary; malformed output or provider failure is rpc_error, never an exception or a fallback. A mismatch or RPC failure after selection never falls through to another endpoint.

When no endpoint qualifies, empty_code has precedence over chain_id_mismatch, and chain_id_mismatch has precedence over unreachable only when every valid chain-id response was nonmatching. The drift worker records the endpoint ordinal/count and expected/observed numeric chain IDs, never a raw RPC URL, provider response, or exception message.

2.8 Mainnet KMS runtime opt-in

The base Compose stack deliberately starts both application services with signing disabled. Do not change that default or rename the opt-in overlay to docker-compose.override.yml. For a reviewed Stargate mainnet drill, use exactly these two files, in this order:

export MG_LOCAL_SIGNER_KEY='<non-secret signer registry key>'
export MG_LOCAL_SIGNER_KMS_KEY_ID='<KMS alias or ARN>'
export MG_LOCAL_SIGNER_AWS_REGION='<AWS region>'
export MG_LOCAL_SIGNER_AWS_PROFILE='<host AWS profile name>'
# Exactly the selected source/destination chain IDs; no development defaults.
export MG_EVM_RPC_ENDPOINTS_JSON='{"42161":"https://<arb-rpc>","8453":"https://<base-rpc>"}'
export MG_REMOTE_SIGNER_EXPECTED_ADDRESS='<pinned KMS-derived EVM address>'
# The overlay also requires these host values for the remote signer plane:
export MG_SIGNER_DATABASE_URL='<signer DB URL>'
export QTG_SIGNER_HMAC_KEY_ID='<signer HMAC key id>'
export QTG_SIGNER_HMAC_SECRET='<signer HMAC secret>'
# Contains only config/credentials files for the named drill profile; never ~/.aws.
export QTG_STARGATE_AWS_PROFILE_DIR='<absolute dedicated profile directory>'
case "$QTG_STARGATE_AWS_PROFILE_DIR" in
  /*) ;;
  *) echo 'BLOCK: QTG_STARGATE_AWS_PROFILE_DIR must be absolute.'; exit 2 ;;
esac
if [ "$QTG_STARGATE_AWS_PROFILE_DIR" = "$HOME/.aws" ]; then
  echo 'BLOCK: never mount the operator full ~/.aws directory.'
  exit 2
fi
test -f "$QTG_STARGATE_AWS_PROFILE_DIR/config"
test -f "$QTG_STARGATE_AWS_PROFILE_DIR/credentials"
unexpected_profile_entry=$(find "$QTG_STARGATE_AWS_PROFILE_DIR" -mindepth 1 -maxdepth 1 \
  ! -name config ! -name credentials -print -quit)
if [ -n "$unexpected_profile_entry" ]; then
  echo 'BLOCK: dedicated AWS profile directory has an unexpected top-level entry.'
  exit 2
fi
export AWS_CONFIG_FILE="$QTG_STARGATE_AWS_PROFILE_DIR/config"
export AWS_SHARED_CREDENTIALS_FILE="$QTG_STARGATE_AWS_PROFILE_DIR/credentials"
profiles="$(aws configure list-profiles)" || exit $?
if [ "$profiles" != "$MG_LOCAL_SIGNER_AWS_PROFILE" ]; then
  echo 'BLOCK: dedicated profile directory must expose exactly MG_LOCAL_SIGNER_AWS_PROFILE.'
  exit 2
fi
test -z "$(git status --porcelain)"
export QTG_SOURCE_REVISION="$(git rev-parse HEAD)"

docker compose \
  -f infra/docker-compose.yml \
  -f infra/docker-compose.stargate-kms-mainnet.yml \
  config --quiet

infra/docker-compose.stargate-kms-mainnet.yml affects only qtg-mainnet. It selects aws_kms_evm, enables Stargate, keeps raw-key settings empty, and bind-mounts the dedicated profile directory read-only at /root/.aws. It pins AWS_CONFIG_FILE and AWS_SHARED_CREDENTIALS_FILE to the mounted config and credentials files, and blanks inherited AWS access-key/session-token values. It does not declare AWS access keys, session tokens, private keys, or HMAC secrets. The KMS key identifier and signer registry key are identifiers, not cryptographic material. The dedicated directory must contain only the named drill profile’s AWS configuration and credentials — never the operator’s full ${HOME}/.aws. The overlay explicitly clears MG_LOCAL_SIGNER_AWS_ENDPOINT_URL, AWS_ENDPOINT_URL, and AWS_ENDPOINT_URL_KMS, so the KMS client cannot inherit an arbitrary endpoint.

Before starting a signing-capable worker, run this read-only database audit. It fails closed if either a non-drill READY/in-flight node exists or any nonterminal node still references the selected signer key/address:

audit_sql=$(cat <<'SQL'
WITH active_non_drill AS (
  SELECT 'non_drill_active' AS blocker, request_id, node_key, node_state
  FROM mainnet.movement_request_nodes AS node
  JOIN mainnet.movement_requests AS movement ON movement.id = node.request_id
  WHERE node.node_state IN ('READY', 'PREPARING', 'AWAITING_SIGNATURE',
                            'SUBMITTING', 'SUBMITTED', 'OBSERVING', 'UNKNOWN')
    AND COALESCE(movement.strategy_id, '') <> 'stargate-send-drill'
), signer_reuse AS (
  SELECT 'signer_reuse' AS blocker, request_id, node_key, node_state
  FROM mainnet.movement_request_nodes AS node
  WHERE node.node_state NOT IN ('COMPLETED', 'FAILED', 'CANCELLED', 'SKIPPED')
    AND (
      node.signer_binding->>'signer_key' = :'signer_key'
      OR lower(node.signer_binding->>'signer_address_snapshot') = lower(:'signer_address')
    )
)
SELECT blocker, request_id, node_key, node_state FROM active_non_drill
UNION ALL
SELECT blocker, request_id, node_key, node_state FROM signer_reuse
ORDER BY blocker, request_id, node_key;
SQL
)

blockers=$(docker compose \
  -f infra/docker-compose.yml \
  -f infra/docker-compose.stargate-kms-mainnet.yml \
  exec -T postgres psql -U qtg -d qtg_v3 -v ON_ERROR_STOP=1 -tA \
  -v signer_key="$MG_LOCAL_SIGNER_KEY" \
  -v signer_address="$MG_REMOTE_SIGNER_EXPECTED_ADDRESS" \
  -c "$audit_sql") || exit $?

if [ -n "$blockers" ]; then
  printf '%s\n' "$blockers"
  echo 'BLOCK: resolve or explicitly close the listed work; do not start qtg-mainnet.'
  exit 2
fi

After the JEP-82 migration is applied and this audit is empty, build the exact checked-out source, record its image ID/revision, then recreate only mainnet:

docker compose \
  -f infra/docker-compose.yml \
  -f infra/docker-compose.stargate-kms-mainnet.yml \
  build qtg-mainnet

expected_image_id=$(docker compose \
  -f infra/docker-compose.yml \
  -f infra/docker-compose.stargate-kms-mainnet.yml \
  images -q qtg-mainnet)
test -n "$expected_image_id"
test "$(docker image inspect -f '{{ index .Config.Labels "org.opencontainers.image.revision" }}' "$expected_image_id")" \
  = "$QTG_SOURCE_REVISION"

docker compose \
  -f infra/docker-compose.yml \
  -f infra/docker-compose.stargate-kms-mainnet.yml \
  up -d --no-deps --force-recreate qtg-mainnet

running_image_id=$(docker inspect -f '{{.Image}}' qtg-mainnet)
test "$running_image_id" = "$expected_image_id"

Stop immediately; do not recreate or run a drill if any of the following is true:

• config --quiet rejects a required KMS value, the dedicated profile directory is absent, or it contains credentials beyond the drill profile.
• The pre-start database audit returns any row. Do not start workers around non-drill work or a reused signer; resolve it first.
• The intended KMS profile cannot perform the required signer health check, or its derived EVM address does not equal the authority signer and approved round-trip sender.
• MG_EVM_RPC_ENDPOINTS_JSON lacks an explicit non-public endpoint for either selected chain; the drill refuses default RPC endpoints.
• Either endpoint cannot serve the destination observer’s GUID-bound paged eth_getLogs lookback. The observer snapshots the destination head and reads the 3,001-block safety window in newest-first, inclusive 10-block pages (then only new blocks plus a small reorg overlap after a complete miss). If a provider rejects even that bounded read or the scan exceeds its explicit page budget, preserve the saved hash/GUID and investigate the read-only observer; never retry or rebroadcast the send.
• The migration head, registry pool trust/preapproval, enabled path baseline, destination allowlist, or signer expected-identity gate is not satisfied.
• Any existing node has ambiguous Stargate broadcast evidence. Preserve the known hash and recover/poll it; never initiate a second send as a retry.

Using this overlay enables a signing-capable process; it is not approval to sign or broadcast. The drill still requires its separate one-time execution approval.