@lumina-dex/sdk v0.17.0

LuminaDex SDK

State machine-driven SDK for interacting with the Lumina DEX on the Mina blockchain

⚠️ Disclaimer

The Lumina DEX SDK is provided "as is" without any warranties or guarantees. While we strive to ensure the SDK's reliability and security, users should be aware that:

• Lumina is not liable for any losses, damages, or issues arising from the use of this SDK
• Users are responsible for validating and testing the SDK's functionality in their applications
• Smart contract interactions always carry inherent risks including potential loss of funds

By using this SDK, you acknowledge and accept these risks and limitations.

Quick Links

• 📚 Documentation - Comprehensive guides and API reference
• 🚀 Getting Started - Installation and basic usage
• 📖 API Reference - Detailed API documentation

Features

• XState Powered: Built on XState state machines for predictable, testable application logic with type-safe events and transitions
• Framework Agnostic: First-class support for both React and Vue with dedicated integrations, while maintaining a framework-agnostic core
• Complete DEX Support: Connect wallets, swap tokens, add/remove liquidity, fetch pool data, and deploy contracts with a consistent API
• Type-Safe: Full TypeScript support with comprehensive type definitions for a better developer experience and fewer runtime errors

Installation

# Using npm
npm install @lumina-dex/sdk

# Using pnpm
pnpm add @lumina-dex/sdk

# Using yarn
yarn add @lumina-dex/sdk

# Using bun
bun add @lumina-dex/sdk

Basic Usage

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

// Create and start a wallet machine actor
const Wallet = createWallet()

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

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

// Subscribe to wallet state changes
Wallet.subscribe(state => {
	console.log("Wallet state:", state.value)
	console.log("Current network:", state.context.currentNetwork)
	console.log("Account address:", state.context.account)
})

Framework Integration

The SDK provides dedicated integration modules for both React and Vue.

React

import {
	createDex,
	createWallet,
	type LuminaContext as LC
} from "@lumina-dex/sdk"
import { useSelector } from "@lumina-dex/sdk/react"
import { createContext, useContext } from "react"

// Create context
const Wallet = createWallet()
const Dex = createDex({
	input: { wallet: Wallet, frontendFee: { destination: "", amount: 0 } }
})
const Context: LC = { Dex, Wallet }
export const LuminaContext = createContext(Context)

// Use in components
function WalletButton() {
	const { Wallet } = useContext(LuminaContext)
	const isReady = useSelector(Wallet, (state) => state.matches("READY"))
	const connect = () => Wallet.send({ type: "Connect" })

	return (
		<button onClick={connect} disabled={isReady}>
			{isReady ? "Connected" : "Connect Wallet"}
		</button>
	)
}

Vue

<script setup lang="ts">
import { dexMachine, walletMachine } from "@lumina-dex/sdk"
import { useActor } from "@lumina-dex/sdk/vue"
import { computed } from "vue"

// Create shared composable
const Wallet = useActor(walletMachine)
const Dex = useActor(dexMachine, {
  input: {
    wallet: Wallet.actorRef,
    frontendFee: { destination: "", amount: 0 }
  }
})

// Reactive state
const isReady = computed(() => Wallet.snapshot.value.matches("READY"))
const connect = () => Wallet.send({ type: "Connect" })
</script>

<template>
  <button @click="connect" :disabled="isReady">
    {{ isReady ? "Connected" : "Connect Wallet" }}
  </button>
</template>

Data Fetching

import { fetchPoolList, fetchTokenList } from "@lumina-dex/sdk"

// Fetch tokens for a specific network
const tokens = await fetchTokenList("mina:devnet")
const pools = await fetchPoolList("mina:devnet")
console.log("Token list:", tokens)
console.log("Pool list:", pools)

// For direct blockchain queries (slower, use server-side)
import { fetchAllFromPoolFactory } from "@lumina-dex/sdk"
const { tokens, pools } = await fetchAllFromPoolFactory({
	network: "mina:devnet"
})

Load Additional Features

By default, the SDK initializes with the Swap feature. You can specify which features you want to load during initialization:

const Dex = createDex({
	input: {
		wallet: Wallet,
		features: ["Swap", "DeployPool"], // Load specific features
		frontendFee: {
			destination: "B62qmdQRb8FKaKA7cwaujmuTBbpp5NXTJFQqL1X9ya5nkvHSuWsiQ1H",
			amount: 1
		}
	}
})

You can load additional features dynamically after initialization:

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

Debugging

You can set in localStorage some specific values to help with debugging and caching:

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

Documentation

For complete documentation, visit https://lumina-dex.github.io/sdk/

Examples

For full working examples, check out:

• sdk-test-react - React integration example
• sdk-test-vue - Vue integration example

License

MIT