Mierkhat prepares and tracks vault withdrawals on Stellar testnet. Users choose the shares to spend and minimum settlement tokens to receive, review the transaction and sign with their own wallet. The immutable guard enforces the withdrawal and direct swaps in one invocation.
This repository contains the Fastify API, PostgreSQL persistence, recovery workers and @mierkhat/sdk. The service never holds user wallet signing keys. It verifies signed transactions, stores exact retry bytes encrypted before sending them, and reconciles uncertain results by public transaction hash.
| Component | Technology |
|---|---|
| Language and runtime | TypeScript 7.0.2, Node.js 24.22.1 |
| HTTP and validation | Fastify 5.12.7, Zod 4.6.7 |
| Persistence | PostgreSQL 17.6, pg 8.23.1 |
| Stellar | Stellar SDK 17.4.0, Soroban RPC, Horizon |
| Local database | embedded-postgres 17.6.0-beta.15 |
| Verification | Vitest 5.0.5, real PostgreSQL integration tests |
| Package manager | pnpm 12.15.0 |
Use Linux x64 as a non-root user for the embedded database. Install Node.js 24.22.1, then:
git clone https://github.com/Mierkhat/backend.git
cd backend
npm install --global pnpm@12.15.0
pnpm install --frozen-lockfile
pnpm build
pnpm localThe local launcher starts persistent PostgreSQL on 127.0.0.1:55432, applies migrations and starts the API on 127.0.0.1:3001. Random database/encryption credentials stay in ignored .tooling/local/ files. Preserve that directory to resume outstanding submissions after a restart.
curl --fail http://127.0.0.1:3001/v1/health
curl --fail http://127.0.0.1:3001/v1/openapi.jsonRun the frontend separately. The bundled registry enables six withdrawal output profiles and two cross-asset migration profiles across two actual testnet vaults. Readiness and receiving-target planning test complete invocations; opt-in condition watches persist in PostgreSQL and deliver in-app notifications. See withdrawal tools. Account positions are grouped once per vault; quote and setup requests can select a route by epoch. Mainnet is disabled. No real balances or RPC responses are replaced with examples.
Account funding uses Friendbot. Issuing configured test tokens additionally requires TESTNET_FAUCET_KEY_FILE, pointing to a mode-0600 JSON file containing the dedicated issuer's admin secret. Its issuer must match the pinned assets. A fresh clone does not include this credential; without it, issuance reports unavailability. Never use a personal wallet secret for the faucet. Testnet assets have no monetary value.
cp .env.example .env
openssl rand -hex 32Set POSTGRES_PASSWORD, the matching DATABASE_URL and the generated PAYLOAD_KEY in .env. Keep PAYLOAD_KEY stable across restarts. Then:
docker compose up -d
pnpm dev
# Or, after pnpm build:
pnpm startThe server reads .env and serializes migrations with an advisory lock. See operations for deployment, recovery, retention and issuer configuration.
pnpm build
pnpm typecheck
pnpm typecheck:scripts
pnpm --filter @mierkhat/sdk typecheck
pnpm --filter @mierkhat/sdk typecheck:scripts
pnpm test # 4 provider tests
pnpm --filter @mierkhat/sdk test # 37 SDK tests
pnpm test:integration # 16 real PostgreSQL tests
pnpm --filter @mierkhat/sdk check:deploymentsIntegration tests create a temporary real PostgreSQL cluster with a random password, then remove it. They cover encrypted bytes, deduplication, idempotency conflicts, worker leases, terminal updates, expiry, route selection and receipt enrichment. They do not broadcast transactions. Actual testnet acceptance has separate integration instructions.
src/ HTTP service, transaction checks, storage and workers
migrations/ Ordered PostgreSQL schema migrations
sdk/ Transaction preparation, verification, signing and recovery
scripts/ Persistent local service and crash acceptance harness
test/ Actual PostgreSQL integration tests
docs/ API, architecture, operations and integration documentation
compose.yaml Pinned local PostgreSQL service
- Architecture and recovery
- HTTP API and SDK, OpenAPI snapshot
- Operations and configuration
- Integration testing and sibling checkouts
- Frontend and contracts
The SDK is a local workspace package; no npm release is needed. Ordinary owner-signed accounts are supported. Mainnet, fee bumps, separate fee sources and nonstandard signers are rejected. reviewed denotes source/integration verification, not an independent audit.
Enabled testnet routes have a fixed 5 XLM preparation ceiling. Current measured Soroban resource fees exceed the previous 1 XLM ceiling; all eight full-flow preflights are recorded in sdk/fixtures/testnet-fee-preflight.json. The prepared envelope includes its exact simulated resource fee plus inclusion fee, which the frontend shows before wallet approval. The 5 XLM ceiling is a rejection limit, not the amount inserted into every transaction. Fees above it and wallet mutations remain rejected.
In the original combined workspace, run ./scripts/pnpm --filter @mierkhat/backend <command> from its root. The local launcher retains that workspace's root .tooling/local/ storage. Standalone clones use this repository's .tooling/local/.
Read CONTRIBUTING.md before opening a pull request. Report sensitive issues through the security policy.
Mierkhat-authored code uses the MIT license. Dependencies, upstream protocols, fonts where bundled and brand usage retain the terms described in third-party notices.