Client Layer

Any client, whether a wallet application, a payment processor, or an internal service, must implement the mechanisms defined in this section to interact with the Moonlight protocol. A compliant client is able to manage the user’s master account, deterministically derive UTXO addresses, construct and sign transactions, and communicate with authorized privacy providers.

The reference Moonlight SDK offers ready-made modules that satisfy these requirements, but custom implementations are acceptable as long as they follow the specification precisely.

Key Derivation Scheme

Derivation lets a single master secret control an unlimited set of UTXO key pairs while keeping every address bound to the correct network and Privacy Channel. A compliant client feeds this composite seed into the agreed Key Derivation Function, which deterministically produces a secp256r1 key pair. Incrementing the counter yields the next address, giving the application an unlimited, ordered sequence of UTXO keys.

To create each secp256r1 key pair, the client builds a seed by concatenating the following context items in the order shown:

• Network identifier – the passphrase that uniquely identifies the target Stellar network.
• Privacy Channel ID – the Soroban contract address of the channel.
• Master secret key – the user’s root secret.
• Stepping Suffix – a unique suffix generated by a step function based on a sequential integer that starts at 0 and increments for every new UTXO address.

flowchart TB
  TEMPLATE --> ALL
  linkStyle default stroke:#7DAEFF,stroke-width:1.5px           %% Lunar-Ice arrows
	style ALL fill:#2A2C33,stroke:#2A2C33,color:#FFFFFF
	style TEMPLATE fill:#2A2C33,stroke:#2A2C33,color:#FFFFFF
    
  classDef net  fill:#8C7AFF,stroke:#2A2C33,color:#12131A,stroke-width:1px
  classDef ch   fill:#7DAEFF,stroke:#2A2C33,color:#12131A,stroke-width:1px
  classDef sec  fill:#FF6B6B,stroke:#2A2C33,color:#FFFFFF,stroke-width:1px
  classDef step fill:#F3F4F6,stroke:#2A2C33,color:#12131A,stroke-width:1px
  classDef addr fill:#7DAEFF,stroke:#2A2C33,color:#12131A,stroke-width:1px
  classDef box  fill:#F3F4F6,stroke:#2A2C33,color:#E8E9F0

  subgraph TEMPLATE["Derivation Seed Schema"]
    direction LR
    NET["Network<br/>ID"]:::net --- CHA["Channel<br/>ID"]:::ch --- SEC["Master<br/>Secret"]:::sec --- IDX["Step n"]:::step
  end

  subgraph ALL["Derived Addresses"]
    direction LR
    class ALL box

    subgraph SEED0["Seed #0"]
      direction LR
      n0["Stellar Mainnet"]:::net --- c0["Channel 0x1234"]:::ch --- s0["Master Secret"]:::sec --- i0["Step 0"]:::step
    end
    style SEED0 fill:#F3F4F6,stroke:#2A2C33,color:#12131A       %% light-grey seed box
    kp0["keypair #0"]:::addr
    SEED0 --> kp0

    subgraph SEED1["Seed #1"]
      direction LR
      n1["Stellar Mainnet"]:::net --- c1["Channel 0x1234"]:::ch --- s1["Master Secret"]:::sec --- i1["Step 1"]:::step
    end
    style SEED1 fill:#F3F4F6,stroke:#2A2C33,color:#12131A
    kp1["keypair #1"]:::addr
    SEED1 --> kp1

    subgraph SEED2["Seed #2"]
      direction LR
      n2["Stellar Mainnet"]:::net --- c2["Channel 0x1234"]:::ch --- s2["Master Secret"]:::sec --- i2["Step 2"]:::step
    end
    style SEED2 fill:#F3F4F6,stroke:#2A2C33,color:#12131A
    kp2["keypair #2"]:::addr
    SEED2 --> kp2

    subgraph SEED3["Seed #3"]
      direction LR
      n3["Stellar Mainnet"]:::net --- c3["Channel 0x1234"]:::ch --- s3["Master Secret"]:::sec --- i3["Step 3"]:::step
    end
    style SEED3 fill:#F3F4F6,stroke:#2A2C33,color:#12131A
    kp3["keypair #3"]:::addr
    SEED3 --> kp3
  end

The client passes this composite seed to the agreed Key Derivation Function (a deterministic cryptographic routine) to obtain one private-public key pair. Incrementing the counter and repeating the function yields the next address, giving the client an ordered sequence of UTXO keys.

Characteristics of this schema

• Embedding the network identifier and channel ID in the seed keeps each derived key context-specific, helping wallets organise addresses by network and channel.
• Any conforming client can reproduce the exact address sequence by iterating the counter, making balance recovery straightforward.
• Users need to back up only their single master secret; all UTXO addresses are reproducible whenever needed.
• The schema can evolve and be expanded in future versions of the protocol by managing the underlying elements of the derivation seed.

Transaction bundling and signing

This subsection will define how a client groups user-selected inputs and outputs into a bundle and applies the required signatures so the bundle passes protocol verification in the channel contract.

Work in progress.

UTXO management

This part will describe how a client keeps track of all derived UTXOs, checks their balances and states locally, and presents them to the user as a single aggregated account balance for seamless spending.

Work in progress.

Receiving address generation

When a user plans to receive funds, the client chooses one or more fresh addresses according to a user-defined entropy level, splits the expected amount across those addresses, and encodes the result in a protocol-standard XDR structure ready for sharing with senders.

Work in progress.

Privacy provider integration

This section will specify how a client connects to the standard provider API so that prepared bundles can be relayed by an authorised privacy provider to the channel.

Work in progress.