Getting Started with LuminaDex SDK

The LuminaDex SDK is a powerful library for interacting with the Lumina DEX contracts on the Mina and Zeko blockchains. It provides a state machine-driven approach to managing wallet connections, token swaps, liquidity provision, and other DEX-related operations.

Installation

npm

npm install @lumina-dex/sdk o1js

pnpm

pnpm add @lumina-dex/sdk o1js

yarn

yarn add @lumina-dex/sdk o1js

bun

bun add @lumina-dex/sdk o1js

Prerequisites

To develop a dapp using the LuminaDex SDK effectively, you'll need:

• A modern JavaScript environment with ES modules support
• A Mina wallet extension installed in the user's browser (like Auro Wallet)
• Basic familiarity with state machines

Quick Links

The SDK is built on top of o1js and xstate. For more information you can refer to the following resources:

• 📜 Contracts Reference - Detailed smart contract reference
• 💻 O1js Docs - Official documentation for the o1js library
• ⚙️ XState Docs - Official documentation for the XState library

Quick Start

The core of the SDK revolves around two main modules:

1. Wallet: Manages wallet connection, network switching, and balance fetching
2. DEX: Handles all DEX-related operations like swapping, liquidity, and token deployment

These modules are xstate machines. Here's a quick example to connect a wallet and initialize the DEX:

import { createDex, createWallet } from "@lumina-dex/sdk"

// Create and start the wallet
const Wallet = createWallet()

// Create and start the Dex
const Dex = createDex({
	input: {
		wallet: Wallet,
		frontendFee: {
			destination: "B62qmdQRb8FKaKA7cwaujmuTBbpp5NXTJFQqL1X9ya5nkvHSuWsiQ1H",
			amount: 1
		}
	}
})

// Connect the wallet
Wallet.send({ type: "Connect" })

Handling ready and loading states

In order to handle loading and ready states, you can look at the context and the state of the machines. Here are some of the useful states :

• Wallet:
  • INIT: The initial state.
  • UNSUPPORTED: No wallet extensions is detected
• Dex:
  • contractSystem:
    • READY: All contracts are ready.
  • dexSystem:
    • DEX.READY: The DEX is ready for operations.

We expose 2 helpers, canDoDexAction and canStartDexAction to determine more granularly which actions are possible.

Feature Loading

You can choose which specific features you need from the SDK when initializing it.

const Dex = createDex({
	input: {
		wallet: Wallet,
		features: ["Swap"] // This is the default.
		frontendFee: {
			destination: "B62qmdQRb8FKaKA7cwaujmuTBbpp5NXTJFQqL1X9ya5nkvHSuWsiQ1H",
			amount: 1
		}
	}
})

You can load the following features:

• Swap: For token swapping functionality
• DeployToken: For deploying new tokens
• Claim: For claiming tokens from the Faucet
• ManualDeployPool: For deploying liquidity pools client side

If you want to load additional features after the SDK has been initialized, you can use LoadFeatures :

Dex.send({ type: "LoadFeatures", features: ["ManualDeployPool"] })

Frontend framework Integration

The SDK is built on xstate and is therefore framework-agnostic, but we provide documentation and example for React and Vue. See the React Integration and Vue Integration pages for complete examples.

• For usage with svelte, see @xstate/svelte
• For usage with solid, see @xstate/solid

For other frameworks and vanilla JS, use xstate actors directly.

Debugging and Caching

There are 2 values that can be set in localStorage to help with debugging and caching:

localStorage.setItem("disableCache", true) // default false
localStorage.setItem("debugLogs", true) // default false in prod

Disabling cache will prevent the SDK from using the remote cache for contract compilation, and will force a compilation of the contracts from scratch. This takes longer, but can be useful for debugging.

Debug Logs will enable additional logging in the console, which can help with debugging issues in the SDK in your application during production or preview stage of the development. These logs are enabled by default in development mode.

What's Next?

• Learn about the Core Concepts behind the SDK's design
• Set up Wallet Connection in your application
• Understand how to implement Token Swapping
• Explore the API Reference for detailed information on all available functions and options