مستندات دارامرجع فنیتصمیمهای معماری
این صفحه فقط به انگلیسی موجود است.
Decision Log
Status: Accepted (confirmed by the product owner) · Provisional (engineering default, confirm before production) · Proposed (awaiting decision) · Open (not yet asked).
A decision is never changed silently. A conflicting new decision names the one it supersedes.
Recorded decisions
| ID | Decision | Selected | Consequences | Status |
|---|---|---|---|---|
| D-E01 | Data API | Stellar RPC v30; no Horizon | Horizon is deprecated for new projects; supply and history come from our indexer | Provisional |
| D-E02 | Go SDK | github.com/stellar/go-stellar-sdk v0.8.0, exact pin; never the archived stellar/go | v0.8.0 decodes P30 ledgers | Provisional |
| D-E03 | Protocol target | Build against P30 (Mainnet vote 2026-11-23); test on Quickstart P30 | No P29-only XDR anywhere | Provisional |
| D-E04 | Settlement finality | A transaction in a closed ledger is final (SCP, no reorgs). UNKNOWN is resolved by hash lookup; "not applied" is proven only once a closed ledger's close time passes the transaction's upper time bound | No confirmation-depth logic | Provisional |
| D-E05 | Time bounds | Every transaction has an upper time bound (never 0) | No indefinitely valid signed transactions | Provisional |
Blocking decisions: group 1 (asked and answered 2026-10-29)
The product owner answered "go ahead" to the recommendations in discovery/STELLAR_TECHNOLOGY_BASELINE.md and the Stage 1 report. Each took the recommended option.
| ID | Topic | Selected | Consequences | Status |
|---|---|---|---|---|
| Q-00 | Relationship to sibling projects | Port with review. Chain-independent Go modules, migrations and frontends come from ../carbon-blockchain-ethereum-l1 at clean commit eefc5f2 (its uncommitted observability work is not ported). The Stellar chain layer is new. The sibling's product answers carry over except Q-01–Q-04 (listed in D-S01) | Provenance per module in discovery/PORT_LOG.md; Review Pass 1 treats ported code as new | Accepted (2026-10-29) |
| Q-01 | Custody and on-chain visibility | Custodial, one Stellar account per customer, every BUY/SELL/TRANSFER settles on-chain. The platform creates customer accounts and trustlines with sponsored reserves (the customer account holds 0 XLM) and pays all fees. Keys stay in the platform signer. No external withdrawals or deposits in the MVP | ≈1 XLM + 0.5 XLM per asset locked (recoverable) per customer; holdings visible on-chain per account (privacy notice); Treasury throughput needs channel accounts (baseline §8) | Accepted (2026-10-29) |
| Q-02 | Asset model and issuer authority | Classic Stellar asset; no Soroban contract in the MVP. The issuer is controlled by native multisig: issuance (Payment, medium threshold) needs human hardware signers; an online low-weight authorization signer can only SetTrustLineFlags (low threshold); signer/threshold changes (high) need all governance signers. Issuer master weight 0. SAC not deployed in the MVP | The supply cap is enforced by backend checks + human co-signing, not by code on-chain. A custom SAC admin (option B) stays possible later without changing asset identity | Accepted (2026-10-29) |
| Q-03 | Issuer flags | AUTH_REQUIRED + AUTH_REVOCABLE + AUTH_CLAWBACK_ENABLED, set before any trustline exists; never AUTH_IMMUTABLE | Only holders we authorize can hold the asset (closed holder set → exact supply check). Freeze = revoke authorization. Clawback is a dual-approved, disclosed, audited power | Accepted (2026-10-29) |
| Q-04 | Unit | GOLD: 1 GOLD = 1 g of 750 (18 k) gold (carried over from the siblings). SILVER and OIL: Open | The platform stays generic; SILVER/OIL may exist in local/demo with a visible "unit not defined" label; their production creation is blocked until defined | GOLD Accepted; SILVER/OIL Open |
| ID | Decision | Selected | Status |
|---|---|---|---|
| D-S01 | Product answers carried over by Q-00 | (1) Manual admin mid price per asset, buy/sell spread in bps, 30 s quote TTL, stale price blocks trading, large price move needs a second approver. (2) Currency IRR stored as integer Rials; UI shows Toman. (3) Chain unreachable → fail closed: no new BUY/SELL/TRANSFER, in-flight operations stay pending, reads and quotes continue. (4) No validators; two self-hosted RPC nodes. (5) Maker-checker (four-eyes) for reserve changes, issuance, burn, cash, clawback, signer changes, staff roles. (6) Transfers only between platform users. (7) Admin console on private network/VPN, password + TOTP. (8) Frontends: customer wallet PWA, admin console, public scanner, landing site (fa/en, RTL). (9) No Redis | Accepted (via Q-00) |
| D-S02 | Token precision | Stellar's fixed 7 decimals (1 stroop = 10⁻⁷ unit = 0.1 µg for GOLD). Business amounts are integers in stroops; minimum trade size is configurable per asset | Provisional |
Question backlog (later groups)
| Group | ID | Topic | Blocks |
|---|---|---|---|
| 2 | Q-07 | Issuer signer set: number of human signers, weights, thresholds, hardware — decided 2026-10-31: one signer, software key (../decisions/OWNER_DECISIONS_20261031.md) | issuer ceremony |
| 2 | Q-08 | Dual approval list and limits (issuance, burn, large Treasury moves, clawback, signer changes) — volume decided 2026-10-31: ~1 order/s at peak; per-asset limits are console settings | RBAC |
| 3 | Q-09 | External deposits/withdrawals to non-platform Stellar wallets (future). If yes, the conventional pattern is a SEP-8 approval server (every transfer co-signed after a compliance check) with regulated = true in stellar.toml, and SEP-10/SEP-12 for wallet authentication and KYC. This breaks the closed holder set, so the supply check must change | trustline policy, reconciliation |
| 3 | Q-10 | History requirement (RPC 7-day window vs Galexie data lake). Interim: indexer backfill reads the public Mainnet data lake (AWS Open Data, SEP-54); the decision is whether to run our own Galexie bucket for independence — decided 2026-10-31: our own lake on local disk | indexer, storage |
| 3 | Q-11 | Production orchestration and hosting (Compose / Kubernetes / VM) | IaC |
| 3 | Q-12 | HSM/KMS for the online Ed25519 keys — decided 2026-10-31: Vault Transit | signer |
| 3 | Q-13 | Asset codes and home_domain — GOLD only; domain still open | asset ceremony |
| 4 | Q-14 | RTO/RPO | DR |