dev cicd + tron + docs

2026-01-30 16:58:02 +01:00
parent 51f5b0804a
commit c1596296d1
52 changed files with 3695 additions and 0 deletions
--- a/ci/dev/.air.toml
+++ b/ci/dev/.air.toml
@@ -0,0 +1,46 @@
+root = "."
+testdata_dir = "testdata"
+tmp_dir = "tmp"
+
+[build]
+  args_bin = []
+  entrypoint = "./tmp/main"
+  cmd = "go build -o ./tmp/main ."
+  delay = 1000
+  exclude_dir = ["assets", "tmp", "vendor", "testdata"]
+  exclude_file = []
+  exclude_regex = ["_test.go", "_templ.go"]
+  exclude_unchanged = false
+  follow_symlink = false
+  full_bin = ""
+  include_dir = []
+  include_ext = ["go", "tpl", "tmpl", "html"]
+  include_file = []
+  kill_delay = "0s"
+  log = "build-errors.log"
+  poll = false
+  poll_interval = 0
+  post_cmd = []
+  pre_cmd = []
+  rerun = false
+  rerun_delay = 500
+  send_interrupt = false
+  stop_on_error = false
+
+[color]
+  app = ""
+  build = "yellow"
+  main = "magenta"
+  runner = "green"
+  watcher = "cyan"
+
+[log]
+  main_only = false
+  time = false
+
+[misc]
+  clean_on_exit = false
+
+[screen]
+  clear_on_rebuild = false
+  keep_scroll = true
--- a/ci/dev/CHECKLIST.md
+++ b/ci/dev/CHECKLIST.md
@@ -0,0 +1,160 @@
+# Development Environment - Implementation Checklist
+
+## ✅ Completed
+
+### Infrastructure (3/3)
+- [x] MongoDB Replica Set (3 nodes with auto-init)
+- [x] NATS with JetStream
+- [x] Vault (single node for application data)
+
+### Application Services (12/12)
+- [x] Discovery Service
+- [x] FX Oracle Service
+- [x] FX Ingestor Service
+- [x] Billing Fees Service
+- [x] Ledger Service
+- [x] Payments Orchestrator Service
+- [x] Chain Gateway Service
+- [x] MNTX Gateway Service
+- [x] TGSettle Gateway Service
+- [x] Notification Service
+- [x] BFF (Server) Service
+- [x] Frontend (Flutter Web)
+
+### Configuration Files
+- [x] docker-compose.dev.yml (complete with all services)
+- [x] .env.dev (plaintext credentials template)
+- [x] Makefile (full command suite)
+- [x] .gitignore (updated with dev files)
+
+### Dockerfiles (12/12)
+- [x] ci/dev/discovery.dockerfile
+- [x] ci/dev/ledger.dockerfile
+- [x] ci/dev/billing-fees.dockerfile
+- [x] ci/dev/fx-oracle.dockerfile
+- [x] ci/dev/fx-ingestor.dockerfile
+- [x] ci/dev/payments-orchestrator.dockerfile
+- [x] ci/dev/chain-gateway.dockerfile
+- [x] ci/dev/mntx-gateway.dockerfile
+- [x] ci/dev/tgsettle-gateway.dockerfile
+- [x] ci/dev/notification.dockerfile
+- [x] ci/dev/bff.dockerfile
+- [x] ci/dev/frontend.dockerfile
+
+### Scripts & Utilities
+- [x] ci/dev/mongo.key (MongoDB keyfile)
+- [x] ci/dev/vault/config.hcl (Vault config)
+- [x] Vault templates removed (not needed for dev)
+- [x] Makefile commands for all operations
+
+### Documentation
+- [x] SETUP.md (comprehensive setup guide)
+- [x] ci/dev/README.md (quick reference)
+- [x] ci/dev/CHECKLIST.md (this file)
+- [x] CLAUDE.md (updated with dev commands)
+
+## 🎯 Ready to Test
+
+### Initial Setup
+```bash
+make init
+```
+
+### Start Environment
+```bash
+make up
+```
+
+### Initialize Vault (if needed)
+```bash
+make vault-init
+```
+
+### Check Status
+```bash
+make status
+make list-services
+```
+
+## 📊 Service Dependencies
+
+```
+Infrastructure Layer:
+  ├─ MongoDB (dev-mongo-1, dev-mongo-2, dev-mongo-3)
+  ├─ NATS (dev-nats)
+  └─ Vault (dev-vault)
+
+Service Layer:
+  ├─ dev-discovery → [nats]
+  ├─ dev-fx-oracle → [mongo, nats]
+  ├─ dev-fx-ingestor → [mongo, nats]
+  ├─ dev-billing-fees → [mongo, nats, fx-oracle]
+  ├─ dev-ledger → [mongo, nats, discovery, billing-fees]
+  ├─ dev-payments-orchestrator → [mongo, nats, ledger, billing-fees]
+  ├─ dev-chain-gateway → [mongo, nats, discovery, vault]
+  ├─ dev-mntx-gateway → [nats, discovery, vault]
+  ├─ dev-tgsettle-gateway → [mongo, nats, discovery, vault]
+  ├─ dev-notification → [nats]
+  ├─ dev-bff → [mongo, nats, ledger, payments, chain-gateway]
+  └─ dev-frontend → [bff]
+```
+
+## 🔍 Validation Steps
+
+### 1. Infrastructure
+- [ ] MongoDB replica set initializes correctly
+- [ ] NATS is accessible and healthy
+- [ ] Vault starts and can be initialized
+
+### 2. Core Services
+- [ ] Discovery service starts and is healthy
+- [ ] Ledger service connects to MongoDB and NATS
+- [ ] Billing fees service can query FX oracle
+- [ ] FX oracle provides quotes
+
+### 3. Payment Flow
+- [ ] Payments orchestrator can communicate with ledger
+- [ ] Payments orchestrator can calculate fees
+- [ ] Payment plan execution works
+
+### 4. Gateways
+- [ ] Chain gateway connects to Vault for keys
+- [ ] MNTX gateway is reachable
+- [ ] TGSettle gateway connects to Telegram
+
+### 5. Frontend
+- [ ] BFF serves API endpoints
+- [ ] Frontend builds successfully
+- [ ] Frontend connects to BFF
+
+## 🐛 Known Considerations
+
+1. **Vault Secrets**: Services using Vault (chain, mntx, tgsettle) need secrets populated
+2. **External APIs**: MNTX and TGSettle need API credentials from Vault
+3. **Blockchain**: Chain gateway needs blockchain node URLs and private keys
+4. **Build Time**: Frontend build takes ~5-10 minutes (Flutter compile)
+
+## 📝 Post-Setup Tasks
+
+- [ ] Populate Vault with blockchain keys for Chain Gateway
+- [ ] Add MNTX API credentials to Vault
+- [ ] Add TGSettle (Telegram) credentials to Vault
+- [ ] Seed test data into MongoDB
+- [ ] Configure blockchain RPC endpoints
+- [ ] Test full payment flow end-to-end
+
+## 🚀 Next Development Steps
+
+1. Test `make init && make up`
+2. Verify all services start successfully
+3. Check logs for any errors
+4. Test service-to-service communication
+5. Add seed data scripts
+6. Create integration tests
+
+---
+
+**Status**: ✅ COMPLETE - Ready for testing
+**Date**: 2026-01-27
+**Build System**: Docker Compose + Makefile
+**Total Services**: 12 application + 3 infrastructure = 15 containers
--- a/ci/dev/Caddyfile.dev
+++ b/ci/dev/Caddyfile.dev
@@ -0,0 +1,101 @@
+########################################
+# Development Caddyfile for Sendico
+########################################
+{
+  # No ACME email needed for local dev
+  auto_https off
+}
+
+:80 {
+  vars static_root /usr/share/pweb
+
+  encode zstd gzip
+
+  route {
+    ########################################
+    # Backend API - proxy to dev-bff
+    ########################################
+    handle /api/v1/* {
+      reverse_proxy dev-bff:8080 {
+        health_uri /api/v1/health
+        health_interval 15s
+        health_timeout 4s
+        health_status 2xx
+      }
+      header Cache-Control "no-cache, no-store, must-revalidate"
+    }
+
+    # Telegram webhook -> notification service
+    handle /telegram/webhook {
+      reverse_proxy dev-notification:8081
+    }
+
+    # Monetix callbacks -> mntx gateway
+    handle /gateway/m/* {
+      rewrite * /monetix/callback
+      reverse_proxy dev-mntx-gateway:8084
+      header Cache-Control "no-cache, no-store, must-revalidate"
+    }
+
+    ########################################
+    # Static assets
+    ########################################
+    handle /version.json {
+      root * {vars.static_root}
+      file_server
+      header Cache-Control "no-cache"
+    }
+
+    handle /*.js {
+      root * {vars.static_root}
+      file_server
+      header Cache-Control "public, max-age=3600"
+    }
+
+    handle /assets/* {
+      root * {vars.static_root}
+      file_server
+      header Cache-Control "public, max-age=86400"
+    }
+
+    handle /canvaskit/* {
+      root * {vars.static_root}
+      file_server
+      header Cache-Control "public, max-age=86400"
+    }
+
+    handle /icons/* {
+      root * {vars.static_root}
+      file_server
+      header Cache-Control "public, max-age=86400"
+    }
+
+    handle /*.html {
+      root * {vars.static_root}
+      file_server
+      header Cache-Control "no-cache"
+    }
+
+    handle /*.css {
+      root * {vars.static_root}
+      file_server
+      header Cache-Control "public, max-age=3600"
+    }
+
+    handle /*.json {
+      root * {vars.static_root}
+      file_server
+      header Cache-Control "public, max-age=3600"
+    }
+
+    ########################################
+    # SPA fallback - serves index.html for all routes
+    ########################################
+    handle {
+      root * {vars.static_root}
+      try_files {path} /index.html
+      file_server
+      header Cache-Control "no-cache"
+    }
+  }
+}
--- a/ci/dev/README.md
+++ b/ci/dev/README.md
@@ -0,0 +1,124 @@
+# Sendico Development Environment
+
+Docker Compose + Makefile build system for local development.
+
+## Architecture
+
+**Infrastructure:**
+- MongoDB replica set (3 nodes) - credentials in `.env.dev`
+- NATS with JetStream - credentials in `.env.dev`
+- Vault (single node) - for application data ONLY (blockchain keys, external API keys)
+
+**Services:**
+- Discovery, Ledger, Billing Fees, Billing Documents, FX Oracle, Payments Orchestrator
+- Chain Gateway, MNTX Gateway, TGSettle Gateway
+- FX Ingestor, Notification, BFF (Server), Frontend
+
+## Quick Start
+
+```bash
+# 1. Initialize environment (first time)
+make init
+
+# 2. Start all services
+make up
+
+# 3. Initialize Vault (if services need it for application data)
+make vault-init
+
+# 4. View logs
+make logs SERVICE=ledger
+
+# 5. Stop everything
+make down
+```
+
+## Credentials
+
+All in `.env.dev` (plaintext for dev):
+- MongoDB: `dev_root` / `dev_password_123`
+- NATS: `dev_nats` / `nats_password_123`
+- Vault: Run `make vault-init` to get root token
+
+## Common Commands
+
+```bash
+make build                  # Build all images
+make up                     # Start environment
+make down                   # Stop environment
+make logs SERVICE=ledger    # View service logs
+make rebuild SERVICE=ledger # Rebuild specific service
+make proto                  # Regenerate protobuf
+make clean                  # Remove everything
+make status                 # Check service status
+```
+
+## Vault Usage
+
+**Vault is ONLY for application data**, not infrastructure secrets!
+
+Examples:
+- Blockchain private keys (Chain Gateway)
+- External API keys (MNTX, TGSettle)
+- Production-like secrets
+
+Infrastructure (MongoDB, NATS) uses plain `.env.dev` credentials.
+
+## Network
+
+All services on `sendico-dev` network. Vault also on `cicd` network to connect to infra Vault if needed.
+
+## Rebuilding Services
+
+After code changes:
+
+```bash
+# Rebuild specific service
+make rebuild SERVICE=ledger
+
+# Or manually
+docker compose -f docker-compose.dev.yml build ledger
+docker compose -f docker-compose.dev.yml up -d --force-recreate ledger
+```
+
+## Adding New Services
+
+1. Create Dockerfile: `ci/dev/yourservice.dockerfile`
+2. Add service to `docker-compose.dev.yml`
+3. Use environment variables from `.env.dev`
+4. Connect to `sendico-dev` network
+
+## Troubleshooting
+
+**MongoDB replica set not initializing:**
+```bash
+make down
+make up
+# Wait for health checks, then:
+docker logs dev-mongo-init
+```
+
+**Vault sealed:**
+```bash
+make vault-init
+# Save the unseal key and root token from vault-keys.txt
+```
+
+**Service can't connect to MongoDB:**
+- Check replica set: `docker exec -it dev-mongo-1 mongosh -u dev_root -p dev_password_123 --eval "rs.status()"`
+- Ensure `dev-mongo-init` completed: `docker ps -a | grep init`
+
+**Proto generation errors:**
+```bash
+make proto
+# Check output for missing dependencies
+```
+
+## Files
+
+- `docker-compose.dev.yml` - All services
+- `.env.dev` - Plaintext credentials
+- `Makefile` - Build commands
+- `ci/dev/*.dockerfile` - Service builds
+- `ci/dev/mongo.key` - MongoDB replica set key
+- `ci/dev/vault/config.hcl` - Vault config
--- a/ci/dev/bff.dockerfile
+++ b/ci/dev/bff.dockerfile
@@ -0,0 +1,52 @@
+# Development Dockerfile for BFF (Server) Service with Air hot reload
+
+FROM golang:alpine AS builder
+
+RUN apk add --no-cache bash git build-base protoc protobuf-dev && \
+    go install google.golang.org/protobuf/cmd/protoc-gen-go@latest && \
+    go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest && \
+    go install github.com/air-verse/air@latest
+
+WORKDIR /src
+
+COPY api/proto ./api/proto
+COPY api/pkg ./api/pkg
+COPY ci/scripts/proto/generate.sh ./ci/scripts/proto/
+RUN bash ci/scripts/proto/generate.sh
+
+# Copy service dependencies (needed for go.mod replace directives)
+COPY api/ledger ./api/ledger
+COPY api/payments/orchestrator ./api/payments/orchestrator
+COPY api/gateway/chain ./api/gateway/chain
+COPY api/billing/fees ./api/billing/fees
+COPY api/fx/oracle ./api/fx/oracle
+COPY api/fx/storage ./api/fx/storage
+COPY api/gateway/mntx ./api/gateway/mntx
+
+# Runtime stage for development with Air
+FROM golang:alpine
+
+RUN apk add --no-cache bash git build-base && \
+    go install github.com/air-verse/air@latest
+
+WORKDIR /src
+
+# Copy generated proto and pkg from builder
+COPY --from=builder /src/api/proto ./api/proto
+COPY --from=builder /src/api/pkg ./api/pkg
+
+# Copy service dependencies
+COPY --from=builder /src/api/ledger ./api/ledger
+COPY --from=builder /src/api/payments/orchestrator ./api/payments/orchestrator
+COPY --from=builder /src/api/gateway/chain ./api/gateway/chain
+COPY --from=builder /src/api/billing/fees ./api/billing/fees
+COPY --from=builder /src/api/fx/oracle ./api/fx/oracle
+COPY --from=builder /src/api/fx/storage ./api/fx/storage
+COPY --from=builder /src/api/gateway/mntx ./api/gateway/mntx
+
+# Source code will be mounted at runtime
+WORKDIR /src/api/server
+
+EXPOSE 8080
+
+CMD ["air", "-c", ".air.toml", "--", "-config.file", "/app/config.yml", "-debug"]
--- a/ci/dev/billing-documents.dockerfile
+++ b/ci/dev/billing-documents.dockerfile
@@ -0,0 +1,39 @@
+# Development Dockerfile for Billing Documents Service with Air hot reload
+
+FROM golang:alpine AS builder
+
+# Install build dependencies
+RUN apk add --no-cache bash git build-base protoc protobuf-dev && \
+    go install google.golang.org/protobuf/cmd/protoc-gen-go@latest && \
+    go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest && \
+    go install github.com/air-verse/air@latest
+
+WORKDIR /src
+
+# Copy proto and pkg first (changes less frequently)
+COPY api/proto ./api/proto
+COPY api/pkg ./api/pkg
+COPY ci/scripts/proto/generate.sh ./ci/scripts/proto/
+
+# Generate protos (cached if proto files unchanged)
+RUN bash ci/scripts/proto/generate.sh
+
+# Runtime stage for development with Air
+FROM golang:alpine
+
+RUN apk add --no-cache bash git build-base && \
+    go install github.com/air-verse/air@latest
+
+WORKDIR /src
+
+# Copy generated proto and pkg from builder
+COPY --from=builder /src/api/proto ./api/proto
+COPY --from=builder /src/api/pkg ./api/pkg
+
+# Source code will be mounted at runtime to /src/api/billing/documents
+WORKDIR /src/api/billing/documents
+
+EXPOSE 50061 9409
+
+# Use Air for hot reload
+CMD ["air", "-c", ".air.toml", "--", "-config.file", "/app/config.yml", "-debug"]
--- a/ci/dev/billing-fees.dockerfile
+++ b/ci/dev/billing-fees.dockerfile
@@ -0,0 +1,42 @@
+# Development Dockerfile for Billing Fees Service with Air hot reload
+
+FROM golang:alpine AS builder
+
+RUN apk add --no-cache bash git build-base protoc protobuf-dev && \
+    go install google.golang.org/protobuf/cmd/protoc-gen-go@latest && \
+    go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest && \
+    go install github.com/air-verse/air@latest
+
+WORKDIR /src
+
+COPY api/proto ./api/proto
+COPY api/pkg ./api/pkg
+COPY ci/scripts/proto/generate.sh ./ci/scripts/proto/
+RUN bash ci/scripts/proto/generate.sh
+
+# Copy service dependencies (needed for go.mod replace directives)
+COPY api/fx/oracle ./api/fx/oracle
+COPY api/fx/storage ./api/fx/storage
+
+# Runtime stage for development with Air
+FROM golang:alpine
+
+RUN apk add --no-cache bash git build-base && \
+    go install github.com/air-verse/air@latest
+
+WORKDIR /src
+
+# Copy generated proto and pkg from builder
+COPY --from=builder /src/api/proto ./api/proto
+COPY --from=builder /src/api/pkg ./api/pkg
+
+# Copy service dependencies
+COPY --from=builder /src/api/fx/oracle ./api/fx/oracle
+COPY --from=builder /src/api/fx/storage ./api/fx/storage
+
+# Source code will be mounted at runtime
+WORKDIR /src/api/billing/fees
+
+EXPOSE 50060 9402
+
+CMD ["air", "-c", ".air.toml", "--", "-config.file", "/app/config.yml", "-debug"]
--- a/ci/dev/chain-gateway.dockerfile
+++ b/ci/dev/chain-gateway.dockerfile
@@ -0,0 +1,40 @@
+# Development Dockerfile for chain-gateway Service with Air hot reload
+
+FROM golang:alpine AS builder
+
+RUN apk add --no-cache bash git build-base protoc protobuf-dev && \
+    go install google.golang.org/protobuf/cmd/protoc-gen-go@latest && \
+    go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest && \
+    go install github.com/air-verse/air@latest
+
+WORKDIR /src
+
+COPY api/proto ./api/proto
+COPY api/pkg ./api/pkg
+COPY ci/scripts/proto/generate.sh ./ci/scripts/proto/
+RUN bash ci/scripts/proto/generate.sh
+
+# Runtime stage for development with Air
+FROM golang:alpine
+
+RUN apk add --no-cache bash git build-base && \
+    go install github.com/air-verse/air@latest
+
+WORKDIR /src
+
+# Copy generated proto and pkg from builder
+COPY --from=builder /src/api/proto ./api/proto
+COPY --from=builder /src/api/pkg ./api/pkg
+
+# Copy dev-specific entrypoint script
+COPY ci/dev/entrypoints/chain-gateway.sh /app/entrypoint.sh
+RUN chmod +x /app/entrypoint.sh
+
+# Source code will be mounted at runtime
+WORKDIR /src/api/gateway/chain
+
+EXPOSE 50070 9404
+
+# Use entrypoint wrapper to load vault token
+ENTRYPOINT ["/app/entrypoint.sh"]
+CMD ["air", "-c", ".air.toml", "--", "-config.file", "/app/config.yml", "-debug"]
--- a/ci/dev/discovery.dockerfile
+++ b/ci/dev/discovery.dockerfile
@@ -0,0 +1,34 @@
+# Development Dockerfile for discovery Service with Air hot reload
+
+FROM golang:alpine AS builder
+
+RUN apk add --no-cache bash git build-base protoc protobuf-dev && \
+    go install google.golang.org/protobuf/cmd/protoc-gen-go@latest && \
+    go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest && \
+    go install github.com/air-verse/air@latest
+
+WORKDIR /src
+
+COPY api/proto ./api/proto
+COPY api/pkg ./api/pkg
+COPY ci/scripts/proto/generate.sh ./ci/scripts/proto/
+RUN bash ci/scripts/proto/generate.sh
+
+# Runtime stage for development with Air
+FROM golang:alpine
+
+RUN apk add --no-cache bash git build-base && \
+    go install github.com/air-verse/air@latest
+
+WORKDIR /src
+
+# Copy generated proto and pkg from builder
+COPY --from=builder /src/api/proto ./api/proto
+COPY --from=builder /src/api/pkg ./api/pkg
+
+# Source code will be mounted at runtime
+WORKDIR /src/api/discovery
+
+EXPOSE 9407
+
+CMD ["air", "-c", ".air.toml", "--", "-config.file", "/app/config.yml", "-debug"]
--- a/ci/dev/entrypoints/chain-gateway.sh
+++ b/ci/dev/entrypoints/chain-gateway.sh
@@ -0,0 +1,17 @@
+#!/bin/sh
+set -eu
+
+# Load Vault token from file if VAULT_TOKEN_FILE is set
+if [ -n "${VAULT_TOKEN_FILE:-}" ] && [ -f "${VAULT_TOKEN_FILE}" ]; then
+  token="$(cat "${VAULT_TOKEN_FILE}" 2>/dev/null | tr -d '[:space:]')"
+  if [ -n "${token}" ]; then
+    export VAULT_TOKEN="${token}"
+  fi
+fi
+
+if [ -z "${VAULT_TOKEN:-}" ]; then
+  echo "[entrypoint] VAULT_TOKEN is not set; expected Vault Agent sink to write a token to ${VAULT_TOKEN_FILE:-/run/vault/token}" >&2
+fi
+
+# Execute the command passed as arguments (e.g., air)
+exec "$@"
--- a/ci/dev/entrypoints/tron-gateway.sh
+++ b/ci/dev/entrypoints/tron-gateway.sh
@@ -0,0 +1,17 @@
+#!/bin/sh
+set -eu
+
+# Load Vault token from file if VAULT_TOKEN_FILE is set
+if [ -n "${VAULT_TOKEN_FILE:-}" ] && [ -f "${VAULT_TOKEN_FILE}" ]; then
+  token="$(cat "${VAULT_TOKEN_FILE}" 2>/dev/null | tr -d '[:space:]')"
+  if [ -n "${token}" ]; then
+    export VAULT_TOKEN="${token}"
+  fi
+fi
+
+if [ -z "${VAULT_TOKEN:-}" ]; then
+  echo "[entrypoint] VAULT_TOKEN is not set; expected Vault Agent sink to write a token to ${VAULT_TOKEN_FILE:-/run/vault/token}" >&2
+fi
+
+# Execute the command passed as arguments (e.g., air)
+exec "$@"
--- a/ci/dev/frontend.dockerfile
+++ b/ci/dev/frontend.dockerfile
@@ -0,0 +1,57 @@
+# Development Dockerfile for Frontend (Flutter Web)
+
+FROM dart:stable AS web_builder
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    git \
+    curl \
+    unzip \
+    xz-utils \
+    libglu1-mesa \
+    ca-certificates \
+  && apt-get clean \
+  && rm -rf /var/lib/apt/lists/*
+
+RUN useradd -ms /bin/bash flutteruser
+
+ENV PATH="/home/flutteruser/flutter/bin:${PATH}"
+
+USER flutteruser
+WORKDIR /home/flutteruser
+
+# Install Flutter
+RUN git clone --branch stable --depth 1 https://github.com/flutter/flutter.git \
+  && flutter config --enable-web \
+  && flutter precache --web \
+  && flutter upgrade
+
+COPY --chown=flutteruser:flutteruser frontend /home/flutteruser/app
+
+# Replace production config with dev config
+WORKDIR /home/flutteruser/app/pshared
+RUN cp lib/config/common_dev.dart lib/config/common.dart
+
+# Build shared package with code generation
+RUN flutter clean \
+  && flutter pub get \
+  && dart run build_runner build --delete-conflicting-outputs
+
+# Build the web client
+WORKDIR /home/flutteruser/app/pweb
+RUN flutter clean \
+  && flutter pub get \
+  && flutter build web --release --no-tree-shake-icons
+
+# Runtime stage with Caddy
+FROM caddy:alpine AS runtime
+
+WORKDIR /usr/share/pweb
+
+COPY --from=web_builder /home/flutteruser/app/pweb/build/web /usr/share/pweb
+
+# Copy Caddy config (will be mounted from host)
+# COPY frontend/pweb/caddy/Caddyfile /etc/caddy/Caddyfile
+
+EXPOSE 80
+
+CMD ["caddy", "run", "--config", "/etc/caddy/Caddyfile", "--adapter", "caddyfile"]
--- a/ci/dev/fx-ingestor.dockerfile
+++ b/ci/dev/fx-ingestor.dockerfile
@@ -0,0 +1,40 @@
+# Development Dockerfile for fx-ingestor Service with Air hot reload
+
+FROM golang:alpine AS builder
+
+RUN apk add --no-cache bash git build-base protoc protobuf-dev && \
+    go install google.golang.org/protobuf/cmd/protoc-gen-go@latest && \
+    go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest && \
+    go install github.com/air-verse/air@latest
+
+WORKDIR /src
+
+COPY api/proto ./api/proto
+COPY api/pkg ./api/pkg
+COPY ci/scripts/proto/generate.sh ./ci/scripts/proto/
+RUN bash ci/scripts/proto/generate.sh
+
+# Copy service dependencies (needed for go.mod replace directives)
+COPY api/fx/storage ./api/fx/storage
+
+# Runtime stage for development with Air
+FROM golang:alpine
+
+RUN apk add --no-cache bash git build-base && \
+    go install github.com/air-verse/air@latest
+
+WORKDIR /src
+
+# Copy generated proto and pkg from builder
+COPY --from=builder /src/api/proto ./api/proto
+COPY --from=builder /src/api/pkg ./api/pkg
+
+# Copy service dependencies
+COPY --from=builder /src/api/fx/storage ./api/fx/storage
+
+# Source code will be mounted at runtime
+WORKDIR /src/api/fx/ingestor
+
+EXPOSE 9102
+
+CMD ["air", "-c", ".air.toml", "--", "-config.file", "/app/config.yml", "-debug"]
--- a/ci/dev/fx-oracle.dockerfile
+++ b/ci/dev/fx-oracle.dockerfile
@@ -0,0 +1,40 @@
+# Development Dockerfile for fx-oracle Service with Air hot reload
+
+FROM golang:alpine AS builder
+
+RUN apk add --no-cache bash git build-base protoc protobuf-dev && \
+    go install google.golang.org/protobuf/cmd/protoc-gen-go@latest && \
+    go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest && \
+    go install github.com/air-verse/air@latest
+
+WORKDIR /src
+
+COPY api/proto ./api/proto
+COPY api/pkg ./api/pkg
+COPY ci/scripts/proto/generate.sh ./ci/scripts/proto/
+RUN bash ci/scripts/proto/generate.sh
+
+# Copy service dependencies (needed for go.mod replace directives)
+COPY api/fx/storage ./api/fx/storage
+
+# Runtime stage for development with Air
+FROM golang:alpine
+
+RUN apk add --no-cache bash git build-base && \
+    go install github.com/air-verse/air@latest
+
+WORKDIR /src
+
+# Copy generated proto and pkg from builder
+COPY --from=builder /src/api/proto ./api/proto
+COPY --from=builder /src/api/pkg ./api/pkg
+
+# Copy service dependencies
+COPY --from=builder /src/api/fx/storage ./api/fx/storage
+
+# Source code will be mounted at runtime
+WORKDIR /src/api/fx/oracle
+
+EXPOSE 50051 9400
+
+CMD ["air", "-c", ".air.toml", "--", "-config.file", "/app/config.yml", "-debug"]
--- a/ci/dev/ledger.dockerfile
+++ b/ci/dev/ledger.dockerfile
@@ -0,0 +1,39 @@
+# Development Dockerfile for Ledger Service with Air hot reload
+
+FROM golang:alpine AS builder
+
+# Install build dependencies
+RUN apk add --no-cache bash git build-base protoc protobuf-dev && \
+    go install google.golang.org/protobuf/cmd/protoc-gen-go@latest && \
+    go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest && \
+    go install github.com/air-verse/air@latest
+
+WORKDIR /src
+
+# Copy proto and pkg first (changes less frequently)
+COPY api/proto ./api/proto
+COPY api/pkg ./api/pkg
+COPY ci/scripts/proto/generate.sh ./ci/scripts/proto/
+
+# Generate protos (cached if proto files unchanged)
+RUN bash ci/scripts/proto/generate.sh
+
+# Runtime stage for development with Air
+FROM golang:alpine
+
+RUN apk add --no-cache bash git build-base && \
+    go install github.com/air-verse/air@latest
+
+WORKDIR /src
+
+# Copy generated proto and pkg from builder
+COPY --from=builder /src/api/proto ./api/proto
+COPY --from=builder /src/api/pkg ./api/pkg
+
+# Source code will be mounted at runtime to /src/api/ledger
+WORKDIR /src/api/ledger
+
+EXPOSE 50052 9401
+
+# Use Air for hot reload
+CMD ["air", "-c", ".air.toml", "--", "-config.file", "/app/config.yml", "-debug"]
--- a/ci/dev/mntx-gateway.dockerfile
+++ b/ci/dev/mntx-gateway.dockerfile
@@ -0,0 +1,34 @@
+# Development Dockerfile for mntx-gateway Service with Air hot reload
+
+FROM golang:alpine AS builder
+
+RUN apk add --no-cache bash git build-base protoc protobuf-dev && \
+    go install google.golang.org/protobuf/cmd/protoc-gen-go@latest && \
+    go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest && \
+    go install github.com/air-verse/air@latest
+
+WORKDIR /src
+
+COPY api/proto ./api/proto
+COPY api/pkg ./api/pkg
+COPY ci/scripts/proto/generate.sh ./ci/scripts/proto/
+RUN bash ci/scripts/proto/generate.sh
+
+# Runtime stage for development with Air
+FROM golang:alpine
+
+RUN apk add --no-cache bash git build-base && \
+    go install github.com/air-verse/air@latest
+
+WORKDIR /src
+
+# Copy generated proto and pkg from builder
+COPY --from=builder /src/api/proto ./api/proto
+COPY --from=builder /src/api/pkg ./api/pkg
+
+# Source code will be mounted at runtime
+WORKDIR /src/api/gateway/mntx
+
+EXPOSE 50075 9405 8084
+
+CMD ["air", "-c", ".air.toml", "--", "-config.file", "/app/config.yml", "-debug"]
--- a/ci/dev/mongo.key
+++ b/ci/dev/mongo.key
@@ -0,0 +1 @@
+FyzfUWK+e1eja+tKfkBhLBPHK34pQgsTkgsq8jxocQCt95k5dxbhw8loB+wyZ2LijIXRjGqraurKEHIl4bF12C05pRlazIyiJXA7T2iQzFtEnJW7IQM1rRWcnm5ZKwxlnnjF4t+5E48SUnXUq587iZV+osrHpGxIHu7WKMtRXE6kD+allogQ+6TCcFu8dDg4ruyC1WUkXh/5ivoFyzFE9hK5WDPo8/dURPav8j+rhaP6+ZWKisfzvssVNiLA3jyb+NYiTBgWkVXk9RXH1SpyrQZOHaOon7Kr57KQnksBrv/yJa75FfwZJagpWUkSbqtpz20e8Jimh/1c+fzE8JR0wFd0eprMQQbZ0WM1hadi5FP5I0e883nLh2brUUI9MUC0sO/+qAL7Giv6+eNhrVWfrJBA0TNQ09AygqBrgM0JJGxHe8OBtlQWWcAI58rtSU2eJmNiwMkyzccv3Z7zknjZ4Y/dGTNQ7ckzEyRQE2u+Ujgs1bje/IS+geFieVpwGoRuKyBqQsnH2uKO/M1wrMwGyPo+5AMKhXtYuMCQoz5jNuRFmOxQq/8Jykg07Z2hntoky3nvWAlDgh3B/mXJmZzi4KfXIW1xnNGzxDMnHeuNcCxAe7vlHkLX6xU74DuWUYYi92Sd6oLeyfxZqoqwgO3SEqfErDC3bOIAQBiJHKs+8UwhbfUoEdX/pLenAOPIcq1fcRQIOd/PKE/USlYGFao8mluBqJuXkw8iPeMQEBepuovebTDxIM4whzWQmMqKm/Xn/CZNhv3CISQvGg0IIqNL6q8FxFSRc7aa0ezUMpMFQBt20muL0xz8DGxdzTOqUWXr8ac2JQH0A66UXYW8iBlP3ZPh37BURBVQTB+++uF2p72jGhWHcE873ELV5Xq7LeextIDcz4L8O+C0K8v7v9tsI35PJR93+jNOS8phEkanvN2Yo6v4W1GQ8oBqbFd9R0KIwxgL7iK1H9pfA7lIeBavHjEjz8FqFxltpqz9mHvop41Sybp6
--- a/ci/dev/notification.dockerfile
+++ b/ci/dev/notification.dockerfile
@@ -0,0 +1,34 @@
+# Development Dockerfile for notification Service with Air hot reload
+
+FROM golang:alpine AS builder
+
+RUN apk add --no-cache bash git build-base protoc protobuf-dev && \
+    go install google.golang.org/protobuf/cmd/protoc-gen-go@latest && \
+    go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest && \
+    go install github.com/air-verse/air@latest
+
+WORKDIR /src
+
+COPY api/proto ./api/proto
+COPY api/pkg ./api/pkg
+COPY ci/scripts/proto/generate.sh ./ci/scripts/proto/
+RUN bash ci/scripts/proto/generate.sh
+
+# Runtime stage for development with Air
+FROM golang:alpine
+
+RUN apk add --no-cache bash git build-base && \
+    go install github.com/air-verse/air@latest
+
+WORKDIR /src
+
+# Copy generated proto and pkg from builder
+COPY --from=builder /src/api/proto ./api/proto
+COPY --from=builder /src/api/pkg ./api/pkg
+
+# Source code will be mounted at runtime
+WORKDIR /src/api/notification
+
+EXPOSE 8081
+
+CMD ["air", "-c", ".air.toml", "--", "-config.file", "/app/config.yml", "-debug"]
--- a/ci/dev/payments-orchestrator.dockerfile
+++ b/ci/dev/payments-orchestrator.dockerfile
@@ -0,0 +1,50 @@
+# Development Dockerfile for Payments Orchestrator Service with Air hot reload
+
+FROM golang:alpine AS builder
+
+RUN apk add --no-cache bash git build-base protoc protobuf-dev && \
+    go install google.golang.org/protobuf/cmd/protoc-gen-go@latest && \
+    go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest && \
+    go install github.com/air-verse/air@latest
+
+WORKDIR /src
+
+COPY api/proto ./api/proto
+COPY api/pkg ./api/pkg
+COPY ci/scripts/proto/generate.sh ./ci/scripts/proto/
+RUN bash ci/scripts/proto/generate.sh
+
+# Copy service dependencies (needed for go.mod replace directives)
+COPY api/ledger ./api/ledger
+COPY api/billing/fees ./api/billing/fees
+COPY api/fx/oracle ./api/fx/oracle
+COPY api/fx/storage ./api/fx/storage
+COPY api/gateway/chain ./api/gateway/chain
+COPY api/gateway/mntx ./api/gateway/mntx
+
+# Runtime stage for development with Air
+FROM golang:alpine
+
+RUN apk add --no-cache bash git build-base && \
+    go install github.com/air-verse/air@latest
+
+WORKDIR /src
+
+# Copy generated proto and pkg from builder
+COPY --from=builder /src/api/proto ./api/proto
+COPY --from=builder /src/api/pkg ./api/pkg
+
+# Copy service dependencies
+COPY --from=builder /src/api/ledger ./api/ledger
+COPY --from=builder /src/api/billing/fees ./api/billing/fees
+COPY --from=builder /src/api/fx/oracle ./api/fx/oracle
+COPY --from=builder /src/api/fx/storage ./api/fx/storage
+COPY --from=builder /src/api/gateway/chain ./api/gateway/chain
+COPY --from=builder /src/api/gateway/mntx ./api/gateway/mntx
+
+# Source code will be mounted at runtime
+WORKDIR /src/api/payments/orchestrator
+
+EXPOSE 50062 9403
+
+CMD ["air", "-c", ".air.toml", "--", "-config.file", "/app/config.yml", "-debug"]
--- a/ci/dev/scripts/mongo-entrypoint.sh
+++ b/ci/dev/scripts/mongo-entrypoint.sh
@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+# MongoDB entrypoint wrapper for dev environment
+# Reads credentials from Vault secrets and initializes MongoDB
+set -euo pipefail
+
+# Read credentials from Vault Agent-rendered files
+if [ -s /vault/secrets/MONGO_ROOT_USER ] && [ -s /vault/secrets/MONGO_ROOT_PASSWORD ]; then
+  export MONGO_INITDB_ROOT_USERNAME="$(cat /vault/secrets/MONGO_ROOT_USER)"
+  export MONGO_INITDB_ROOT_PASSWORD="$(cat /vault/secrets/MONGO_ROOT_PASSWORD)"
+fi
+
+# Execute original MongoDB entrypoint
+exec docker-entrypoint.sh "$@"
--- a/ci/dev/scripts/nats-entrypoint.sh
+++ b/ci/dev/scripts/nats-entrypoint.sh
@@ -0,0 +1,18 @@
+#!/usr/bin/env bash
+# NATS entrypoint wrapper for dev environment
+# Reads credentials from Vault secrets and starts NATS
+set -euo pipefail
+
+# Read NATS credentials from Vault Agent-rendered files
+NATS_USER="$(cat /vault/secrets/NATS_USER)"
+NATS_PASSWORD="$(cat /vault/secrets/NATS_PASSWORD)"
+
+# Start NATS with JetStream
+exec nats-server \
+  --jetstream \
+  --store_dir=/data \
+  --http_port=8222 \
+  --port=4222 \
+  --server_name=dev-nats \
+  --user="${NATS_USER}" \
+  --pass="${NATS_PASSWORD}"
--- a/ci/dev/scripts/vault-setup.sh
+++ b/ci/dev/scripts/vault-setup.sh
@@ -0,0 +1,112 @@
+#!/usr/bin/env bash
+# Vault Setup Script for Development Environment
+# Creates AppRole, policies, and secrets for dev services
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "${SCRIPT_DIR}/../../.." && pwd)"
+
+# Source the vlt helper
+VLT="${REPO_ROOT}/ci/vlt"
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m' # No Color
+
+log() { echo -e "${GREEN}[vault-setup]${NC} $*"; }
+warn() { echo -e "${YELLOW}[vault-setup]${NC} $*"; }
+error() { echo -e "${RED}[vault-setup]${NC} $*" >&2; }
+
+# Check prerequisites
+if [ ! -f "$VLT" ]; then
+  error "Vault helper not found at $VLT"
+  exit 1
+fi
+
+if [ -z "${VAULT_ADDR:-}" ]; then
+  error "VAULT_ADDR is not set"
+  error "Please ensure Vault is running: cd infra/vault && docker compose up -d"
+  exit 1
+fi
+
+log "Checking Vault connection..."
+if ! curl -sf "${VAULT_ADDR}/v1/sys/health" > /dev/null; then
+  error "Cannot connect to Vault at ${VAULT_ADDR}"
+  error "Please ensure Vault is running: cd infra/vault && docker compose up -d"
+  exit 1
+fi
+
+log "✓ Vault is reachable at ${VAULT_ADDR}"
+
+# You need to be authenticated to Vault to run this script
+# Either set VAULT_TOKEN or VAULT_ROLE_ID + VAULT_SECRET_ID
+if [ -z "${VAULT_TOKEN:-}" ]; then
+  warn "VAULT_TOKEN not set. Attempting AppRole login..."
+  if [ -z "${VAULT_ROLE_ID:-}" ] || [ -z "${VAULT_SECRET_ID:-}" ]; then
+    error "Neither VAULT_TOKEN nor VAULT_ROLE_ID/VAULT_SECRET_ID are set"
+    error "Please authenticate to Vault first:"
+    error "  export VAULT_TOKEN=<your-vault-token>"
+    error "Or use AppRole:"
+    error "  export VAULT_ROLE_ID=<role-id>"
+    error "  export VAULT_SECRET_ID=<secret-id>"
+    exit 1
+  fi
+  "${VLT}" login
+  VAULT_TOKEN="$(cat .vault_token)"
+  export VAULT_TOKEN
+fi
+
+log "Creating dev environment policy..."
+cat <<'EOF' | curl -sf -X PUT -H "X-Vault-Token: ${VAULT_TOKEN}" \
+  --data-binary @- "${VAULT_ADDR}/v1/sys/policy/dev-services" > /dev/null
+{
+  "policy": "path \"kv/data/sendico/dev\" { capabilities = [\"read\"] }"
+}
+EOF
+
+log "Creating dev-services AppRole..."
+curl -sf -X POST -H "X-Vault-Token: ${VAULT_TOKEN}" \
+  -d '{"policies": ["dev-services"], "bind_secret_id": true, "token_ttl": "24h", "token_max_ttl": "720h"}' \
+  "${VAULT_ADDR}/v1/auth/approle/role/dev-services" > /dev/null
+
+log "Fetching AppRole credentials..."
+ROLE_ID=$(curl -sf -H "X-Vault-Token: ${VAULT_TOKEN}" \
+  "${VAULT_ADDR}/v1/auth/approle/role/dev-services/role-id" | \
+  grep -o '"role_id":"[^"]*' | cut -d'"' -f4)
+
+SECRET_ID=$(curl -sf -X POST -H "X-Vault-Token: ${VAULT_TOKEN}" \
+  "${VAULT_ADDR}/v1/auth/approle/role/dev-services/secret-id" | \
+  grep -o '"secret_id":"[^"]*' | cut -d'"' -f4)
+
+log "Creating/updating dev secrets in Vault..."
+
+# Generate random credentials if they don't exist
+MONGO_USER="sendico_dev"
+MONGO_PASSWORD="$(openssl rand -base64 32 | tr -d '/+=' | cut -c1-24)"
+MONGO_KEYFILE="$(openssl rand -base64 756 | tr -d '\n')"
+NATS_USER="sendico_dev"
+NATS_PASSWORD="$(openssl rand -base64 32 | tr -d '/+=' | cut -c1-24)"
+
+curl -sf -X POST -H "X-Vault-Token: ${VAULT_TOKEN}" \
+  -d "{
+    \"data\": {
+      \"mongo_user\": \"${MONGO_USER}\",
+      \"mongo_password\": \"${MONGO_PASSWORD}\",
+      \"mongo_keyfile\": \"${MONGO_KEYFILE}\",
+      \"nats_user\": \"${NATS_USER}\",
+      \"nats_password\": \"${NATS_PASSWORD}\"
+    }
+  }" \
+  "${VAULT_ADDR}/v1/kv/data/sendico/dev" > /dev/null
+
+log "✅ Vault setup complete!"
+echo ""
+log "AppRole Credentials (add these to .env.dev):"
+echo ""
+echo "VAULT_ROLE_ID=${ROLE_ID}"
+echo "VAULT_SECRET_ID=${SECRET_ID}"
+echo ""
+warn "IMPORTANT: Save these credentials in .env.dev"
+warn "They will be needed to start the dev environment"
--- a/ci/dev/tgsettle-gateway.dockerfile
+++ b/ci/dev/tgsettle-gateway.dockerfile
@@ -0,0 +1,34 @@
+# Development Dockerfile for tgsettle-gateway Service with Air hot reload
+
+FROM golang:alpine AS builder
+
+RUN apk add --no-cache bash git build-base protoc protobuf-dev && \
+    go install google.golang.org/protobuf/cmd/protoc-gen-go@latest && \
+    go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest && \
+    go install github.com/air-verse/air@latest
+
+WORKDIR /src
+
+COPY api/proto ./api/proto
+COPY api/pkg ./api/pkg
+COPY ci/scripts/proto/generate.sh ./ci/scripts/proto/
+RUN bash ci/scripts/proto/generate.sh
+
+# Runtime stage for development with Air
+FROM golang:alpine
+
+RUN apk add --no-cache bash git build-base && \
+    go install github.com/air-verse/air@latest
+
+WORKDIR /src
+
+# Copy generated proto and pkg from builder
+COPY --from=builder /src/api/proto ./api/proto
+COPY --from=builder /src/api/pkg ./api/pkg
+
+# Source code will be mounted at runtime
+WORKDIR /src/api/gateway/tgsettle
+
+EXPOSE 50080 9406
+
+CMD ["air", "-c", ".air.toml", "--", "-config.file", "/app/config.yml", "-debug"]
--- a/ci/dev/tron-gateway.dockerfile
+++ b/ci/dev/tron-gateway.dockerfile
@@ -0,0 +1,40 @@
+# Development Dockerfile for tron-gateway Service with Air hot reload
+
+FROM golang:alpine AS builder
+
+RUN apk add --no-cache bash git build-base protoc protobuf-dev && \
+    go install google.golang.org/protobuf/cmd/protoc-gen-go@latest && \
+    go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest && \
+    go install github.com/air-verse/air@latest
+
+WORKDIR /src
+
+COPY api/proto ./api/proto
+COPY api/pkg ./api/pkg
+COPY ci/scripts/proto/generate.sh ./ci/scripts/proto/
+RUN bash ci/scripts/proto/generate.sh
+
+# Runtime stage for development with Air
+FROM golang:alpine
+
+RUN apk add --no-cache bash git build-base && \
+    go install github.com/air-verse/air@latest
+
+WORKDIR /src
+
+# Copy generated proto and pkg from builder
+COPY --from=builder /src/api/proto ./api/proto
+COPY --from=builder /src/api/pkg ./api/pkg
+
+# Copy dev-specific entrypoint script
+COPY ci/dev/entrypoints/tron-gateway.sh /app/entrypoint.sh
+RUN chmod +x /app/entrypoint.sh
+
+# Source code will be mounted at runtime
+WORKDIR /src/api/gateway/tron
+
+EXPOSE 50071 9407
+
+# Use entrypoint wrapper to load vault token
+ENTRYPOINT ["/app/entrypoint.sh"]
+CMD ["air", "-c", ".air.toml", "--", "-config.file", "/app/config.yml", "-debug"]
--- a/ci/dev/vault-agent/chain-gateway.hcl
+++ b/ci/dev/vault-agent/chain-gateway.hcl
@@ -0,0 +1,20 @@
+vault {
+  address = "http://dev-vault:8200"
+}
+
+auto_auth {
+  method "approle" {
+    mount_path = "auth/approle"
+    config = {
+      role_id_file_path    = "/run/vault/role_id"
+      secret_id_file_path  = "/run/vault/secret_id"
+    }
+  }
+
+  sink "file" {
+    config = {
+      path = "/run/vault/token"
+      mode = 0600
+    }
+  }
+}
--- a/ci/dev/vault-agent/tron-gateway.hcl
+++ b/ci/dev/vault-agent/tron-gateway.hcl
@@ -0,0 +1,20 @@
+vault {
+  address = "http://dev-vault:8200"
+}
+
+auto_auth {
+  method "approle" {
+    mount_path = "auth/approle"
+    config = {
+      role_id_file_path    = "/run/vault/role_id"
+      secret_id_file_path  = "/run/vault/secret_id"
+    }
+  }
+
+  sink "file" {
+    config = {
+      path = "/run/vault/token"
+      mode = 0600
+    }
+  }
+}
--- a/ci/dev/vault/agent.hcl
+++ b/ci/dev/vault/agent.hcl
@@ -0,0 +1,49 @@
+# Vault Agent for Development Environment
+# AppRole credentials are injected as files from environment variables
+pid_file = "/tmp/vault-agent.pid"
+
+auto_auth {
+  method "approle" {
+    mount_path = "auth/approle"
+    config = {
+      role_id_file_path   = "/vault/secrets/role_id"
+      secret_id_file_path = "/vault/secrets/secret_id"
+    }
+  }
+  sink "file" {
+    config = { path = "/vault/token" }
+  }
+}
+
+vault {
+  address = "{{ env `VAULT_ADDR` }}"
+}
+
+# MongoDB root credentials
+template {
+  source      = "/etc/vault/templates/mongo/user.ctmpl"
+  destination = "/vault/secrets/MONGO_ROOT_USER"
+}
+
+template {
+  source      = "/etc/vault/templates/mongo/pass.ctmpl"
+  destination = "/vault/secrets/MONGO_ROOT_PASSWORD"
+}
+
+# MongoDB replica set keyFile (strict perms for MongoDB)
+template {
+  source      = "/etc/vault/templates/mongo/keyfile.ctmpl"
+  destination = "/vault/secrets/mongo.kf"
+  command     = "sh -lc 'chmod 0400 /vault/secrets/mongo.kf'"
+}
+
+# NATS credentials
+template {
+  source      = "/etc/vault/templates/nats/user.ctmpl"
+  destination = "/vault/secrets/NATS_USER"
+}
+
+template {
+  source      = "/etc/vault/templates/nats/pass.ctmpl"
+  destination = "/vault/secrets/NATS_PASSWORD"
+}
--- a/ci/dev/vault/config.hcl
+++ b/ci/dev/vault/config.hcl
@@ -0,0 +1,17 @@
+# Vault Configuration for Development
+# Single node, file storage backend
+
+storage "file" {
+  path = "/vault/file"
+}
+
+listener "tcp" {
+  address     = "0.0.0.0:8200"
+  tls_disable = true
+}
+
+api_addr = "http://0.0.0.0:8200"
+ui = true
+
+# Disable mlock for dev (no need for memory protection)
+disable_mlock = true
--- a/ci/dev/vault/templates/mongo/keyfile.ctmpl
+++ b/ci/dev/vault/templates/mongo/keyfile.ctmpl
@@ -0,0 +1,3 @@
+{{ with secret "kv/data/sendico/dev" -}}
+{{ .Data.data.mongo_keyfile }}
+{{- end }}
--- a/ci/dev/vault/templates/mongo/pass.ctmpl
+++ b/ci/dev/vault/templates/mongo/pass.ctmpl
@@ -0,0 +1,3 @@
+{{ with secret "kv/data/sendico/dev" -}}
+{{ .Data.data.mongo_password }}
+{{- end }}
--- a/ci/dev/vault/templates/mongo/user.ctmpl
+++ b/ci/dev/vault/templates/mongo/user.ctmpl
@@ -0,0 +1,3 @@
+{{ with secret "kv/data/sendico/dev" -}}
+{{ .Data.data.mongo_user }}
+{{- end }}
--- a/ci/dev/vault/templates/nats/pass.ctmpl
+++ b/ci/dev/vault/templates/nats/pass.ctmpl
@@ -0,0 +1,3 @@
+{{ with secret "kv/data/sendico/dev" -}}
+{{ .Data.data.nats_password }}
+{{- end }}
--- a/ci/dev/vault/templates/nats/user.ctmpl
+++ b/ci/dev/vault/templates/nats/user.ctmpl
@@ -0,0 +1,3 @@
+{{ with secret "kv/data/sendico/dev" -}}
+{{ .Data.data.nats_user }}
+{{- end }}
--- a/ci/prod/.env.runtime
+++ b/ci/prod/.env.runtime
@@ -90,6 +90,13 @@ FEES_SERVICE_NAME=sendico_billing_fees
 FEES_GRPC_PORT=50060
 FEES_METRICS_PORT=9402

+# Billing documents stack
+DOCUMENTS_DIR=billing_documents
+DOCUMENTS_COMPOSE_PROJECT=sendico-billing-documents
+DOCUMENTS_SERVICE_NAME=sendico_billing_documents
+DOCUMENTS_GRPC_PORT=50061
+DOCUMENTS_METRICS_PORT=9409
+
 # Billing fees Mongo settings
 FEES_MONGO_HOST=sendico_db1
 FEES_MONGO_PORT=27017
--- a/ci/prod/compose/billing_documents.dockerfile
+++ b/ci/prod/compose/billing_documents.dockerfile
@@ -0,0 +1,40 @@
+# syntax=docker/dockerfile:1.7
+
+ARG TARGETOS=linux
+ARG TARGETARCH=amd64
+
+FROM golang:alpine AS build
+ARG APP_VERSION=dev
+ARG GIT_REV=unknown
+ARG BUILD_BRANCH=unknown
+ARG BUILD_DATE=unknown
+ARG BUILD_USER=ci
+ENV GO111MODULE=on
+ENV PATH="/go/bin:${PATH}"
+WORKDIR /src
+COPY . .
+RUN apk add --no-cache bash git build-base protoc protobuf-dev \
+ && go install google.golang.org/protobuf/cmd/protoc-gen-go@latest \
+ && go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest \
+ && bash ci/scripts/proto/generate.sh
+WORKDIR /src/api/billing/documents
+RUN --mount=type=cache,target=/root/.cache/go-build \
+    --mount=type=cache,target=/go/pkg/mod \
+    CGO_ENABLED=0 GOOS=${TARGETOS} GOARCH=${TARGETARCH} \
+    go build -trimpath -ldflags "\
+      -s -w \
+      -X github.com/tech/sendico/billing/documents/internal/appversion.Version=${APP_VERSION} \
+      -X github.com/tech/sendico/billing/documents/internal/appversion.Revision=${GIT_REV} \
+      -X github.com/tech/sendico/billing/documents/internal/appversion.Branch=${BUILD_BRANCH} \
+      -X github.com/tech/sendico/billing/documents/internal/appversion.BuildUser=${BUILD_USER} \
+      -X github.com/tech/sendico/billing/documents/internal/appversion.BuildDate=${BUILD_DATE}" \
+    -o /out/billing-documents .
+
+FROM alpine:latest AS runtime
+RUN apk add --no-cache ca-certificates tzdata wget
+WORKDIR /app
+COPY api/billing/documents/config.yml /app/config.yml
+COPY --from=build /out/billing-documents /app/billing-documents
+EXPOSE 50061 9409
+ENTRYPOINT ["/app/billing-documents"]
+CMD ["--config.file", "/app/config.yml"]
--- a/ci/prod/compose/billing_documents.yml
+++ b/ci/prod/compose/billing_documents.yml
@@ -0,0 +1,39 @@
+# Compose v2 - Billing documents
+
+x-common-env: &common-env
+  env_file:
+    - ../env/.env.runtime
+    - ../env/.env.version
+
+networks:
+  sendico-net:
+    external: true
+    name: sendico-net
+
+services:
+  sendico_billing_documents:
+    <<: *common-env
+    container_name: sendico-billing-documents
+    restart: unless-stopped
+    image: ${REGISTRY_URL}/billing/documents:${APP_V}
+    pull_policy: always
+    environment:
+      DOCUMENTS_GRPC_PORT: ${DOCUMENTS_GRPC_PORT}
+      DOCUMENTS_METRICS_PORT: ${DOCUMENTS_METRICS_PORT}
+      NATS_URL: ${NATS_URL}
+      NATS_HOST: ${NATS_HOST}
+      NATS_PORT: ${NATS_PORT}
+      NATS_USER: ${NATS_USER}
+      NATS_PASSWORD: ${NATS_PASSWORD}
+    command: ["--config.file", "/app/config.yml"]
+    ports:
+      - "0.0.0.0:${DOCUMENTS_GRPC_PORT}:50061"
+      - "0.0.0.0:${DOCUMENTS_METRICS_PORT}:${DOCUMENTS_METRICS_PORT}"
+    healthcheck:
+      test: ["CMD-SHELL","wget -qO- http://localhost:${DOCUMENTS_METRICS_PORT}/health | grep -q '\"status\":\"ok\"'"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 60s
+    networks:
+      - sendico-net
--- a/ci/prod/compose/tron_gateway.dockerfile
+++ b/ci/prod/compose/tron_gateway.dockerfile
@@ -0,0 +1,43 @@
+# syntax=docker/dockerfile:1.7
+
+ARG TARGETOS=linux
+ARG TARGETARCH=amd64
+
+FROM golang:alpine AS build
+ARG APP_VERSION=dev
+ARG GIT_REV=unknown
+ARG BUILD_BRANCH=unknown
+ARG BUILD_DATE=unknown
+ARG BUILD_USER=ci
+ENV GO111MODULE=on
+ENV PATH="/go/bin:${PATH}"
+WORKDIR /src
+COPY . .
+RUN apk add --no-cache bash git build-base protoc protobuf-dev \
+ && go install google.golang.org/protobuf/cmd/protoc-gen-go@latest \
+ && go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest \
+ && bash ci/scripts/proto/generate.sh
+WORKDIR /src/api/gateway/tron
+RUN --mount=type=cache,target=/root/.cache/go-build \
+    --mount=type=cache,target=/go/pkg/mod \
+    CGO_ENABLED=0 GOOS=${TARGETOS} GOARCH=${TARGETARCH} \
+    go build -trimpath -ldflags "\
+      -s -w \
+      -X github.com/tech/sendico/gateway/tron/internal/appversion.Version=${APP_VERSION} \
+      -X github.com/tech/sendico/gateway/tron/internal/appversion.Revision=${GIT_REV} \
+      -X github.com/tech/sendico/gateway/tron/internal/appversion.Branch=${BUILD_BRANCH} \
+      -X github.com/tech/sendico/gateway/tron/internal/appversion.BuildUser=${BUILD_USER} \
+      -X github.com/tech/sendico/gateway/tron/internal/appversion.BuildDate=${BUILD_DATE}" \
+    -o /out/tron-gateway .
+
+FROM alpine:latest AS runtime
+RUN apk add --no-cache ca-certificates tzdata wget
+WORKDIR /app
+COPY api/gateway/tron/config.yml /app/config.yml
+COPY api/gateway/tron/env /app/env
+COPY api/gateway/tron/entrypoint.sh /app/entrypoint.sh
+COPY --from=build /out/tron-gateway /app/tron-gateway
+RUN chmod +x /app/entrypoint.sh
+EXPOSE 50071 9407
+ENTRYPOINT ["/app/entrypoint.sh"]
+CMD ["/app/tron-gateway","--config.file","/app/config.yml"]
--- a/ci/prod/compose/vault-agent/tron-gateway.hcl
+++ b/ci/prod/compose/vault-agent/tron-gateway.hcl
@@ -0,0 +1,20 @@
+vault {
+  address = "https://vault.sendico.io"
+}
+
+auto_auth {
+  method "approle" {
+    mount_path = "auth/approle"
+    config = {
+      role_id_file_path    = "/run/vault/role_id"
+      secret_id_file_path  = "/run/vault/secret_id"
+    }
+  }
+
+  sink "file" {
+    config = {
+      path = "/run/vault/token"
+      mode = 0600
+    }
+  }
+}
--- a/ci/prod/scripts/deploy/billing_documents.sh
+++ b/ci/prod/scripts/deploy/billing_documents.sh
@@ -0,0 +1,139 @@
+#!/usr/bin/env bash
+set -euo pipefail
+[[ "${DEBUG_DEPLOY:-0}" = "1" ]] && set -x
+trap 'echo "[deploy-billing-documents] error at line $LINENO" >&2' ERR
+
+: "${REMOTE_BASE:?missing REMOTE_BASE}"
+: "${SSH_USER:?missing SSH_USER}"
+: "${SSH_HOST:?missing SSH_HOST}"
+: "${DOCUMENTS_DIR:?missing DOCUMENTS_DIR}"
+: "${DOCUMENTS_COMPOSE_PROJECT:?missing DOCUMENTS_COMPOSE_PROJECT}"
+: "${DOCUMENTS_SERVICE_NAME:?missing DOCUMENTS_SERVICE_NAME}"
+
+REMOTE_DIR="${REMOTE_BASE%/}/${DOCUMENTS_DIR}"
+REMOTE_TARGET="${SSH_USER}@${SSH_HOST}"
+COMPOSE_FILE="billing_documents.yml"
+SERVICE_NAMES="${DOCUMENTS_SERVICE_NAME}"
+
+REQUIRED_SECRETS=(
+  NATS_USER
+  NATS_PASSWORD
+  NATS_URL
+)
+
+for var in "${REQUIRED_SECRETS[@]}"; do
+  if [[ -z "${!var:-}" ]]; then
+    echo "missing required secret env: ${var}" >&2
+    exit 65
+  fi
+done
+
+if [[ ! -s .env.version ]]; then
+  echo ".env.version is missing; run version step first" >&2
+  exit 66
+fi
+
+b64enc() {
+  printf '%s' "$1" | base64 | tr -d '\n'
+}
+
+NATS_USER_B64="$(b64enc "${NATS_USER}")"
+NATS_PASSWORD_B64="$(b64enc "${NATS_PASSWORD}")"
+NATS_URL_B64="$(b64enc "${NATS_URL}")"
+
+SSH_OPTS=(
+  -i /root/.ssh/id_rsa
+  -o StrictHostKeyChecking=no
+  -o UserKnownHostsFile=/dev/null
+  -o LogLevel=ERROR
+  -q
+)
+if [[ "${DEBUG_DEPLOY:-0}" = "1" ]]; then
+  SSH_OPTS=("${SSH_OPTS[@]/-q/}" -vv)
+fi
+
+RSYNC_FLAGS=(-az --delete)
+[[ "${DEBUG_DEPLOY:-0}" = "1" ]] && RSYNC_FLAGS=(-avz --delete)
+
+ssh "${SSH_OPTS[@]}" "$REMOTE_TARGET" "mkdir -p ${REMOTE_DIR}/{compose,env}"
+
+rsync "${RSYNC_FLAGS[@]}" -e "ssh ${SSH_OPTS[*]}" ci/prod/compose/ "$REMOTE_TARGET:${REMOTE_DIR}/compose/"
+rsync "${RSYNC_FLAGS[@]}" -e "ssh ${SSH_OPTS[*]}" ci/prod/.env.runtime "$REMOTE_TARGET:${REMOTE_DIR}/env/.env.runtime"
+rsync "${RSYNC_FLAGS[@]}" -e "ssh ${SSH_OPTS[*]}" .env.version         "$REMOTE_TARGET:${REMOTE_DIR}/env/.env.version"
+
+SERVICES_LINE="${SERVICE_NAMES}"
+
+ssh "${SSH_OPTS[@]}" "$REMOTE_TARGET" \
+  REMOTE_DIR="$REMOTE_DIR" \
+  COMPOSE_FILE="$COMPOSE_FILE" \
+  COMPOSE_PROJECT="$DOCUMENTS_COMPOSE_PROJECT" \
+  SERVICES_LINE="$SERVICES_LINE" \
+  NATS_USER_B64="$NATS_USER_B64" \
+  NATS_PASSWORD_B64="$NATS_PASSWORD_B64" \
+  NATS_URL_B64="$NATS_URL_B64" \
+  bash -s <<'EOSSH'
+set -euo pipefail
+cd "${REMOTE_DIR}/compose"
+set -a
+. ../env/.env.runtime
+load_kv_file() {
+  local file="$1"
+  while IFS= read -r line || [ -n "$line" ]; do
+    case "$line" in
+      ''|\#*) continue ;;
+    esac
+    if printf '%s' "$line" | grep -Eq '^[[:alpha:]_][[:alnum:]_]*='; then
+      local key="${line%%=*}"
+      local value="${line#*=}"
+      key="$(printf '%s' "$key" | tr -d '[:space:]')"
+      value="${value#"${value%%[![:space:]]*}"}"
+      value="${value%"${value##*[![:space:]]}"}"
+      if [[ -n "$key" ]]; then
+        export "$key=$value"
+      fi
+    fi
+  done <"$file"
+}
+load_kv_file ../env/.env.version
+set +a
+
+if base64 -d >/dev/null 2>&1 <<<'AA=='; then
+  BASE64_DECODE_FLAG='-d'
+else
+  BASE64_DECODE_FLAG='--decode'
+fi
+
+decode_b64() {
+  val="$1"
+  if [[ -z "$val" ]]; then
+    printf ''
+    return
+  fi
+  printf '%s' "$val" | base64 "${BASE64_DECODE_FLAG}"
+}
+
+NATS_USER="$(decode_b64 "$NATS_USER_B64")"
+NATS_PASSWORD="$(decode_b64 "$NATS_PASSWORD_B64")"
+NATS_URL="$(decode_b64 "$NATS_URL_B64")"
+
+export NATS_USER NATS_PASSWORD NATS_URL
+COMPOSE_PROJECT_NAME="$COMPOSE_PROJECT"
+export COMPOSE_PROJECT_NAME
+read -r -a SERVICES <<<"${SERVICES_LINE}"
+
+pull_cmd=(docker compose -f "$COMPOSE_FILE" pull)
+up_cmd=(docker compose -f "$COMPOSE_FILE" up -d --remove-orphans)
+ps_cmd=(docker compose -f "$COMPOSE_FILE" ps)
+if [[ "${#SERVICES[@]}" -gt 0 ]]; then
+  pull_cmd+=("${SERVICES[@]}")
+  up_cmd+=("${SERVICES[@]}")
+  ps_cmd+=("${SERVICES[@]}")
+fi
+
+"${pull_cmd[@]}"
+"${up_cmd[@]}"
+"${ps_cmd[@]}"
+
+date -Is > .last_deploy
+logger -t "deploy-${COMPOSE_PROJECT_NAME}" "${COMPOSE_PROJECT_NAME} deployed at $(date -Is) in ${REMOTE_DIR}"
+EOSSH
--- a/ci/prod/scripts/deploy/tron_gateway.sh
+++ b/ci/prod/scripts/deploy/tron_gateway.sh
@@ -0,0 +1,175 @@
+#!/usr/bin/env bash
+set -euo pipefail
+[[ "${DEBUG_DEPLOY:-0}" = "1" ]] && set -x
+trap 'echo "[deploy-tron-gateway] error at line $LINENO" >&2' ERR
+
+: "${REMOTE_BASE:?missing REMOTE_BASE}"
+: "${SSH_USER:?missing SSH_USER}"
+: "${SSH_HOST:?missing SSH_HOST}"
+: "${TRON_GATEWAY_DIR:?missing TRON_GATEWAY_DIR}"
+: "${TRON_GATEWAY_COMPOSE_PROJECT:?missing TRON_GATEWAY_COMPOSE_PROJECT}"
+: "${TRON_GATEWAY_SERVICE_NAME:?missing TRON_GATEWAY_SERVICE_NAME}"
+
+REMOTE_DIR="${REMOTE_BASE%/}/${TRON_GATEWAY_DIR}"
+REMOTE_TARGET="${SSH_USER}@${SSH_HOST}"
+COMPOSE_FILE="tron_gateway.yml"
+SERVICE_NAMES="${TRON_GATEWAY_SERVICE_NAME}"
+
+REQUIRED_SECRETS=(
+  TRON_GATEWAY_MONGO_USER
+  TRON_GATEWAY_MONGO_PASSWORD
+  TRON_GATEWAY_RPC_URL
+  TRON_GATEWAY_SERVICE_WALLET_KEY
+  TRON_GATEWAY_SERVICE_WALLET_ADDRESS
+  TRON_GATEWAY_VAULT_ROLE_ID
+  TRON_GATEWAY_VAULT_SECRET_ID
+  NATS_USER
+  NATS_PASSWORD
+  NATS_URL
+)
+
+for var in "${REQUIRED_SECRETS[@]}"; do
+  if [[ -z "${!var:-}" ]]; then
+    echo "missing required secret env: ${var}" >&2
+    exit 65
+  fi
+done
+
+if [[ ! -s .env.version ]]; then
+  echo ".env.version is missing; run version step first" >&2
+  exit 66
+fi
+
+b64enc() {
+  printf '%s' "$1" | base64 | tr -d '\n'
+}
+
+TRON_GATEWAY_MONGO_USER_B64="$(b64enc "${TRON_GATEWAY_MONGO_USER}")"
+TRON_GATEWAY_MONGO_PASSWORD_B64="$(b64enc "${TRON_GATEWAY_MONGO_PASSWORD}")"
+TRON_GATEWAY_RPC_URL_B64="$(b64enc "${TRON_GATEWAY_RPC_URL}")"
+TRON_GATEWAY_GRPC_URL_B64="$(b64enc "${TRON_GATEWAY_GRPC_URL:-}")"
+TRON_GATEWAY_SERVICE_WALLET_KEY_B64="$(b64enc "${TRON_GATEWAY_SERVICE_WALLET_KEY}")"
+TRON_GATEWAY_SERVICE_WALLET_ADDRESS_B64="$(b64enc "${TRON_GATEWAY_SERVICE_WALLET_ADDRESS}")"
+TRON_GATEWAY_VAULT_ROLE_ID_B64="$(b64enc "${TRON_GATEWAY_VAULT_ROLE_ID}")"
+TRON_GATEWAY_VAULT_SECRET_ID_B64="$(b64enc "${TRON_GATEWAY_VAULT_SECRET_ID}")"
+NATS_USER_B64="$(b64enc "${NATS_USER}")"
+NATS_PASSWORD_B64="$(b64enc "${NATS_PASSWORD}")"
+NATS_URL_B64="$(b64enc "${NATS_URL}")"
+
+SSH_OPTS=(
+  -i /root/.ssh/id_rsa
+  -o StrictHostKeyChecking=no
+  -o UserKnownHostsFile=/dev/null
+  -o LogLevel=ERROR
+  -q
+)
+if [[ "${DEBUG_DEPLOY:-0}" = "1" ]]; then
+  SSH_OPTS=("${SSH_OPTS[@]/-q/}" -vv)
+fi
+
+RSYNC_FLAGS=(-az --delete)
+[[ "${DEBUG_DEPLOY:-0}" = "1" ]] && RSYNC_FLAGS=(-avz --delete)
+
+ssh "${SSH_OPTS[@]}" "$REMOTE_TARGET" "mkdir -p ${REMOTE_DIR}/compose/secrets ${REMOTE_DIR}/env"
+
+rsync "${RSYNC_FLAGS[@]}" -e "ssh ${SSH_OPTS[*]}" ci/prod/compose/ "$REMOTE_TARGET:${REMOTE_DIR}/compose/"
+rsync "${RSYNC_FLAGS[@]}" -e "ssh ${SSH_OPTS[*]}" ci/prod/.env.runtime "$REMOTE_TARGET:${REMOTE_DIR}/env/.env.runtime"
+rsync "${RSYNC_FLAGS[@]}" -e "ssh ${SSH_OPTS[*]}" .env.version         "$REMOTE_TARGET:${REMOTE_DIR}/env/.env.version"
+
+SERVICES_LINE="${SERVICE_NAMES}"
+
+ssh "${SSH_OPTS[@]}" "$REMOTE_TARGET" \
+  REMOTE_DIR="$REMOTE_DIR" \
+  COMPOSE_FILE="$COMPOSE_FILE" \
+  COMPOSE_PROJECT="$TRON_GATEWAY_COMPOSE_PROJECT" \
+  SERVICES_LINE="$SERVICES_LINE" \
+  TRON_GATEWAY_MONGO_USER_B64="$TRON_GATEWAY_MONGO_USER_B64" \
+  TRON_GATEWAY_MONGO_PASSWORD_B64="$TRON_GATEWAY_MONGO_PASSWORD_B64" \
+  TRON_GATEWAY_RPC_URL_B64="$TRON_GATEWAY_RPC_URL_B64" \
+  TRON_GATEWAY_GRPC_URL_B64="$TRON_GATEWAY_GRPC_URL_B64" \
+  TRON_GATEWAY_SERVICE_WALLET_KEY_B64="$TRON_GATEWAY_SERVICE_WALLET_KEY_B64" \
+  TRON_GATEWAY_SERVICE_WALLET_ADDRESS_B64="$TRON_GATEWAY_SERVICE_WALLET_ADDRESS_B64" \
+  TRON_GATEWAY_VAULT_ROLE_ID_B64="$TRON_GATEWAY_VAULT_ROLE_ID_B64" \
+  TRON_GATEWAY_VAULT_SECRET_ID_B64="$TRON_GATEWAY_VAULT_SECRET_ID_B64" \
+  NATS_USER_B64="$NATS_USER_B64" \
+  NATS_PASSWORD_B64="$NATS_PASSWORD_B64" \
+  NATS_URL_B64="$NATS_URL_B64" \
+  bash -s <<'EOSSH'
+set -euo pipefail
+cd "${REMOTE_DIR}/compose"
+set -a
+. ../env/.env.runtime
+load_kv_file() {
+  local file="$1"
+  while IFS= read -r line || [ -n "$line" ]; do
+    case "$line" in
+      ''|\#*) continue ;;
+    esac
+    if printf '%s' "$line" | grep -Eq '^[[:alpha:]_][[:alnum:]_]*='; then
+      local key="${line%%=*}"
+      local value="${line#*=}"
+      key="$(printf '%s' "$key" | tr -d '[:space:]')"
+      value="${value#"${value%%[![:space:]]*}"}"
+      value="${value%"${value##*[![:space:]]}"}"
+      if [[ -n "$key" ]]; then
+        export "$key=$value"
+      fi
+    fi
+  done <"$file"
+}
+load_kv_file ../env/.env.version
+set +a
+
+if base64 -d >/dev/null 2>&1 <<<'AA=='; then
+  BASE64_DECODE_FLAG='-d'
+else
+  BASE64_DECODE_FLAG='--decode'
+fi
+
+decode_b64() {
+  val="$1"
+  if [[ -z "$val" ]]; then
+    printf ''
+    return
+  fi
+  printf '%s' "$val" | base64 "${BASE64_DECODE_FLAG}"
+}
+
+TRON_GATEWAY_MONGO_USER="$(decode_b64 "$TRON_GATEWAY_MONGO_USER_B64")"
+TRON_GATEWAY_MONGO_PASSWORD="$(decode_b64 "$TRON_GATEWAY_MONGO_PASSWORD_B64")"
+TRON_GATEWAY_RPC_URL="$(decode_b64 "$TRON_GATEWAY_RPC_URL_B64")"
+TRON_GATEWAY_GRPC_URL="$(decode_b64 "$TRON_GATEWAY_GRPC_URL_B64")"
+TRON_GATEWAY_SERVICE_WALLET_KEY="$(decode_b64 "$TRON_GATEWAY_SERVICE_WALLET_KEY_B64")"
+TRON_GATEWAY_SERVICE_WALLET_ADDRESS="$(decode_b64 "$TRON_GATEWAY_SERVICE_WALLET_ADDRESS_B64")"
+TRON_GATEWAY_VAULT_ROLE_ID="$(decode_b64 "$TRON_GATEWAY_VAULT_ROLE_ID_B64")"
+TRON_GATEWAY_VAULT_SECRET_ID="$(decode_b64 "$TRON_GATEWAY_VAULT_SECRET_ID_B64")"
+NATS_USER="$(decode_b64 "$NATS_USER_B64")"
+NATS_PASSWORD="$(decode_b64 "$NATS_PASSWORD_B64")"
+NATS_URL="$(decode_b64 "$NATS_URL_B64")"
+
+export TRON_GATEWAY_MONGO_USER TRON_GATEWAY_MONGO_PASSWORD
+export TRON_GATEWAY_RPC_URL TRON_GATEWAY_GRPC_URL
+export TRON_GATEWAY_SERVICE_WALLET_KEY TRON_GATEWAY_SERVICE_WALLET_ADDRESS
+export TRON_GATEWAY_VAULT_ROLE_ID TRON_GATEWAY_VAULT_SECRET_ID
+export NATS_USER NATS_PASSWORD NATS_URL
+
+COMPOSE_PROJECT_NAME="$COMPOSE_PROJECT"
+export COMPOSE_PROJECT_NAME
+read -r -a SERVICES <<<"${SERVICES_LINE}"
+
+pull_cmd=(docker compose -f "$COMPOSE_FILE" pull)
+up_cmd=(docker compose -f "$COMPOSE_FILE" up -d --remove-orphans)
+ps_cmd=(docker compose -f "$COMPOSE_FILE" ps)
+if [[ "${#SERVICES[@]}" -gt 0 ]]; then
+  pull_cmd+=("${SERVICES[@]}")
+  up_cmd+=("${SERVICES[@]}")
+  ps_cmd+=("${SERVICES[@]}")
+fi
+
+"${pull_cmd[@]}"
+"${up_cmd[@]}"
+"${ps_cmd[@]}"
+
+date -Is > .last_deploy
+logger -t "deploy-${COMPOSE_PROJECT_NAME}" "${COMPOSE_PROJECT_NAME} deployed at $(date -Is) in ${REMOTE_DIR}"
+EOSSH
--- a/ci/scripts/billing_documents/build-image.sh
+++ b/ci/scripts/billing_documents/build-image.sh
@@ -0,0 +1,85 @@
+#!/bin/sh
+set -eu
+
+if ! set -o pipefail 2>/dev/null; then
+  :
+fi
+
+REPO_ROOT="$(cd "$(dirname "$0")/../../.." && pwd)"
+cd "${REPO_ROOT}"
+
+sh ci/scripts/common/ensure_env_version.sh
+
+normalize_env_file() {
+  file="$1"
+  tmp="${file}.tmp.$$"
+  tr -d '\r' <"$file" >"$tmp"
+  mv "$tmp" "$file"
+}
+
+load_env_file() {
+  file="$1"
+  while IFS= read -r line || [ -n "$line" ]; do
+    case "$line" in
+      ''|\#*) continue ;;
+    esac
+    key="${line%%=*}"
+    value="${line#*=}"
+    key="$(printf '%s' "$key" | tr -d '[:space:]')"
+    value="${value#"${value%%[![:space:]]*}"}"
+    value="${value%"${value##*[![:space:]]}"}"
+    export "$key=$value"
+  done <"$file"
+}
+
+DOCUMENTS_ENV_NAME="${DOCUMENTS_ENV:-prod}"
+RUNTIME_ENV_FILE="./ci/${DOCUMENTS_ENV_NAME}/.env.runtime"
+
+if [ ! -f "${RUNTIME_ENV_FILE}" ]; then
+  echo "[billing-documents-build] runtime env file not found: ${RUNTIME_ENV_FILE}" >&2
+  exit 1
+fi
+
+normalize_env_file "${RUNTIME_ENV_FILE}"
+normalize_env_file ./.env.version
+
+load_env_file "${RUNTIME_ENV_FILE}"
+load_env_file ./.env.version
+
+REGISTRY_URL="${REGISTRY_URL:?missing REGISTRY_URL}"
+APP_V="${APP_V:?missing APP_V}"
+DOCUMENTS_DOCKERFILE="${DOCUMENTS_DOCKERFILE:?missing DOCUMENTS_DOCKERFILE}"
+DOCUMENTS_IMAGE_PATH="${DOCUMENTS_IMAGE_PATH:?missing DOCUMENTS_IMAGE_PATH}"
+
+REGISTRY_HOST="${REGISTRY_URL#http://}"
+REGISTRY_HOST="${REGISTRY_HOST#https://}"
+REGISTRY_USER="$(cat secrets/REGISTRY_USER)"
+REGISTRY_PASSWORD="$(cat secrets/REGISTRY_PASSWORD)"
+: "${REGISTRY_USER:?missing registry user}"
+: "${REGISTRY_PASSWORD:?missing registry password}"
+
+mkdir -p /kaniko/.docker
+AUTH_B64="$(printf '%s:%s' "$REGISTRY_USER" "$REGISTRY_PASSWORD" | base64 | tr -d '\n')"
+cat <<EOF_JSON >/kaniko/.docker/config.json
+{
+  "auths": {
+    "https://${REGISTRY_HOST}": { "auth": "${AUTH_B64}" }
+  }
+}
+EOF_JSON
+
+BUILD_CONTEXT="${DOCUMENTS_BUILD_CONTEXT:-${WOODPECKER_WORKSPACE:-${CI_WORKSPACE:-${PWD:-/workspace}}}}"
+if [ ! -d "${BUILD_CONTEXT}" ]; then
+  BUILD_CONTEXT="/workspace"
+fi
+
+/kaniko/executor \
+  --context "${BUILD_CONTEXT}" \
+  --dockerfile "${DOCUMENTS_DOCKERFILE}" \
+  --destination "${REGISTRY_URL}/${DOCUMENTS_IMAGE_PATH}:${APP_V}" \
+  --build-arg APP_VERSION="${APP_V}" \
+  --build-arg GIT_REV="${GIT_REV}" \
+  --build-arg BUILD_BRANCH="${BUILD_BRANCH}" \
+  --build-arg BUILD_DATE="${BUILD_DATE}" \
+  --build-arg BUILD_USER="${BUILD_USER}" \
+  --single-snapshot
--- a/ci/scripts/billing_documents/deploy.sh
+++ b/ci/scripts/billing_documents/deploy.sh
@@ -0,0 +1,54 @@
+#!/bin/sh
+set -eu
+
+if ! set -o pipefail 2>/dev/null; then
+  :
+fi
+
+REPO_ROOT="$(cd "$(dirname "$0")/../../.." && pwd)"
+cd "${REPO_ROOT}"
+
+sh ci/scripts/common/ensure_env_version.sh
+
+normalize_env_file() {
+  file="$1"
+  tmp="${file}.tmp.$$"
+  tr -d '\r' <"$file" >"$tmp"
+  mv "$tmp" "$file"
+}
+
+load_env_file() {
+  file="$1"
+  while IFS= read -r line || [ -n "$line" ]; do
+    case "$line" in
+      ''|\#*) continue ;;
+    esac
+    key="${line%%=*}"
+    value="${line#*=}"
+    key="$(printf '%s' "$key" | tr -d '[:space:]')"
+    value="${value#"${value%%[![:space:]]*}"}"
+    value="${value%"${value##*[![:space:]]}"}"
+    export "$key=$value"
+  done <"$file"
+}
+
+. ci/scripts/common/nats_env.sh
+
+DOCUMENTS_ENV_NAME="${DOCUMENTS_ENV:-prod}"
+RUNTIME_ENV_FILE="./ci/${DOCUMENTS_ENV_NAME}/.env.runtime"
+
+if [ ! -f "${RUNTIME_ENV_FILE}" ]; then
+  echo "[billing-documents-deploy] runtime env file not found: ${RUNTIME_ENV_FILE}" >&2
+  exit 1
+fi
+
+normalize_env_file "${RUNTIME_ENV_FILE}"
+normalize_env_file ./.env.version
+
+load_env_file "${RUNTIME_ENV_FILE}"
+load_env_file ./.env.version
+
+load_nats_env
+
+bash ci/prod/scripts/bootstrap/network.sh
+bash ci/prod/scripts/deploy/billing_documents.sh
--- a/ci/scripts/proto/generate.sh
+++ b/ci/scripts/proto/generate.sh
@@ -134,4 +134,10 @@ if [ -f "${PROTO_DIR}/billing/fees/v1/fees.proto" ]; then
  generate_go_with_grpc "${PROTO_DIR}/billing/fees/v1/fees.proto"
 fi

+if [ -f "${PROTO_DIR}/billing/documents/v1/documents.proto" ]; then
+  info "Compiling billing documents protos"
+  clean_pb_files "./pkg/proto/billing/documents"
+  generate_go_with_grpc "${PROTO_DIR}/billing/documents/v1/documents.proto"
+fi
+
 info "Protobuf generation completed"
--- a/ci/scripts/tron_gateway/build-image.sh
+++ b/ci/scripts/tron_gateway/build-image.sh
@@ -0,0 +1,85 @@
+#!/bin/sh
+set -eu
+
+if ! set -o pipefail 2>/dev/null; then
+  :
+fi
+
+REPO_ROOT="$(cd "$(dirname "$0")/../../.." && pwd)"
+cd "${REPO_ROOT}"
+
+sh ci/scripts/common/ensure_env_version.sh
+
+normalize_env_file() {
+  file="$1"
+  tmp="${file}.tmp.$$"
+  tr -d '\r' <"$file" >"$tmp"
+  mv "$tmp" "$file"
+}
+
+load_env_file() {
+  file="$1"
+  while IFS= read -r line || [ -n "$line" ]; do
+    case "$line" in
+      ''|\#*) continue ;;
+    esac
+    key="${line%%=*}"
+    value="${line#*=}"
+    key="$(printf '%s' "$key" | tr -d '[:space:]')"
+    value="${value#"${value%%[![:space:]]*}"}"
+    value="${value%"${value##*[![:space:]]}"}"
+    export "$key=$value"
+  done <"$file"
+}
+
+TRON_GATEWAY_ENV_NAME="${TRON_GATEWAY_ENV:-prod}"
+RUNTIME_ENV_FILE="./ci/${TRON_GATEWAY_ENV_NAME}/.env.runtime"
+
+if [ ! -f "${RUNTIME_ENV_FILE}" ]; then
+  echo "[tron-gateway-build] runtime env file not found: ${RUNTIME_ENV_FILE}" >&2
+  exit 1
+fi
+
+normalize_env_file "${RUNTIME_ENV_FILE}"
+normalize_env_file ./.env.version
+
+load_env_file "${RUNTIME_ENV_FILE}"
+load_env_file ./.env.version
+
+REGISTRY_URL="${REGISTRY_URL:?missing REGISTRY_URL}"
+APP_V="${APP_V:?missing APP_V}"
+TRON_GATEWAY_DOCKERFILE="${TRON_GATEWAY_DOCKERFILE:?missing TRON_GATEWAY_DOCKERFILE}"
+TRON_GATEWAY_IMAGE_PATH="${TRON_GATEWAY_IMAGE_PATH:?missing TRON_GATEWAY_IMAGE_PATH}"
+
+REGISTRY_HOST="${REGISTRY_URL#http://}"
+REGISTRY_HOST="${REGISTRY_HOST#https://}"
+REGISTRY_USER="$(cat secrets/REGISTRY_USER)"
+REGISTRY_PASSWORD="$(cat secrets/REGISTRY_PASSWORD)"
+: "${REGISTRY_USER:?missing registry user}"
+: "${REGISTRY_PASSWORD:?missing registry password}"
+
+mkdir -p /kaniko/.docker
+AUTH_B64="$(printf '%s:%s' "$REGISTRY_USER" "$REGISTRY_PASSWORD" | base64 | tr -d '\n')"
+cat <<EOF >/kaniko/.docker/config.json
+{
+  "auths": {
+    "https://${REGISTRY_HOST}": { "auth": "${AUTH_B64}" }
+  }
+}
+EOF
+
+BUILD_CONTEXT="${TRON_GATEWAY_BUILD_CONTEXT:-${WOODPECKER_WORKSPACE:-${CI_WORKSPACE:-${PWD:-/workspace}}}}"
+if [ ! -d "${BUILD_CONTEXT}" ]; then
+  BUILD_CONTEXT="/workspace"
+fi
+
+/kaniko/executor \
+  --context "${BUILD_CONTEXT}" \
+  --dockerfile "${TRON_GATEWAY_DOCKERFILE}" \
+  --destination "${REGISTRY_URL}/${TRON_GATEWAY_IMAGE_PATH}:${APP_V}" \
+  --build-arg APP_VERSION="${APP_V}" \
+  --build-arg GIT_REV="${GIT_REV}" \
+  --build-arg BUILD_BRANCH="${BUILD_BRANCH}" \
+  --build-arg BUILD_DATE="${BUILD_DATE}" \
+  --build-arg BUILD_USER="${BUILD_USER}" \
+  --single-snapshot
--- a/ci/scripts/tron_gateway/deploy.sh
+++ b/ci/scripts/tron_gateway/deploy.sh
@@ -0,0 +1,75 @@
+#!/bin/sh
+set -eu
+
+if ! set -o pipefail 2>/dev/null; then
+  :
+fi
+
+REPO_ROOT="$(cd "$(dirname "$0")/../../.." && pwd)"
+cd "${REPO_ROOT}"
+
+sh ci/scripts/common/ensure_env_version.sh
+
+normalize_env_file() {
+  file="$1"
+  tmp="${file}.tmp.$$"
+  tr -d '\r' <"$file" >"$tmp"
+  mv "$tmp" "$file"
+}
+
+load_env_file() {
+  file="$1"
+  while IFS= read -r line || [ -n "$line" ]; do
+    case "$line" in
+      ''|\#*) continue ;;
+    esac
+    key="${line%%=*}"
+    value="${line#*=}"
+    key="$(printf '%s' "$key" | tr -d '[:space:]')"
+    value="${value#"${value%%[![:space:]]*}"}"
+    value="${value%"${value##*[![:space:]]}"}"
+    export "$key=$value"
+  done <"$file"
+}
+
+. ci/scripts/common/nats_env.sh
+
+TRON_GATEWAY_ENV_NAME="${TRON_GATEWAY_ENV:-prod}"
+RUNTIME_ENV_FILE="./ci/${TRON_GATEWAY_ENV_NAME}/.env.runtime"
+
+if [ ! -f "${RUNTIME_ENV_FILE}" ]; then
+  echo "[tron-gateway-deploy] runtime env file not found: ${RUNTIME_ENV_FILE}" >&2
+  exit 1
+fi
+
+normalize_env_file "${RUNTIME_ENV_FILE}"
+normalize_env_file ./.env.version
+
+load_env_file "${RUNTIME_ENV_FILE}"
+load_env_file ./.env.version
+
+TRON_GATEWAY_MONGO_SECRET_PATH="${TRON_GATEWAY_MONGO_SECRET_PATH:?missing TRON_GATEWAY_MONGO_SECRET_PATH}"
+TRON_GATEWAY_RPC_SECRET_PATH="${TRON_GATEWAY_RPC_SECRET_PATH:?missing TRON_GATEWAY_RPC_SECRET_PATH}"
+TRON_GATEWAY_WALLET_SECRET_PATH="${TRON_GATEWAY_WALLET_SECRET_PATH:?missing TRON_GATEWAY_WALLET_SECRET_PATH}"
+TRON_GATEWAY_VAULT_SECRET_PATH="${TRON_GATEWAY_VAULT_SECRET_PATH:?missing TRON_GATEWAY_VAULT_SECRET_PATH}"
+
+export TRON_GATEWAY_MONGO_USER="$(./ci/vlt kv_get kv "${TRON_GATEWAY_MONGO_SECRET_PATH}" user)"
+export TRON_GATEWAY_MONGO_PASSWORD="$(./ci/vlt kv_get kv "${TRON_GATEWAY_MONGO_SECRET_PATH}" password)"
+
+export TRON_GATEWAY_RPC_URL="$(./ci/vlt kv_get kv "${TRON_GATEWAY_RPC_SECRET_PATH}" tron_rpc_url)"
+export TRON_GATEWAY_GRPC_URL="$(./ci/vlt kv_get kv "${TRON_GATEWAY_RPC_SECRET_PATH}" tron_grpc_url || true)"
+
+export TRON_GATEWAY_SERVICE_WALLET_KEY="$(./ci/vlt kv_get kv "${TRON_GATEWAY_WALLET_SECRET_PATH}" private_key)"
+export TRON_GATEWAY_SERVICE_WALLET_ADDRESS="$(./ci/vlt kv_get kv "${TRON_GATEWAY_WALLET_SECRET_PATH}" address || true)"
+
+export TRON_GATEWAY_VAULT_ROLE_ID="$(./ci/vlt kv_get kv "${TRON_GATEWAY_VAULT_SECRET_PATH}" role_id)"
+export TRON_GATEWAY_VAULT_SECRET_ID="$(./ci/vlt kv_get kv "${TRON_GATEWAY_VAULT_SECRET_PATH}" secret_id)"
+if [ -z "${TRON_GATEWAY_VAULT_ROLE_ID}" ] || [ -z "${TRON_GATEWAY_VAULT_SECRET_ID}" ]; then
+  echo "[tron-gateway-deploy] vault approle creds are empty for path ${TRON_GATEWAY_VAULT_SECRET_PATH}" >&2
+  exit 1
+fi
+
+load_nats_env
+
+bash ci/prod/scripts/bootstrap/network.sh
+bash ci/prod/scripts/deploy/tron_gateway.sh
				`@@ -0,0 +1 @@`
				FyzfUWK+e1eja+tKfkBhLBPHK34pQgsTkgsq8jxocQCt95k5dxbhw8loB+wyZ2LijIXRjGqraurKEHIl4bF12C05pRlazIyiJXA7T2iQzFtEnJW7IQM1rRWcnm5ZKwxlnnjF4t+5E48SUnXUq587iZV+osrHpGxIHu7WKMtRXE6kD+allogQ+6TCcFu8dDg4ruyC1WUkXh/5ivoFyzFE9hK5WDPo8/dURPav8j+rhaP6+ZWKisfzvssVNiLA3jyb+NYiTBgWkVXk9RXH1SpyrQZOHaOon7Kr57KQnksBrv/yJa75FfwZJagpWUkSbqtpz20e8Jimh/1c+fzE8JR0wFd0eprMQQbZ0WM1hadi5FP5I0e883nLh2brUUI9MUC0sO/+qAL7Giv6+eNhrVWfrJBA0TNQ09AygqBrgM0JJGxHe8OBtlQWWcAI58rtSU2eJmNiwMkyzccv3Z7zknjZ4Y/dGTNQ7ckzEyRQE2u+Ujgs1bje/IS+geFieVpwGoRuKyBqQsnH2uKO/M1wrMwGyPo+5AMKhXtYuMCQoz5jNuRFmOxQq/8Jykg07Z2hntoky3nvWAlDgh3B/mXJmZzi4KfXIW1xnNGzxDMnHeuNcCxAe7vlHkLX6xU74DuWUYYi92Sd6oLeyfxZqoqwgO3SEqfErDC3bOIAQBiJHKs+8UwhbfUoEdX/pLenAOPIcq1fcRQIOd/PKE/USlYGFao8mluBqJuXkw8iPeMQEBepuovebTDxIM4whzWQmMqKm/Xn/CZNhv3CISQvGg0IIqNL6q8FxFSRc7aa0ezUMpMFQBt20muL0xz8DGxdzTOqUWXr8ac2JQH0A66UXYW8iBlP3ZPh37BURBVQTB+++uF2p72jGhWHcE873ELV5Xq7LeextIDcz4L8O+C0K8v7v9tsI35PJR93+jNOS8phEkanvN2Yo6v4W1GQ8oBqbFd9R0KIwxgL7iK1H9pfA7lIeBavHjEjz8FqFxltpqz9mHvop41Sybp6