> ## Documentation Index > Fetch the complete documentation index at: https://jephalabs.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # 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.