Core Concepts

The LuminaDex SDK is built around several key concepts that are important to understand before diving into implementation details.

State Machines

At the heart of the SDK are two main state machines powered by XState:

Wallet Machine

The Wallet machine handles all interactions with the Mina blockchain wallet:

• Detecting wallet extension presence
• Connecting to the wallet
• Switching networks
• Fetching account balances
• Handling network and account changes

DEX Machine

The DEX machine handles all operations related to the Lumina DEX:

• Compiling and loading smart contracts
• Swapping tokens
• Adding/removing liquidity
• Deploying pools and tokens
• Minting tokens
• Claiming from faucet (on test networks)
• Tracking and resuming transactions via dedicated child transactionMachine actors

Both machines expose an UNSUPPORTED state when no Mina wallet provider is available in the browser. Use this to drive UI that recommends installing Auro Wallet.

Transaction Machines

Every user action that emits a zkApp transaction spawns (or resumes) a transactionMachine responsible for signing, sending, persisting and waiting for inclusion. Instead of storing raw { hash, url } pairs in the action context, the DEX context now keeps a transactionLid and a transactions map of child actors. See the Transaction Tracking guide for details.

Network Types

The SDK supports several network configurations:

type NetworkLayer = "mina" | "zeko"
type ChainNetwork = "mainnet" | "devnet" | "testnet"
type NetworkUri = "mina:mainnet" | "mina:devnet" | "zeko:testnet" | "zeko:mainnet"

These network identifiers are used throughout the SDK to specify which blockchain network to interact with.

Actor System

The SDK uses an actor-based approach where state machines are instantiated as actors that can:

1. Receive events through the send() method
2. Maintain internal state
3. Execute side effects
4. Communicate with other actors

// Create actors
const Wallet = createWallet()
const Dex = createDex({ input: { wallet: Wallet, ... } })

// Send events to actors
Wallet.send({ type: "Connect" })
Dex.send({ type: "ChangeSwapSettings", settings: { ... } })

// Subscribe to actor state changes
Wallet.subscribe(state => {
  console.log("New wallet state:", state.value)
})

//Read the actor state
console.log(Wallet.getSnapshot())

Web Workers

For computationally intensive operations like cryptographic calculations, the SDK utilizes Web Workers to free-up the main thread. The DEX machine spawns a worker that handles:

• Contract compilation with a remote cache
• Cryptographic operations
• Transaction preparation

Additionally, o1js is being used, which includes other web workers based optimizations.

This architecture ensures the main thread remains responsive during heavy computations, such as contract compilation or zk proof generations.

GraphQL for Blockchain Data

The SDK uses GraphQL to fetch blockchain data from Mina nodes and archive services. It provides:

• Pre-configured GraphQL clients with urql
• Type-safe queries using gql.tada
• GraphQL schemas for Mina, Archive, and Zeko services
• Helper functions for common data requests