Skip to content

docs: explain Stellar network selection and deposit preparation #1405

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Obaara293 wants to merge 3 commits into
base: main
Choose a base branch
from
+29 −4
Open

docs: explain Stellar network selection and deposit preparation #1405

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
55174e2
security: Explain Stellar network selection and deposit preparation (…
Obaara293 Sep 29, 2026
2a869bf
security: Explain Stellar network selection and deposit preparation (…
Obaara293 Sep 29, 2026
b6095ff
security: Explain Stellar network selection and deposit preparation (…
Obaara293 Sep 29, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions docs/deposit-transaction-builder.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,10 @@ Requires authentication via `x-user-id` header.
- `network` (optional): Stellar network identifier
- Values: `"testnet"` or `"mainnet"`
- Default: `"testnet"`
- Must match `config.stellar.network`. `DepositController` rejects any other
value with `INVALID_NETWORK` before the transaction builder is invoked, so
a request for a network that differs from the server configuration fails
even if the identifier is otherwise well-formed.

- `source_account` (optional): Custom source account for the transaction
- Format: Valid Stellar public key (G... with 56 characters)
Expand Down
29 changes: 25 additions & 4 deletions docs/network-configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# Stellar Network Configuration

This backend supports two networks:
- `testnet`
- `testnet`
- `mainnet`

Use one active network per deployment to avoid mixing chain data.
Expand Down Expand Up @@ -36,7 +36,7 @@ STELLAR_TESTNET_SETTLEMENT_CONTRACT_ID=CC...TESTNET_SETTLEMENT
STELLAR_MAINNET_HORIZON_URL=https://horizon.stellar.org
SOROBAN_MAINNET_RPC_URL=https://soroban-mainnet.stellar.org
STELLAR_MAINNET_VAULT_CONTRACT_ID=CC...MAINNET_VAULT
STELLAR_MAINNET_SETTLEMENT_CONTRACT_ID=CC...MAINNET_SETTLEMENT
STELLAR_MAINNET_SETTLEMENT_CONTRACT_ID=CB...MAINNET_SETTLEMENT
```

## Behavior Guarantees
Expand All @@ -49,10 +49,31 @@ STELLAR_MAINNET_SETTLEMENT_CONTRACT_ID=CC...MAINNET_SETTLEMENT
- Remote Stellar endpoints must use `https://`; plain `http://` is only allowed for localhost-based development endpoints.
- Stellar endpoint URLs must not include embedded credentials, query strings, or URL fragments.

## Network Match Rules for Deposit Preparation

The deposit flow enforces the active network at the controller layer. `DepositController` compares the `Network` field of the incoming `Post /api/vault/deposit/prepare` body against `config.stellar.network and rejects any mismatch before touching Horizon or Soroban.

- Allowed values are the active network only (`testnet` or `mainnet`).
- A mismatch returns HTTP 400 with an `INVALID_NETWORK` error code and a message identifying the expected network.
- The controller also rejects requests whose vault has not been registered, surfacing a vault-not-found error instead of building a transaction.
- Network and vault validation happen before fee estimation, so misconfigured clients fail fast and cheaply.

## Fee and Timeout Environment Variables

The deposit transaction builder derives fees and timebounds from environment variables rather than hard-coding them:

| Variable | Purpose | Default |
| --- | --- | --- |
| `STELLAR_BASE_FEE` | Base fee (in strops) applied to the built transaction | Horizon default when unset |
| `STELLAR_FEE_MULTIPLIER` | Multiplier applied on top of the simulated/base fee | `1` |
| `STELLAR_TX_TIMEOUT_SECONDS` | Transaction timebound in seconds from the current ledger time | `300` |

These values are read through the active network configuration, so changing them requires a restart of the service.

## Optional Aliases

For contract IDs, these aliases are also accepted:
- `SOROBAN_TESTNET_VAULT_CONTRACT_ID`
- `SOROBAN_MAINNET_VAULT_CONTRACT_ID`
- `SOROBAN_MAINNET_VAULT_CONTRACT_ID`
- `SOROBAN_TESTNET_SETTLEMENT_CONTRACT_ID`
- `SOROBAN_MAINNET_SETTLEMENT_CONTRACT_ID`
- `SOROBAN_MAINNET_SETTLEMENT_CONTRACT_ID`