مستندات دارامرجع فنیبررسی اولیه
این صفحه فقط به انگلیسی موجود است.
Stellar Technology Baseline (Stage 1)
Verified: 2026-10-29. Release numbers come from the GitHub Releases API and Docker Hub, queried on that date. Semantics come from developers.stellar.org and stellar.org.
Evidence labels:
- [OFF] official Stellar page or SDF repository.
- [REL] GitHub release or Docker Hub tag data.
- [PROTO] long-standing protocol behaviour that I know but did not re-fetch today. Re-verify before Testnet.
- [3P] third-party source only; treat as unverified.
Re-verify every row before the first Testnet deployment and again before Mainnet. Protocol 30 is voted on Mainnet on 2026-11-23, during our build.
0. Assumptions in the brief that are outdated or need adjusting
| # | Brief assumes / implies | Current reality (2026-10-29) | Effect on design |
|---|---|---|---|
| A1 | Pin "current" versions | Mainnet runs Protocol 29 (2026-10-01, security fixes only, no new CAPs). Protocol 30 "Bell": Core v30.0.0 released 2026-10-16; Testnet vote 2026-11-03, Mainnet vote 2026-11-23 [OFF]. P30's CAP-88 changes the ledger-header XDR, and SDKs older than the P30 releases fail to decode P30 ledgers [OFF] | Pin P30-ready versions from the start: Go SDK v0.8.0, JS SDK v17.3.0+, RPC/Galexie v30.0.0. The indexer must use P30 XDR before 2026-11-23 |
| A2 | Horizon is a normal component | Horizon is deprecated for new projects: it gets protocol-compatibility updates only, no new features. Stellar RPC is the recommended API [OFF] | No Horizon. RPC for reads and submission; our own indexer for history |
| A3 | Go SDK at github.com/stellar/go | The monorepo is archived. The official SDK is now github.com/stellar/go-stellar-sdk (txnbuild, rpcclient, ingest, xdr, strkey, processors) [OFF/REL] | Import only go-stellar-sdk; never stellar/go |
| A4 | A single Treasury account can absorb concurrent settlements by careful sequence management | An account can have only one transaction consumed per ledger [OFF] | Sequence management alone is not enough. Throughput needs batching (up to 100 operations per transaction) and/or channel accounts: the transaction source is a channel account, while the operation source stays Treasury. This shapes the SequenceManager design (§8) |
| A5 | A supply cap can be enforced on-chain, as in the EVM siblings | A Classic asset has no on-chain supply cap. Any signature set that meets the issuer's medium threshold can issue an unlimited amount with a Payment [OFF] | Either the cap is enforced by native multisig on the issuer (human co-signers) plus backend checks, or by a custom SAC admin contract with the issuer locked. This is decision Q-02 |
| A6 | Burn is an operation | No burn operation exists. Supply is removed by paying the asset back to the issuer, or by Clawback; both destroy the tokens. SAC burn/clawback do the same [OFF] | The domain Burn(asset, amount) maps to Treasury → issuer Payment (medium threshold on Treasury, not on the issuer) |
| A7 | Supply can be read from a node | RPC has no asset-supply endpoint (Horizon's /assets did). Supply = Σ trustline balances + claimable balances + liquidity-pool reserves + SAC contract balances [PROTO/OFF] | Compute supply ourselves. With AUTH_REQUIRED, every possible holder is an account we authorized, so the holder set is known and closed (§10) |
| A8 | Authorization and issuance need separate keys or a contract | Thresholds are per operation class on one account: SetTrustLineFlags is low, Payment and Clawback are medium, and changing signers/thresholds is high [OFF] | Native multisig can separate KYC authorization (a low-weight online signer) from issuance (medium, human signers). See §6 |
| A9 | Quickstart is only a dev tool | Confirmed: "for local development and testing only… not suitable for production" [OFF] | As the brief says |
| A10 | Validator vs RPC | Stellar RPC runs a captive Core (a watcher, not a validator). SDF runs no public Mainnet RPC [OFF] | Self-hosting RPC is mandatory for Mainnet anyway; no validator needed (§11) |
| A11 | Amounts | Classic amounts are int64 in stroops (7 fixed decimals); max ≈ 922,337,203,685.4775807 per balance. SAC contract balances are i128 [OFF/PROTO] | The token unit (Q-04) must fit in 7 decimals, and the largest balance must fit int64 |
None of these breaks the brief's architecture. A4, A5 and A8 materially shape the Treasury and issuer designs.
1. Network
| Item | Value | Source |
|---|---|---|
| Mainnet protocol | 29 (since 2026-10-01) | [OFF] software-versions |
| Next protocol | 30 "Bell": CAP-84 muxed contract addresses (W…), CAP-87 ML-DSA verification host functions, CAP-88 millisecond close time in the ledger header (closeTime stays whole seconds; consecutive ledgers may share a second) | [OFF] Bell upgrade guide |
| P30 effect on us | Not backwards-incompatible at the transaction level; XDR consumers must update | [OFF] |
| Recent protocols | P25 X-Ray (Jan 2026), P26 Yardstick (May), P27 Zipper (Jul), P28 Adapter (Sep: CAP-83 empty tx-set value, CAP-85, CAP-86; faster ledger close; validators must run NTP) | [OFF] |
| Passphrases | Mainnet Public Global Stellar Network ; September 2015; Testnet Test SDF Network ; September 2015; Futurenet Test SDF Future Network ; October 2022 | [OFF] |
| Classic ledger capacity | 1,000 classic operations per ledger on Mainnet (July 2026) | [OFF] fees page |
| Ledger close time | ≈5 s historically; P28 shortened and steadied it. Read it at runtime; never hard-code | [OFF] / [PROTO] |
| Testnet | Reset periodically, so Testnet asset identities are disposable. Friendbot for funding; SDF public Testnet RPC exists | [PROTO] / [OFF] |
2. Software versions (candidates to pin)
| Technology | Current version | Purpose | Maturity | Why selected | Alternatives | Compatibility / upgrade risk | Source |
|---|---|---|---|---|---|---|---|
| Stellar Core | v30.0.0 (2026-10-16); v29.0.0 runs Mainnet P29 | Captive core inside RPC and Galexie | Stable | Required | — | Must be ≥ v30 before 2026-11-23 | [REL] |
| Stellar RPC | v30.0.0 (2026-10-21); image stellar/stellar-rpc:30.0.0 | Reads, simulation, submission, recent events | Stable; SDF's recommended API | Replaces Horizon; self-hostable | Horizon (deprecated); commercial RPC (rejected: independence) | Default history window is 7 days | [REL]/[OFF] |
| Horizon | v30.0.0 | Legacy API | Deprecated (compatibility only) | Not selected | — | — | [REL]/[OFF] |
| Galexie | v30.0.0 (galexie-v30.0.0) | Exports ledger metadata to a data lake (GCS, S3-compatible, filesystem for dev only) | Stable | Only if we need history beyond the RPC window (Q later) | RPC retention window; history archives | Data lake format is versioned | [REL]/[OFF] config |
| Go SDK | github.com/stellar/go-stellar-sdk v0.8.0 (2026-10-20; go 1.25 minimum) | txnbuild, rpcclient, ingest, xdr, strkey | Official, 0.x (API may change between minors) | Our backend is Go; official | JS SDK sidecar (rejected: two languages on the money path) | Pin exactly; wrap behind our StellarGateway port | [REL]/[OFF] README |
JS/TS SDK @stellar/stellar-sdk | v17.4.0 (2026-10-25); v17.3.0 is the P30 minimum for W addresses | Frontends (display only; the custodial model signs server-side) | Official | Next.js frontends | — | v16.x line still patched | [REL]/[OFF] |
| Stellar CLI | v28.1.0 (2026-09-26); P30 release pending | Local network, key generation for dev, SAC deploy, contract build | Stable | Official tooling | — | Need P30 CLI before rebuilding any contract against soroban-sdk 30 | [REL]/[OFF] |
| soroban-sdk (Rust) | v29.0.1 stable; v30.0.0-rc.1 | Only if a contract is selected (Q-02) | Stable | — | — | Use 30.0.0 stable once released (before the vote) | [REL] |
| Rust | 1.97.1 local; contracts need target wasm32v1-none | Contracts only | Stable | — | — | Pin with rust-toolchain.toml | Local |
| OpenZeppelin Stellar Contracts | v0.8.0 (2026-10-20), with an audit report for v0.8.0 in the repo | Audited Soroban building blocks: tokens/{fungible, rwa, vault}, access, governance, accounts, fee-abstraction | 0.x, audited per release | The only audited RWA library found | Custom contract (rejected: §38) | 0.x API churn | [REL] |
OZ rwa module | in v0.8.0 | T-REX / ERC-3643-style Soroban token: identity registry, compliance modules, address and partial freeze, forced transfer, recovery, pause, batch ops, optional cap | Audited with the library | Option C of the asset evaluation | — | It is a contract token, not a Classic asset: DEX, trustlines and Classic wallets do not apply | [OFF] repo |
| Quickstart | stellar/quickstart:latest = v689-b1585.1-latest (2026-10-28) | Local / CI / demo network | Dev only | Official | — | Pin by digest, never latest | [REL] |
3. Classic asset semantics
| Topic | Behaviour | Source |
|---|---|---|
| Identity | asset_code (1–4 chars → alphanum4, 5–12 → alphanum12) + issuer account. The same code from another issuer is a different asset | [OFF] |
| Issuance | A Payment from the issuer creates new units. The issuer holds no balance of its own asset | [OFF] SAC page |
| Burn | A Payment to the issuer destroys units. Clawback also destroys them | [OFF] |
| Distribution pattern | Issuer → distribution (Treasury) account → holders. Issuer and distribution must be separate accounts | [OFF] |
| Trustline | A holder must ChangeTrust (medium threshold, the holder's own signature) before receiving; it costs 0.5 XLM reserve and has a limit | [OFF] |
| Flags (issuer account) | AUTH_REQUIRED (trustlines start unauthorized), AUTH_REVOCABLE (the issuer can de-authorize), AUTH_CLAWBACK_ENABLED (requires revocable), AUTH_IMMUTABLE (flags can never change, and the issuer can never be merged) | [OFF] |
| Trustline auth states | AUTHORIZED (full); AUTHORIZED_TO_MAINTAIN_LIABILITIES (keeps offers, cannot send or receive); unauthorized (frozen) | [OFF]/[PROTO] |
| Clawback scope | Applies only to trustlines that carry TRUSTLINE_CLAWBACK_ENABLED, which is copied from the issuer flag when the trustline is created. Turning clawback on later does not affect existing trustlines | [OFF]/[PROTO] |
| Payment errors | NO_DESTINATION, NO_TRUST, NOT_AUTHORIZED, LINE_FULL, SRC_NO_TRUST, SRC_NOT_AUTHORIZED, UNDERFUNDED | [OFF] |
| Metadata | home_domain on the issuer + stellar.toml (SEP-1) [[CURRENCIES]] | [OFF] |
| Classic events | Since P23 (CAP-67), Classic transfer/mint/burn/clawback/set_authorized emit Soroban-format events, readable through RPC getEvents | [OFF] |
4. Accounts, thresholds, multisig, reserves, fees, sequence numbers
| Topic | Behaviour | Source |
|---|---|---|
| Thresholds | Each account has master weight + up to 20 signers and low/medium/high thresholds (0–255). A transaction needs the summed weight ≥ the threshold of each operation's class | [OFF]/[PROTO] |
| Low | SetTrustLineFlags, AllowTrust (deprecated), BumpSequence, ClaimClaimableBalance; also the transaction source's own check | [OFF] |
| Medium | Payment (= issuance from the issuer), PathPayment*, CreateAccount, ChangeTrust, Clawback, ClawbackClaimableBalance, sponsorship ops, ManageData, SetOptions (flags, home domain) | [OFF] |
| High | SetOptions that changes signers or thresholds; AccountMerge | [OFF] |
| Multisig best practice | Native signers on cold keys; never leave master weight > 0 on the issuer; check that thresholds stay reachable before every change (a misconfiguration locks the account forever) | [OFF]/[PROTO] |
| Minimum balance | (2 + subentries + numSponsoring − numSponsored) × 0.5 XLM. Account = 1 XLM; each trustline / signer / data entry / offer +0.5 XLM; max 1,000 subentries | [OFF] |
| Sponsored reserves | BeginSponsoringFutureReserves / EndSponsoringFutureReserves sandwich in one transaction; both sponsor and sponsored sign; covers account creation (starting balance 0), trustlines, signers, data, offers. The sponsor can revoke or transfer | [OFF] |
| Fees | Inclusion fee ≥ 100 stroops per operation; surge pricing when demand exceeds capacity (everyone pays the lowest included bid). The fee is charged even when the transaction fails | [OFF]/[PROTO] |
| Fee bump | A fee account wraps a signed inner transaction and pays the fee; replacing a pending transaction needs a 10× fee bid | [OFF] |
| Ops per transaction | ≤ 100 Classic operations; Soroban: 1 (+1 if fee-bumped) | [OFF] |
| Sequence numbers | Transaction seq must be account seq + 1 (or within minSeqNum with that precondition). A failed transaction still consumes the sequence number and the fee; txBAD_SEQ does not consume anything [PROTO]. One transaction per source account per ledger [OFF] | [OFF]/[PROTO] |
| Preconditions | Time bounds (ledger close time), ledger bounds, minSeqNum, min sequence age, min sequence ledger gap, up to 2 extra signers. An upper time bound of 0 keeps a transaction valid forever: never use 0 | [OFF] |
| Source accounts | The transaction source pays the fee and supplies the sequence number; each operation may name another source account, whose threshold must then be met | [OFF] |
| Finality | SCP has no reorgs: a transaction in a closed ledger is final. "Unknown" exists only between submission and the time bound | [PROTO] |
5. Stellar RPC: production deployment
| Item | Value | Source |
|---|---|---|
| Methods | Docker stellar/stellar-rpc (preferred), Debian package from apt.stellar.org, or source | [OFF] |
| Configuration | TOML file (recommended for production); runs a captive Core inside | [OFF] |
| Hardware (Mainnet) | 4–8 vCPU, 16 GB RAM, 350 GB local SSD with ≥ 3K IOPS for the default 7-day window; +≈40 GB per extra retention day; ≥ 32 GB RAM and horizontal scaling above ~500 req/s | [OFF] prerequisites |
| History | Default 7-day window. Longer history comes from a Galexie data lake ("connect a data lake") | [OFF] |
| Health / metrics | getHealth (status, latest/oldest ledger; v27.1+ adds close times); Prometheus /metrics on the admin endpoint | [OFF]/[3P] |
| Public Mainnet RPC | SDF provides none; only Testnet and Futurenet | [OFF] |
| Quickstart | Local and test only | [OFF] |
6. Stellar Asset Contract (SAC) and Soroban tokens
| Topic | Behaviour | Source |
|---|---|---|
| Identity | One SAC per Classic asset; the same asset and the same supply, not a wrapper. Contract ID is deterministic from asset + network | [OFF] |
| Deployment | Anyone can deploy it. It is not needed for Classic accounts to use the asset | [OFF] |
| Admin | Defaults to the issuer; set_admin can hand it to a G account or a contract. Admin functions: mint, clawback, set_authorized, set_admin | [OFF] |
| Flags | Enforces the issuer's Classic flags (auth required, revocable, clawback) | [OFF] |
| Custom SAC admin caveat | If the issuer's signers stay active, they can still issue, claw back and change trustline flags directly, bypassing the admin contract. A contract-enforced cap therefore requires locking the issuer (master weight 0, no signers) after set_admin (irreversible) | [OFF] custom-sac-admin |
| Balances | G accounts: int64 trustlines. Contract addresses: i128 contract data | [OFF] |
| Production example | USDT0 on Stellar: a Classic asset whose SAC admin is a role-gated contract, with the issuer locked | Skill reference, re-verify |
7. Indexing and data
| Option | Status | Fit |
|---|---|---|
RPC getEvents / getTransactions / getLedgers | Official; recent window only (default 7 days) | Primary MVP source. Since CAP-67, every Classic payment, mint, burn, clawback and set_authorized is an event |
Go Ingest SDK (go-stellar-sdk/ingest) | Official; reads Captive Core, a Galexie data lake or RPC | Our indexer library: typed ledger-meta processing, gap-free by ledger sequence |
| Galexie + CDP | Official, v30.0.0; S3-compatible storage works, so self-hosted MinIO/Ceph is possible | Only if we need more history than the RPC window or a replayable archive (decided later) |
| History archives | Official, public | Last-resort backfill |
| Horizon | Deprecated | Not used |
| Hosted indexers (Hubble, etc.) | Third-party | Not used for correctness |
8. Implications for the Treasury and sequence design (preview)
- One transaction per account per ledger means a single Treasury source account does ≈1 transaction per ledger. Batching up to 100 payments per transaction raises this to ≈100 settlements per ledger.
- Channel accounts: N small fee/sequence accounts act as transaction sources while Treasury is the operation source. Treasury signs for its operations; the channel signs the envelope. This is the standard Stellar pattern for parallel submission from one asset holder.
- The SequenceManager therefore manages a pool of channel accounts, with one in-flight transaction per channel and a strict time bound. Recovery after a crash: look up the hash; if it is not found and the ledger is past the time bound, the transaction can never apply. Re-read the sequence number from the chain, then rebuild.
- Whether this is needed is measured in Stage 25 and not assumed.
9. Ownership of fees and reserves (preview, depends on Q-01)
| Account | Reserve | Funded by |
|---|---|---|
| Issuer | 1 XLM + 0.5 per signer | Platform |
| Treasury | 1 XLM + 0.5 per trustline + signers | Platform |
| Channel accounts | 1 XLM each | Platform |
| Per-customer account (if chosen) | 1 XLM + 0.5 per asset trustline | Sponsored by a platform sponsor account (customer holds 0 XLM) |
Fees: 100 stroops per operation at base, and more under surge. At the base fee, 1 M settlements cost ≈ 10 XLM.
10. Supply reconciliation (preview)
Outstanding supply of a Classic asset = Σ all trustline balances + claimable balances + liquidity-pool reserves + SAC contract balances. With AUTH_REQUIRED and no authorized liquidity pools or contracts, it equals Σ balances of the trustlines we authorized. Every one of those accounts is known to us, so the supply can be read exactly with getLedgerEntries and cross-checked against the indexer's running sum of mint/burn/clawback events.
11. Validator architecture
| Option | Assessment |
|---|---|
| A. Self-hosted RPC (captive Core) ×2 | Meets the independence requirement; no quorum responsibilities. Recommended (as in the siblings) |
| B. + a non-validating watcher/archive Core | Adds a history archive we control; useful only if Galexie or long history is selected |
| C. Validator | SDF's guidance expects organizations to run three validators plus a public history archive to be a reliable tier-1 participant [PROTO]; a quorum misconfiguration can halt or fork our node. No benefit for an asset issuer. Not recommended |
A Stellar node cannot create Mainnet history while disconnected; brief §66 is correct.
12. Assumptions in the brief confirmed as correct
§16 (separate issuer and distribution), §30 (SELL is not a burn), §50 (no Ethereum states; Stellar has no reorgs), §52 (a timeout is not a failure), §60–61 (self-hosted RPC, Quickstart is dev only), §64 (no validator needed), §66 (no offline Mainnet history), §72 (no hosted indexer is needed).
Sources
- https://developers.stellar.org/docs/networks/software-versions
- https://stellar.org/blog/developers/bell-protocol-30-upgrade-guide
- https://stellar.org/blog/developers/adapter-protocol-28-upgrade-guide
- https://developers.stellar.org/docs/data/apis (Horizon deprecated, RPC recommended)
- https://developers.stellar.org/docs/data/apis/rpc/admin-guide (+
/prerequisites,/installing) - https://developers.stellar.org/docs/learn/fundamentals/lumens
- https://developers.stellar.org/docs/learn/fundamentals/transactions/list-of-operations
- https://developers.stellar.org/docs/learn/fundamentals/transactions/operations-and-transactions
- https://developers.stellar.org/docs/learn/fundamentals/fees-resource-limits-metering
- https://developers.stellar.org/docs/build/guides/transactions/sponsored-reserves
- https://developers.stellar.org/docs/tokens/stellar-asset-contract
- https://developers.stellar.org/docs/build/guides/tokens/custom-sac-admin
- https://developers.stellar.org/docs/data/indexers/build-your-own/galexie and
stellar/stellar-galexie/config/config.example.toml - https://github.com/stellar/go-stellar-sdk (README, go.mod)
- https://github.com/OpenZeppelin/stellar-contracts (
packages/tokens/src/rwa,audits/) - GitHub Releases API: stellar-core, stellar-rpc, stellar-cli, go-stellar-sdk, js-stellar-sdk, rs-soroban-sdk, stellar-horizon, stellar-galexie, OpenZeppelin/stellar-contracts; Docker Hub
stellar/quickstart,stellar/stellar-rpc