Lightning architecture
VOUT’s Lightning service has two financial responsibilities: recording what each user owns and controlling the assets that back those records. The custodial ledger handles the first. The node, its wallets and its channels handle the second.
The mobile wallet remains a separate system. Its Rust Core validates and signs on-chain operations for the device’s wallet. A Lightning balance comes from the service and represents a claim on VOUT. The app does not add it to the on-chain balance Core verifies.
Deposits and withdrawals move funds on-chain between a wallet and the service’s BTC or RGB custody wallet. The dotted connection identifies a separate capability of the node code. Mainnet configuration currently permits BTC channels only; the RGB custody wallet can operate without an RGB channel.
The account boundary
The app authenticates with the user’s VOUT account session. The service resolves that session to an account identifier and replaces any caller-supplied account field with the authenticated identity. Choosing an account in a request does not grant access to its balance.
Amounts cross the boundary as integer strings. BTC uses millisatoshis; each RGB contract uses its own base units. Asset precision controls display rather than introducing floating-point arithmetic into the ledger.
The ledger
The ledger records entries and updates their balance projection together. Debits run in an immediate database transaction, checking the available balance before writing. Internal transfers update both accounts together. A balance cannot change without an entry explaining the movement.
Incoming Lightning payments are identified by payment hash. The service records the invoice’s owner, asset and amount before giving the request to the user. Replaying the same arrival cannot create a second credit. An unrecognized payment or a mismatched asset is recorded for investigation without guessing an account to credit.
Outside payments reserve funds before the node is asked to send. A successful result settles the payment and returns unused routing fees. A failed result releases the reservation. If communication fails without a definite outcome, the reservation remains pending until reconciliation establishes what happened.
These rules protect accounting consistency. They cannot prove that the node still controls enough assets to satisfy every user balance.
The node and its wallets
The node holds the signing keys and channel state. The ledger holds no keys, but its ability to instruct the node to pay is still spending authority. Separating those services narrows their roles; it does not make the ledger harmless if compromised.
BTC deposits arrive in the node’s on-chain wallet. Channels supply inbound and outbound liquidity for outside payments. An optional operator-authorized liquidity policy can move BTC above a retained on-chain amount into channels with a designated peer. User deposits do not each require a new channel.
RGB deposits use a separate custody wallet, with a key derived from the node seed under a separate derivation domain. This wallet runs Core’s RGB receive and send lifecycle, including proof validation and durable operation records. It can hold an RGB asset while the service transfers claims to that asset internally, without putting the asset into a Lightning channel.
Withdrawals reserve the required funds before entering operator review. Manual channel openings also require review. The configured liquidity policy is a specific authorization for automatic channel funding; it does not approve arbitrary withdrawals.
State that must survive a restart
The node persists channel managers and monitors. RGB channels additionally need their contract bindings, exact signed-state evidence and retained recovery descriptors. The ledger needs its entries and unresolved operations. Restoring only one component can leave accounting ahead of the assets, or assets spent without the corresponding ledger update.
Reserve checks compare user liabilities with the node’s on-chain holdings and its share of channel assets, including the RGB custody wallet. They are an operational check performed by the service, not a public proof of reserves.
Each network has its own service instance and state. The channel-specific state and its recovery limits are covered in Settlement and recovery.