What is Lumos Luna?

Lumos Luna is an SDK that exposes three new on-chain primitives for Terra Classic (LUNC). No new token, no governance overhead, no marketing - just code that works.

Philosophy:

• Contracts are the truth, SDK is comfort
• README replaces whitepaper
• Usage creates standard, not marketing

Deployed Contracts (Mainnet)

All contracts are live on Terra Classic Mainnet (columbus-5):

| Primitive | Contract Address | Admin | |-----------|------------------|-------| | Proof-of-Burn | terra188fdkkvf54er3t6e9zgz6v24d7scykv3lqflpqr8xn063ff387uq0ch3d0 | Immutable | | Negative-Staking | terra13kz7rzdpad9hxdkzn4dln2kfcxy8c7pe0lcwfu8ue9n2dlqqlscqnegaws | Config only | | Stable-Vault | terra1g6pyt9gz3efumwpdvtspg9phge0kuqk4vhugdpv3906yvfkapv6q4s7rvj | Pause only |

Installation

npm install lumos-luna-sdk

Quick Start

Read-Only (No Wallet Required)

import { LumosPrimitives } from 'lumos-luna-sdk';

const lumos = new LumosPrimitives();

// Get burn statistics
const burnStats = await lumos.proofOfBurn.getStats();
console.log('Total burned:', burnStats.data.total_burned);

// Get staking statistics
const stakingStats = await lumos.staking.getStats();
console.log('Total staked:', stakingStats.total_staked);

// Verify vault invariant (supply == reserves)
const invariant = await lumos.vault.verifyInvariant();
console.log('Invariant holds:', invariant.holds); // Always true

With Wallet (Write Operations)

import { LumosPrimitives } from 'lumos-luna-sdk';
import { DirectSecp256k1HdWallet } from '@cosmjs/proto-signing';
import { SigningCosmWasmClient } from '@cosmjs/cosmwasm-stargate';

const lumos = new LumosPrimitives();

// Connect wallet
const wallet = await DirectSecp256k1HdWallet.fromMnemonic(process.env.MNEMONIC, {
  prefix: 'terra'
});
const [account] = await wallet.getAccounts();
const client = await SigningCosmWasmClient.connectWithSigner(
  'https://terra-classic-rpc.publicnode.com',
  wallet
);

lumos.connect(client, account.address);

// Burn LUNC and get proof
const proof = await lumos.proofOfBurn.burn('1000000'); // 1 LUNC
console.log('Burn proof:', proof.txHash);

// Stake with negative yield
const stake = await lumos.staking.stake('10000000', 30); // 10 LUNC, 30 days
console.log('Staked:', stake.txHash);

The Three Primitives

1. Proof-of-Burn Registry

Burn LUNC and receive a non-transferable on-chain proof.

Invariant: proof.burned_amount == actual_burned

// Burn and get proof
const result = await lumos.proofOfBurn.burn('1000000');

// Get your proofs
const proofs = await lumos.proofOfBurn.getProofsByBurner('terra1...');

// Get global stats
const stats = await lumos.proofOfBurn.getStats();

Use cases:

• Verifiable burn history
• Access control based on burn amount
• Composable with other contracts

2. Negative-Yield Staking

Staking that costs LUNC. Part of your stake is burned.

Invariant: stake_weight = amount * time_locked

Config: burn_ratio = 10% (configurable by admin)

// Stake 10 LUNC for 30 days (10% burned = 1 LUNC)
const result = await lumos.staking.stake('10000000', 30);

// Check your stake
const info = await lumos.staking.getStakeInfo('terra1...');

// Unstake after lock period
const unstake = await lumos.staking.unstake('9000000');

// Get leaderboard
const leaders = await lumos.staking.getLeaderboard(10);

What you get:

• Governance weight (stake_weight)
• Priority access
• Proof of commitment

3. Invariant-Only Stable Vault

1:1 USDC-collateralized stablecoin. No algorithm, no governance.

Invariant: total_supply(lUSD) == balance(USDC_vault) - ALWAYS

