![\"Lumos](\"https://raw.githubusercontent.com/Schero94/lumos-luna-sdk/main/Lumos-Luna-io.png\")
\n\n \n
\n AI-Powered DeFi Ecosystem for Terra Classic
\n 6 Smart Contracts | AI Oracle | Luna Identity | Stable Vault V2 | Proof-of-Burn | Negative Staking\n
\n ![\"npm](\"https://img.shields.io/npm/v/lumos-luna-sdk.svg?style=flat-square\")
\n ![\"License:](\"https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square\"){kind=icon}
\n ![\"GitHub](\"https://img.shields.io/github/stars/Schero94/lumos-luna-sdk?style=flat-square\")
\n Website · \n Luna Identity App · \n npm · \n Stable Vault V2 on Terra Finder\n
\n\n---\n\n## Live Demo\n\n| App | URL | What it does |\n|-----|-----|-------------|\n| **Luna Identity App** | [luid.fitlex.me](https://luid.fitlex.me) | Mobile wallet + DeFi + on-chain identity in one PWA |\n| **Marketing Site** | [lunar.fitlex.me](https://lunar.fitlex.me) | Ecosystem overview, live on-chain stats, AI burn rate |\n\n---\n\n## Luna Identity App\n\nA full-featured **mobile wallet and DeFi app** for Terra Classic, installable as a PWA. Try it at [luid.fitlex.me](https://luid.fitlex.me).\n\n### Wallet\n- **Create or import** wallet (BIP39 mnemonic, Terra Classic HD path)\n- **Send LUNC** to any address (Binance, MEXC, other wallets) with memo support\n- **Receive** with scannable QR code\n- **Balance display** for LUNC + USTC with manual refresh\n- **Transaction history** (sends, receives, swaps, contract calls)\n- Encrypted local storage (AES-256-GCM) with password visibility toggle\n\n### Identity (On-Chain)\n- **Register** a SoulBound digital citizenship by burning LUNC\n- **ID Card** with QR code for public verification (`/verify/[address]`)\n- **Level system** — burn more to level up (Citizen → Senator → Founder)\n- **Governance** — create and vote on proposals (level 3+)\n\n### DeFi\n- **Swap** LUNC → USTC on TerraSwap with live pool quotes, slippage control, price impact warnings\n- **Stable Vault** — mint lUSD (1:1 USDC-backed) / redeem USDC, with identity-based fee discounts\n- **Proof of Burn** — burn LUNC and receive immutable on-chain receipts\n\n### Tech\n- Next.js 14 PWA (installable on iOS/Android)\n- CosmJS signing (DirectSecp256k1HdWallet + SigningCosmWasmClient)\n- Live on-chain data from Terra Classic LCD\n- LUNC price, AI Oracle burn rate, market data via CoinGecko\n\n---\n\n## What is Lumos Luna?\n\nLumos Luna is a complete DeFi ecosystem for Terra Classic (LUNC) with **6 smart contracts** deployed on mainnet, an **AI-powered burn oracle**, and a **1:1 USDC-backed stablecoin** with identity-based fee discounts.\n\n**Philosophy:**\n- Contracts are the truth, SDK is comfort\n- README replaces whitepaper\n- Usage creates standard, not marketing\n\n---\n\n## Deployed Contracts (Mainnet)\n\nAll 6 contracts are live on **Terra Classic Mainnet** (columbus-5):\n\n| Contract | Address | Admin | Status |\n|----------|---------|-------|--------|\n| **AI Burn Oracle** | [`terra19yr...633nf`](https://finder.terra.money/classic/address/terra19yr2f0akzjaerequfzm4aeecdplychkkq0pfwcetqqd8s5e6lk4qz633nf) | Oracle only | Active |\n| **Luna Identity** | [`terra1xm4...fykwslsmjuj`](https://finder.terra.money/classic/address/terra1xm49ghe04tzd0qgt9uelv9gklfrj7yf6v0faxaw9lc3dsujfykwslsmjuj) | Config only | Active |\n| **Proof-of-Burn** | [`terra188f...387uq0ch3d0`](https://finder.terra.money/classic/address/terra188fdkkvf54er3t6e9zgz6v24d7scykv3lqflpqr8xn063ff387uq0ch3d0) | Immutable | Active |\n| **Negative-Staking** | [`terra13kz...qlscqnegaws`](https://finder.terra.money/classic/address/terra13kz7rzdpad9hxdkzn4dln2kfcxy8c7pe0lcwfu8ue9n2dlqqlscqnegaws) | Config only | Active |\n| **Burn Calculator Pro** | [`terra19yr...633nf`](https://finder.terra.money/classic/address/terra19yr2f0akzjaerequfzm4aeecdplychkkq0pfwcetqqd8s5e6lk4qz633nf) | Immutable | Active |\n| **Stable Vault V2** | [`terra1klz...jrs5uq8p9rh0`](https://finder.terra.money/classic/address/terra1klz58628lk7pg3w6ah7erlpxaz4esxm8zsk02uunyy5gpdjrs5uq8p9rh0) | Pause only | Active |\n\n---\n\n## Ecosystem Overview\n\n### Stable Vault V2 — 1:1 USDC-Backed Stablecoin (lUSD)\n\nThe flagship contract. Deposit USDC, receive lUSD at a 1:1 ratio. The vault enforces a strict invariant: **supply always equals reserves**.\n\nWhat makes V2 special: it integrates with **Luna Identity** for fee discounts.\n\n| Identity Level | Fee | Discount |\n|---------------|-----|----------|\n| No Identity | 0.30% | — |\n| Level 1 | 0.20% | 10 bps |\n| Level 2 | 0.15% | 15 bps |\n| Level 3 | 0.10% | 20 bps |\n| Level 4 | 0.05% | 25 bps |\n| **Level 5+** | **FREE** | **30 bps** |\n\nAll collected fees are **permanently burned**.\n\n### Luna Identity — SoulBound Citizenship NFTs\n\nNon-transferable on-chain identity with a full wallet and DeFi suite. Burn LUNC to register, level up through contributions, unlock fee discounts in Stable Vault V2. Includes send/receive, DEX swap, TX history, and governance voting. Try it at [luid.fitlex.me](https://luid.fitlex.me).\n\n### Governance Voting — On-Chain Proposals\n\nIdentity holders can vote on ecosystem proposals. Voting power scales with your identity level — no token-weighted voting, purely reputation-based through proven LUNC burns.\n\n| Level | Title | Voting Power |\n|-------|-------|-------------|\n| 1-2 | Citizen/Resident | No voting rights |\n| 3 | Patriot | 1 vote |\n| 4 | Guardian | 2 votes |\n| 5+ | Senator+ | Votes = level |\n\nLevel 5+ (Senator) can also **create proposals**. Voting costs only gas (~0.5 LUNC), no additional burn required.\n\n### AI Burn Oracle — Market-Adaptive Burn Rate\n\nClaude AI analyzes market data every 8 hours and adjusts the LUNC burn rate on-chain. Fully transparent, all recommendations stored on-chain with reasoning.\n\n### Proof-of-Burn — Verifiable Burn Receipts\n\nEvery LUNC burn gets an immutable on-chain receipt. Composable with other contracts for access control.\n\n### Negative Staking — Deflationary Staking\n\nStake LUNC, 10% gets burned. You receive governance weight proportional to `amount × lock_time`. The longer you lock, the more influence you earn.\n\n### Burn Calculator Pro — On-Chain Compute\n\nCalculates optimal burn amounts based on current market conditions and AI Oracle data.\n\n---\n\n## Installation\n\n```bash\nnpm install lumos-luna-sdk\n```\n\n---\n\n## Quick Start\n\n### Read-Only (No Wallet Required)\n\n```typescript\nimport { LumosPrimitives } from 'lumos-luna-sdk';\n\nconst lumos = new LumosPrimitives();\n\n// Get burn statistics\nconst burnStats = await lumos.proofOfBurn.getStats();\nconsole.log('Total burned:', burnStats.data.total_burned);\n\n// Get staking statistics\nconst stakingStats = await lumos.staking.getStats();\nconsole.log('Total staked:', stakingStats.total_staked);\n\n// Verify vault invariant (supply == reserves)\nconst invariant = await lumos.vault.verifyInvariant();\nconsole.log('Invariant holds:', invariant.holds); // Always true\n```\n\n### With Wallet (Write Operations)\n\n```typescript\nimport { LumosPrimitives } from 'lumos-luna-sdk';\nimport { DirectSecp256k1HdWallet } from '@cosmjs/proto-signing';\nimport { SigningCosmWasmClient } from '@cosmjs/cosmwasm-stargate';\n\nconst lumos = new LumosPrimitives();\n\n// Connect wallet\nconst wallet = await DirectSecp256k1HdWallet.fromMnemonic(process.env.MNEMONIC, {\n prefix: 'terra'\n});\nconst [account] = await wallet.getAccounts();\nconst client = await SigningCosmWasmClient.connectWithSigner(\n 'https://terra-classic-rpc.publicnode.com',\n wallet\n);\n\nlumos.connect(client, account.address);\n\n// Burn LUNC and get proof\nconst proof = await lumos.proofOfBurn.burn('1000000'); // 1 LUNC\nconsole.log('Burn proof:', proof.txHash);\n\n// Stake with negative yield\nconst stake = await lumos.staking.stake('10000000', 30); // 10 LUNC, 30 days\nconsole.log('Staked:', stake.txHash);\n```\n\n---\n\n## The Three Primitives\n\n### 1. Proof-of-Burn Registry\n\nBurn LUNC and receive a non-transferable on-chain proof.\n\n**Invariant:** `proof.burned_amount == actual_burned`\n\n```typescript\n// Burn and get proof\nconst result = await lumos.proofOfBurn.burn('1000000');\n\n// Get your proofs\nconst proofs = await lumos.proofOfBurn.getProofsByBurner('terra1...');\n\n// Get global stats\nconst stats = await lumos.proofOfBurn.getStats();\n```\n\n**Use cases:**\n- Verifiable burn history\n- Access control based on burn amount\n- Composable with other contracts\n\n### 2. Negative-Yield Staking\n\nStaking that costs LUNC. Part of your stake is burned.\n\n**Invariant:** `stake_weight = amount * time_locked`\n\n**Config:** `burn_ratio = 10%` (configurable by admin)\n\n```typescript\n// Stake 10 LUNC for 30 days (10% burned = 1 LUNC)\nconst result = await lumos.staking.stake('10000000', 30);\n\n// Check your stake\nconst info = await lumos.staking.getStakeInfo('terra1...');\n\n// Unstake after lock period\nconst unstake = await lumos.staking.unstake('9000000');\n\n// Get leaderboard\nconst leaders = await lumos.staking.getLeaderboard(10);\n```\n\n**What you get:**\n- Governance weight (stake_weight)\n- Priority access\n- Proof of commitment\n\n### 3. Invariant-Only Stable Vault\n\n1:1 USDC-collateralized stablecoin. No algorithm, no governance.\n\n**Invariant:** `total_supply(lUSD) == balance(USDC_vault)` - **ALWAYS**\n\n```typescript\n// Deposit USDC, get lUSD (1:1)\nconst mint = await lumos.vault.mint('1000000'); // 1 USDC = 1 lUSD\n\n// Burn lUSD, get USDC back (1:1)\nconst burn = await lumos.vault.burn('1000000'); // 1 lUSD = 1 USDC\n\n// Verify invariant\nconst check = await lumos.vault.verifyInvariant();\nconsole.log('Supply:', check.supply);\nconsole.log('Reserves:', check.reserves);\nconsole.log('Holds:', check.holds); // Always true\n```\n\n**Guarantees:**\n- No algorithmic peg\n- No LUNC collateral\n- Mathematical enforcement, not market mechanisms\n\n---\n\n## AI Oracle (Optional)\n\nAn AI-powered service that analyzes market data and suggests optimal burn rates.\n\n**Features:**\n- Real-time price data from CoinGecko\n- Sentiment analysis\n- AI-enhanced recommendations (OpenRouter/OpenAI)\n- Automatic contract updates\n\n**Run locally:**\n\n```bash\ncd services/ai-oracle\nnpm install\nOPENROUTER_API_KEY=sk-or-... npm run run-once\n```\n\n**With wallet (submits to contract):**\n\n```bash\nMNEMONIC=\"your 24 words\" OPENROUTER_API_KEY=sk-or-... npm run run-once\n```\n\n---\n\n## API Reference\n\n### LumosPrimitives\n\n```typescript\nconst lumos = new LumosPrimitives(config?: {\n lcd?: string; // Default: mainnet LCD\n contracts?: {\n proofOfBurn?: string; // Override contract address\n negativeStaking?: string;\n stableVault?: string;\n };\n});\n```\n\n### Proof of Burn\n\n| Method | Description |\n|--------|-------------|\n| `burn(amount)` | Burn LUNC, get proof |\n| `getStats()` | Total burned, proof count |\n| `getProof(id)` | Get specific proof |\n| `getProofsByBurner(address)` | Get all proofs for address |\n\n### Negative Staking\n\n| Method | Description |\n|--------|-------------|\n| `stake(amount, lockDays)` | Stake LUNC (part burned) |\n| `unstake(amount)` | Unstake after lock period |\n| `getStats()` | Total staked, total burned |\n| `getStakeInfo(address)` | Get stake info for address |\n| `getLeaderboard(limit)` | Top stakers by weight |\n\n### Stable Vault\n\n| Method | Description |\n|--------|-------------|\n| `mint(usdcAmount)` | Deposit USDC, get lUSD |\n| `burn(lusdAmount)` | Burn lUSD, get USDC |\n| `getState()` | Total supply, reserves |\n| `verifyInvariant()` | Check supply == reserves |\n| `isFullyBacked()` | Returns true (always) |\n\n---\n\n## Environment Variables\n\nCreate a `.env` file:\n\n```bash\n# Wallet (for write operations)\nMNEMONIC=\"your 24 word mnemonic phrase\"\n\n# AI Provider (for AI Oracle)\nOPENROUTER_API_KEY=\"sk-or-...\"\n# or\nOPENAI_API_KEY=\"sk-...\"\n```\n\n---\n\n## Legacy SDK Features\n\nThe SDK also includes the original LunaSDK for general Terra operations:\n\n```typescript\nimport { LunaSDK } from 'lumos-luna-sdk';\n\nconst sdk = new LunaSDK({\n chain: 'lunc',\n mnemonic: process.env.MNEMONIC\n});\n\n// Standard operations\nawait sdk.getBalance();\nawait sdk.send('terra1...', '1000000');\nawait sdk.burn('1000000');\n\n// AI features (with API key)\nawait sdk.ai.complete('What is LUNC?');\nawait sdk.ai.generateImage('Terra phoenix');\n\n// NFT minting\nawait sdk.nft.mintGenerative({ prompt: '...' });\n```\n\nSee `/examples` folder for complete usage examples.\n\n---\n\n## Project Structure\n\n```\n/apps\n /luna-identity # Next.js PWA — luid.fitlex.me\n /src/components # SendModal, ReceiveModal, SwapPanel, StableVault, Governance, ...\n /src/lib # secure-wallet.ts, api.ts, store.ts, constants.ts\n /burnfeed # Burn feed viewer\n\n/contracts # Rust CosmWasm smart contracts (Cargo workspace)\n /proof-of-burn # Verifiable burn receipts\n /negative-staking # Deflationary staking (10% burn)\n /stable-vault # V1 — 1:1 USDC vault\n /stable-vault-v2 # V2 — with Identity integration & fee burning\n /luna-identity # SoulBound citizenship NFTs\n /burn-calculator-pro # On-chain burn rate calculator\n /burn-rate-calculator\n /burn-calculator\n /terra-recovery\n\n/public-site # Marketing site — lunar.fitlex.me\n\n/src\n /primitives # SDK wrappers for contracts\n /identity # Identity client\n\n/services\n /ai-oracle # AI burn rate recommender (Claude AI, every 8h)\n```\n\n---\n\n## Building\n\n```bash\n# Build SDK\nnpm run build\n\n# Run tests\nnpm test\n\n# Build contracts (requires Rust)\ncd contracts/proof-of-burn\ncargo build --release --target wasm32-unknown-unknown\n```\n\n---\n\n## Contributing\n\n1. Fork the repository\n2. Create feature branch (`git checkout -b feature/xyz`)\n3. Commit changes (`git commit -m 'Add xyz'`)\n4. Push branch (`git push origin feature/xyz`)\n5. Open Pull Request\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for details.\n\n---\n\n## License\n\nMIT License - see [LICENSE](LICENSE)\n\n---\n\n\n Built by Schero94 for Terra Classic\n
\n","readmeFilename":"README.md"}