Document ID: GOS-80-CHAIN-SINGLE-OP Version: 0.1.0 Status: DRAFT Owner Role: CHAIN_OFFICER Last Review Date: 2026-03-04 Next Review Date: 2026-04-04

Purpose

Run the multichain orchestration path as one operator (you + Copilot) while keeping artifacts team-friendly for later handoff.

Commands

• Start local Kafka broker (Redpanda via Docker):
  • npm run kafka:up
• Stop local Kafka broker:
  • npm run kafka:down
• Tail local Kafka broker logs:
  • npm run kafka:logs
• Start dev signer boundary:
  • npm run signer:dev
• Run single-operator E2E orchestration:
  • npm run single-operator:e2e
• Inspect/replay DLQ index:
  • npm run single-operator:replay-dlq
• Real KafkaJS producer/consumer demo:
  • npm run kafka:demo
• KES orchestrator Kafka consumer demo:
  • npm run kafka:kes-consumer
• KES Kafka smoke (up -> consumer -> API trigger -> down):
  • npm run kafka:kes-smoke
• One-shot Kafka smoke (up -> demo -> down):
  • npm run kafka:smoke
  • Optional retry tuning:
    • KAFKA_SMOKE_UP_RETRIES (default 3)
    • KAFKA_SMOKE_UP_RETRY_DELAY_MS (default 4000)
    • KAFKA_SMOKE_DEMO_RETRIES (default 2)
    • KAFKA_SMOKE_DEMO_RETRY_DELAY_MS (default 2000)
    • KAFKA_SMOKE_POST_UP_WAIT_MS (default 3000)
    • KAFKA_SMOKE_REMOVE_ORPHANS (default false, when true adds --remove-orphans to kafka:up and kafka:down)
  • Caution: --remove-orphans may remove non-Kafka containers in the same Compose project (for example local Postgres).

Data Outputs

• Outbox JSONL: tmp/outputs/single_operator_outbox.jsonl
• DLQ JSONL: tmp/outputs/single_operator_dlq.jsonl

Flow Covered

1. milestone.approved
2. mint.requested
3. mint.confirmed
4. anchor.requested
5. anchor.confirmed

Team-Handoff Friendly Pieces

• Shared DTO contracts in financial-layer orchestration module.
• Partition-key enforcement helper (all records keyed by intentId).
• Scripted local runbook with deterministic outputs for QA onboarding.
• KafkaJS bus scaffold for production broker transition:
  • packages/financial-layer/chain/orchestration/kafka-kafkajs.ts

Optional Signer Dev Env

• SIGNER_DEV_PORT (default 4591)
• SIGNER_DEV_HOST (default 127.0.0.1)
• SIGNER_DEV_SECRET (default dev-signer-secret)
• SIGNER_DEV_API_KEY
• SIGNER_DEV_API_KEY_HEADER (default x-signer-api-key)

Kafka Transition Notes

• Keep current stub flow for local deterministic simulation.
• Use KafkaJsOrchestrationBus for real broker environments.
• Preserve the same DTO contracts and intentId key enforcement; only transport changes.

Local broker profile file:

• docker-compose.kafka.yml

Default local broker endpoint:

• 127.0.0.1:9092

Kafka demo environment (optional):

• KAFKA_BROKERS (default 127.0.0.1:9092)
• KAFKA_DEMO_TOPIC (default mint.requested)
• KAFKA_DEMO_INTENT_ID (autogenerated if missing)
• KAFKA_DEMO_GROUP_ID (autogenerated if missing)
• KAFKA_DEMO_CLIENT_ID (default kvary-kafka-demo)
• KAFKA_DEMO_TIMEOUT_MS (default 20000)
• KAFKA_DEMO_WARMUP_MS (default 1000)

KES consumer demo environment (optional):

• KES_ORCHESTRATOR_KAFKA_TOPIC (default kes.orchestrator.events)
• KES_KAFKA_CONSUMER_GROUP_ID (autogenerated if missing)
• KES_KAFKA_CONSUMER_CLIENT_ID (default kvary-kes-consumer-demo)
• KES_KAFKA_CONSUMER_TIMEOUT_MS (default 30000)
• KES_KAFKA_CONSUMER_MAX_MESSAGES (default 10)

KES smoke environment (optional):

• KES_KAFKA_SMOKE_TRIGGER_URL (default http://127.0.0.1:4001/api/v1/kes/orchestrator/cases)
• KES_KAFKA_SMOKE_TRIGGER_TIMEOUT_MS (default 8000)
• KES_KAFKA_SMOKE_WARMUP_MS (default 2000)
• KES_KAFKA_SMOKE_ALLOW_FALLBACK (default true)
• KES_KAFKA_SMOKE_INTENT_ID (autogenerated if missing)

AWS/MSK note:

• For AWS deployment, point KAFKA_BROKERS to your MSK bootstrap brokers.
• Use kafka:demo against MSK; kafka:smoke is intended for local Docker lifecycle.
• AWS environment matrix: docs/80_chain/AWS_MSK_ENV_MATRIX.md
• Production hardening checklist: docs/80_chain/NO_REWORK_MIGRATION_CHECKLIST.md
• Smoke evidence template: docs/80_chain/SMOKE_EVIDENCE_TEMPLATE.md