// Deposit USDC, get lUSD (1:1)
const mint = await lumos.vault.mint('1000000'); // 1 USDC = 1 lUSD

// Burn lUSD, get USDC back (1:1)
const burn = await lumos.vault.burn('1000000'); // 1 lUSD = 1 USDC

// Verify invariant
const check = await lumos.vault.verifyInvariant();
console.log('Supply:', check.supply);
console.log('Reserves:', check.reserves);
console.log('Holds:', check.holds); // Always true

Guarantees:

• No algorithmic peg
• No LUNC collateral
• Mathematical enforcement, not market mechanisms

AI Oracle (Optional)

An AI-powered service that analyzes market data and suggests optimal burn rates.

Features:

• Real-time price data from CoinGecko
• Sentiment analysis
• AI-enhanced recommendations (OpenRouter/OpenAI)
• Automatic contract updates

Run locally:

cd services/ai-oracle
npm install
OPENROUTER_API_KEY=sk-or-... npm run run-once

With wallet (submits to contract):

MNEMONIC="your 24 words" OPENROUTER_API_KEY=sk-or-... npm run run-once

API Reference

LumosPrimitives

const lumos = new LumosPrimitives(config?: {
  lcd?: string;               // Default: mainnet LCD
  contracts?: {
    proofOfBurn?: string;     // Override contract address
    negativeStaking?: string;
    stableVault?: string;
  };
});

Proof of Burn

| Method | Description | |--------|-------------| | burn(amount) | Burn LUNC, get proof | | getStats() | Total burned, proof count | | getProof(id) | Get specific proof | | getProofsByBurner(address) | Get all proofs for address |

Negative Staking

| Method | Description | |--------|-------------| | stake(amount, lockDays) | Stake LUNC (part burned) | | unstake(amount) | Unstake after lock period | | getStats() | Total staked, total burned | | getStakeInfo(address) | Get stake info for address | | getLeaderboard(limit) | Top stakers by weight |

Stable Vault

| Method | Description | |--------|-------------| | mint(usdcAmount) | Deposit USDC, get lUSD | | burn(lusdAmount) | Burn lUSD, get USDC | | getState() | Total supply, reserves | | verifyInvariant() | Check supply == reserves | | isFullyBacked() | Returns true (always) |

Environment Variables

Create a .env file:

# Wallet (for write operations)
MNEMONIC="your 24 word mnemonic phrase"

# AI Provider (for AI Oracle)
OPENROUTER_API_KEY="sk-or-..."
# or
OPENAI_API_KEY="sk-..."

Legacy SDK Features

The SDK also includes the original LunaSDK for general Terra operations:

import { LunaSDK } from 'lumos-luna-sdk';

const sdk = new LunaSDK({
  chain: 'lunc',
  mnemonic: process.env.MNEMONIC
});

// Standard operations
await sdk.getBalance();
await sdk.send('terra1...', '1000000');
await sdk.burn('1000000');

// AI features (with API key)
await sdk.ai.complete('What is LUNC?');
await sdk.ai.generateImage('Terra phoenix');

// NFT minting
await sdk.nft.mintGenerative({ prompt: '...' });

See /examples folder for complete usage examples.

Project Structure

/contracts
  /proof-of-burn       # Rust CosmWasm contract
  /negative-staking    # Rust CosmWasm contract
  /stable-vault        # Rust CosmWasm contract

/src
  /primitives          # SDK wrappers for contracts
  LumosPrimitives.ts   # Main entry point

/services
  /ai-oracle           # AI burn rate recommender

/docs
  INVARIANTS.md        # Mathematical specifications
  WHY_THIS_EXISTS.md   # Philosophy

Building

# Build SDK
npm run build

# Run tests
npm test

# Build contracts (requires Rust)
cd contracts/proof-of-burn
cargo build --release --target wasm32-unknown-unknown

Contributing

1. Fork the repository
2. Create feature branch (git checkout -b feature/xyz)
3. Commit changes (git commit -m 'Add xyz')
4. Push branch (git push origin feature/xyz)
5. Open Pull Request

See CONTRIBUTING.md for details.

License

MIT License - see LICENSE