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 purposes: admin, all
• 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) use the read purpose, 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

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
• created_at
• updated_at

Route modules return asdict(row) payloads, so the JSON shape is the service dataclass shape directly.

2.4 Typical operator workflow

The most common operator sequence is below.

1. Seed chain registry from discovered pools. python -m qtg.pro.tools.seed_stargate_chain_registry --operator-label ops.seed
2. Seed path baselines from a reviewed JSON payload. python -m qtg.pro.tools.seed_stargate_path_baseline path-baselines.json --operator-label ops.seed
3. Check completeness against template coverage. python -m qtg.pro.tools.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 discovery. Discovery/refresh remains in the tooling and executor-side flows; the admin routes are for reviewed operator mutations after those workflows produce inputs.