JSPM – lumos-luna-sdk@1.13.2

Package Exports

lumos-luna-sdk
lumos-luna-sdk/cli
lumos-luna-sdk/lumos
lumos-luna-sdk/primitives
lumos-luna-sdk/vibe

Readme

Lumos Luna SDK

On-Chain Primitives for Terra Classic
_{Proof-of-Burn | Negative-Yield Staking | Invariant-Only Stable Vault}

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

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

See CONTRIBUTING.md for details.

License

MIT License - see LICENSE

Built by Schero94 for Terra Classic