
# Getting Started with Lumen Network

Welcome to Lumen Network! This guide will help you get started with the SDK and basic on-chain interactions.

## What is Lumen?

Lumen is a Cosmos SDK-based blockchain with:

- `chain_id`: `lumen`
- Bech32 prefix: `lmn` (addresses look like `lmn1...`)
- Base denom: `ulmn` (1 LMN = 1,000,000 ulmn)

## Quick Start

### Prerequisites

Before you begin, ensure you have the following installed:

- Node.js v18 or higher
- Git
- A code editor (VS Code recommended)

### Installation

Install the Lumen SDK using npm:

```bash
npm install @lumen-chain/sdk
```

Or using yarn:

```bash
yarn add @lumen-chain/sdk
```

### Read-Only Query

By default, the SDK targets a local node (`127.0.0.1`). You can override endpoints if you need to connect to a remote node.

```javascript
import { LumenClient, LUMEN } from '@lumen-chain/sdk';

const client = await LumenClient.connect(); // defaults to local endpoints + chainId "lumen"

console.log('Chain ID:', LUMEN.chainId);
console.log('Height:', await client.getHeight());
```

### Your First Transaction (Signing)

The SDK exposes a signing client compatible with CosmJS. For a simple bank send, you must pass an explicit zero-fee (Lumen expects 0 fees).

```typescript
import { LumenSigningClient, LUMEN, utils } from '@lumen-chain/sdk';

const signer = await utils.walletFromMnemonic(process.env.MNEMONIC!, LUMEN.bech32Prefix);
const [account] = await signer.getAccounts();

const signing = await LumenSigningClient.connectWithSigner(signer);

const msg = utils.msg.bankSend(
  account.address,
  'lmn1recipientaddresshere...',
  [utils.coin.ulmn('1000000')], // 1 LMN
);

const res = await signing.signAndBroadcast(account.address, [msg], utils.gas.zeroFee(), 'Hello Lumen');
console.log('TX hash:', res.transactionHash);
```

## Next Steps

- [Explore the SDK Documentation](/docs/sdk)
- [Learn about Validators](/docs/validators)
- [Check out Code Examples](/docs/examples)
- [Join the Community](/community)

## Need Help?

If you run into any issues:

- Join our [Discord](https://discord.gg/DwK6V9shKc)
- Ask questions on [Telegram](https://t.me/+HBWh_cUJCrZiODE0)
- Open an issue on [GitHub](https://github.com/network-lumen/)


Getting Started


# Code & Repositories

Primary sources & tooling for the Lumen ecosystem.

## Core Repositories

### Blockchain Core

The main blockchain implementation (Cosmos SDK-based).

- Repository: https://github.com/network-lumen/blockchain
- Docs: https://github.com/network-lumen/blockchain/tree/master/docs

### Validator Kit

Operational scripts and guides for validators.

- Repository: https://github.com/network-lumen/validator-kit
- Ops docs: https://github.com/network-lumen/validator-kit/tree/master/ops

### Gateway Agent

Runtime agent for gateway nodes (exposes gateway capabilities over HTTP).

- Repository: https://github.com/network-lumen/gateway-agent

### Integrations

Application-level integrations and examples (includes the JS/TS SDK source).

- Repository: https://github.com/network-lumen/integrations
- SDK source: https://github.com/network-lumen/integrations/tree/master/npm/sdk

## SDK & Tools

### JavaScript/TypeScript SDK

- NPM package: https://www.npmjs.com/package/@lumen-chain/sdk
- Source: https://github.com/network-lumen/integrations/tree/master/npm/sdk

```bash
npm install @lumen-chain/sdk
```

## Contributing

See the blockchain contributing guide for repo conventions: https://github.com/network-lumen/blockchain/blob/master/CONTRIBUTING.md

## License

All Lumen repositories are open source under the MIT license.


Code Repositories


# Technical Overview

High-level diagrams & pointers for understanding how Lumen fits together. For exact, source-of-truth details, see the `blockchain/docs` folder.

## Project Architecture

A comprehensive overview of the Lumen blockchain architecture.

![Architecture Diagram](/docs/architecture_overview.png)

## Token Emission

Understanding tokenomics and the emission schedule.

![Token Emission](/docs/tokenemission_overview.png)

## DAO-Governed Parameters

Parameters that can be adjusted through governance proposals.

![Governed Parameters](/docs/governedparameters_overview.png)

## Voting Power Overview

How voting power is calculated and distributed.

![Voting Power](/docs/votingpower_overview.png)

Conceptually:

```
Voting Power = Validator Self-Stake + Delegated Stake
```

## Network Parameters (Where to Look)

Lumen’s “network constants” are defined by configuration and genesis, not marketing numbers.

- Block time: configured by Tendermint `timeout_commit` in `~/.lumen/config/config.toml` (the tokenomics docs assume ~4-second blocks).
- Block max bytes: in genesis under `consensus.params.block.max_bytes` (mainnet genesis currently uses `22,020,096` bytes).
- Evidence max bytes: in genesis under `consensus.params.evidence.max_bytes` (mainnet genesis uses `1,048,576` bytes).
- Gas/fees: Lumen is a zero-fee chain (no gas price market). Genesis sets `consensus.params.block.max_gas = -1`.

## Cryptographic Algorithms

- Consensus keys: Ed25519 (Tendermint)
- Account/tx signatures: Secp256k1 (Cosmos-style EOAs) + required Dilithium3 PQC extension for outbound transactions
- PQC policy: required at genesis (`PQC_POLICY_REQUIRED`, `min_scheme=dilithium3`)
- PQC key linking requires a minimum balance of `1000 ulmn` (you can receive funds without a linked key; signing/broadcasting requires PQC)
- Hashing: SHA-256
- Key derivation: BIP39/BIP44

## Further Reading

- Blockchain docs: https://github.com/network-lumen/blockchain/tree/master/docs
- Cosmos SDK: https://docs.cosmos.network/


High-level architecture and technical diagrams

Technical Overview


# Validator Documentation

This page focuses on the pieces that are Lumen-specific (chain id, denom, genesis source, and fee rules). For deeper ops tooling and scripts, use the Validator Kit. For the most complete reference, see the blockchain docs.

- Blockchain validator guide: https://github.com/network-lumen/blockchain/blob/master/docs/validators.md

## Quick Facts

- Chain id: `lumen`
- Bech32 prefix: `lmn`
- Base denom: `ulmn` (1 LMN = 1,000,000 ulmn)
- Gasless chain: tx fee must be exactly `0` (use `--fees="0ulmn"` when submitting tx)

## Prerequisites

- Hardware: 4+ CPU, 16GB+ RAM, SSD storage, stable network
- Linux admin basics (systemd, firewall, logs)
- Minimum stake: `1 LMN` (`1,000,000 ulmn`) is typically ~`1` voting power (Cosmos default power reduction)

## Setup

### 1) Install and build `lumend`

```bash
sudo apt update && sudo apt upgrade -y
sudo apt install build-essential git curl -y

git clone https://github.com/network-lumen/blockchain
cd blockchain
make install

lumend version
```

### 2) Init with the correct chain id

```bash
MONIKER="your-validator-name"
lumend init "$MONIKER" --chain-id lumen
```

### 3) Install genesis (source of truth)

```bash
curl -L https://raw.githubusercontent.com/network-lumen/validator-kit/master/config/genesis.json > ~/.lumen/config/genesis.json
```

### 4) Configure gasless settings

Lumen nodes should run with `--minimum-gas-prices 0ulmn` (non-zero values are rejected).

Edit `~/.lumen/config/app.toml`:

```toml
minimum-gas-prices = ""
```

Important: transactions must still set a zero fee (example: `--fees="0ulmn"`).

### 5) Run as a systemd service

```bash
sudo tee /etc/systemd/system/lumend.service > /dev/null <<EOF
[Unit]
Description=Lumen Node
After=network.target

[Service]
User=$USER
ExecStart=$(which lumend) start --minimum-gas-prices 0ulmn
Restart=on-failure
RestartSec=3
LimitNOFILE=4096

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl enable lumend
sudo systemctl start lumend
sudo journalctl -u lumend -f
```

## Create a validator

Once synced:

```bash
lumend tx staking create-validator \
  --amount=1000000ulmn \
  --pubkey=$(lumend tendermint show-validator) \
  --moniker="$MONIKER" \
  --chain-id=lumen \
  --fees="0ulmn" \
  --from=<your-key-name>
```

## Delegation / Undelegation

```bash
lumend tx staking delegate <validator-address> 1000000ulmn \
  --from=<your-key-name> \
  --chain-id=lumen \
  --fees="0ulmn"
```

```bash
lumend tx staking unbond <validator-address> 1000000ulmn \
  --from=<your-key-name> \
  --chain-id=lumen \
  --fees="0ulmn"
```

## Troubleshooting

### Validator jailed

```bash
lumend tx slashing unjail \
  --from=<your-key-name> \
  --chain-id=lumen \
  --fees="0ulmn"
```

## Resources

- Validator Kit: https://github.com/network-lumen/validator-kit
- Blockchain: https://github.com/network-lumen/blockchain

## Validator Kit docs:

- How to become a validator: https://github.com/network-lumen/validator-kit/blob/master/ops/become_validator.md
- Stake bootstrap & decentralization: https://github.com/network-lumen/validator-kit/blob/master/ops/stake_bootstrap.md
- Validator & sentry specifications: https://github.com/network-lumen/validator-kit/blob/master/ops/validator_specs.md
- Learn folder: https://github.com/network-lumen/validator-kit/tree/master/learn


Complete guide to running a Lumen validator

Validator Guide


# Lumen SDK

Official JavaScript/TypeScript SDK for interacting with the Lumen chain (Cosmos SDK + Lumen modules).

This page is aligned with the real SDK source at `integrations/npm/sdk` (package `@lumen-chain/sdk`).

## Installation

```bash
npm install @lumen-chain/sdk
```

Or with yarn:

```bash
yarn add @lumen-chain/sdk
```

## Quick Start

### Read-only client (RPC + REST)

```typescript
import { LumenClient, LUMEN } from '@lumen-chain/sdk';

// Defaults target a local node (see LUMEN.defaultRpc/defaultRest).
const endpoints = { rpc: LUMEN.defaultRpc, rest: LUMEN.defaultRest };
const client = await LumenClient.connect(endpoints, LUMEN.chainId);

console.log('height', await client.getHeight());
console.log('dns resolve', await client.dns().resolve('demo', 'lmn'));
```

### Signing client (OfflineSigner + PQC)

```typescript
import { LumenSigningClient, utils } from '@lumen-chain/sdk';

const signer = await utils.walletFromMnemonic(process.env.MNEMONIC!, 'lmn');
const [account] = await signer.getAccounts();

const signing = await LumenSigningClient.connectWithSigner(signer, endpoints, LUMEN.chainId);

// DNS is a gasless module tx: you can pass utils.gas.zeroFee(), or let the client auto-detect it.
const msg = signing.dns().msgRegister(account.address, { domain: 'demo', ext: 'lmn', durationDays: 30 });
const res = await signing.signAndBroadcast(account.address, [msg], utils.gas.zeroFee());
console.log('tx hash', res.transactionHash);
```

## Addresses, chain id, endpoints

- **bech32 prefix**: `lmn` (addresses look like `lmn1...`).
- **chain id**: `lumen` by default (`LUMEN.chainId`).
- **default local endpoints**:
  - RPC: `http://127.0.0.1:27657`
  - REST: `http://127.0.0.1:2327`
  - gRPC: `http://127.0.0.1:9190`

> You can override endpoints to point at a remote node/gateway. Some older nodes still expose 26657/1317; the SDK supports both.

## Common patterns

### Query balance

```typescript
const bal = await client.getBalance('lmn1...');
console.log(bal);
```

### Send tokens (bank MsgSend)

The SDK does not wrap bank sends into a `sendTokens()` helper. Use `utils.msg.bankSend`:

```typescript
import { LumenSigningClient, utils } from '@lumen-chain/sdk';

const signer = await utils.walletFromMnemonic(process.env.MNEMONIC!, 'lmn');
const [account] = await signer.getAccounts();
const signing = await LumenSigningClient.connectWithSigner(signer);

const msg = utils.msg.bankSend(
  account.address,
  'lmn1recipient...',
  [utils.coin.ulmn('1000000')], // 1 LMN
);

// Bank txs are not in the "gaslessTypeUrls" allowlist, so either pass an explicit zero fee,
// or provide a GasPrice=0 and let the client estimate gas.
const res = await signing.signAndBroadcast(account.address, [msg], utils.gas.zeroFee());
console.log(res.transactionHash);
```

### DNS queries + tx composers

```typescript
// Queries (REST)
const resolved = await client.dns().resolve('demo', 'lmn');
const domains = await client.dns().domainsByOwner('lmn1...');

// Tx composers (EncodeObject)
const msgRegister = client.dns().msgRegister('lmn1...', { domain: 'demo', ext: 'lmn', durationDays: 30 });
```

## PQC (Dilithium)

Lumen can require Dilithium signatures for EOAs. The SDK can manage a local PQC keystore (`~/.lumen/pqc_keys`) and add
the `lumen.pqc.v1.PQCSignatures` extension during `signAndBroadcast`.

```ts
import { pqc } from '@lumen-chain/sdk';

const { publicKey, privateKey } = pqc.createKeyPair(); // Dilithium3
const store = await pqc.PqcKeyStore.open();            // defaults to ~/.lumen/pqc_keys
await store.saveKey({ name: 'my-key', scheme: 'dilithium3', publicKey, privateKey, createdAt: new Date() });
await store.linkAddress('lmn1...', 'my-key');
```

## Resources

- [NPM Package](https://www.npmjs.com/package/@lumen-chain/sdk)
- [SDK Source (integrations)](https://github.com/network-lumen/integrations/tree/master/npm/sdk)
- [Examples](/docs/examples)


SDK Documentation


# Code Examples

Examples below are aligned with the real SDK API in `integrations/npm/sdk` (`@lumen-chain/sdk`).

## Connect (Read-Only) + Height

```ts
import { LumenClient } from '@lumen-chain/sdk';

const client = await LumenClient.connect(); // defaults to local endpoints + chainId "lumen"
console.log('Height:', await client.getHeight());
```

## Balance (RPC)

```ts
import { LumenClient, utils } from '@lumen-chain/sdk';

const client = await LumenClient.connect();
const balance = await client.getBalance('lmn1address...', 'ulmn');
console.log('Balance:', balance ?? utils.coin.ulmn('0'));
```

## New Block Callback (Polling)

```ts
import { LumenClient } from '@lumen-chain/sdk';

const client = await LumenClient.connect();
const stop = client.onNewBlock((height) => console.log('new height', height), 1_000);

// later:
// stop();
```

## DNS Resolve (REST)

```ts
import { LumenClient } from '@lumen-chain/sdk';

const client = await LumenClient.connect();
const res = await client.dns().resolve('demo', 'lmn'); // demo.lmn
console.log(res);
```

## Gateways: List Gateways / Contracts (REST)

```ts
import { LumenClient } from '@lumen-chain/sdk';

const client = await LumenClient.connect();
console.log(await client.gateways().gateways({ limit: 10 }));
console.log(await client.gateways().contracts({ limit: 10 }));
```

## Bank Send (Signing)

This is a plain Cosmos bank send. On Lumen, pass an explicit zero-fee.

```ts
import { LumenSigningClient, LUMEN, utils } from '@lumen-chain/sdk';

const signer = await utils.walletFromMnemonic(process.env.MNEMONIC!, LUMEN.bech32Prefix);
const [account] = await signer.getAccounts();

const signing = await LumenSigningClient.connectWithSigner(signer);

const msg = utils.msg.bankSend(
  account.address,
  'lmn1recipient...',
  [utils.coin.ulmn('1000000')], // 1 LMN
);

const res = await signing.signAndBroadcast(account.address, [msg], utils.gas.zeroFee(), 'hello');
console.log(res.transactionHash);
```

## DNS Register (Signing)

DNS messages are gasless in the SDK (it will automatically use a zero fee).

```ts
import { LumenSigningClient, LUMEN, utils } from '@lumen-chain/sdk';

const signer = await utils.walletFromMnemonic(process.env.MNEMONIC!, LUMEN.bech32Prefix);
const [account] = await signer.getAccounts();

const signing = await LumenSigningClient.connectWithSigner(signer);

const msg = signing.dns().msgRegister(account.address, {
  domain: 'mydomain',
  ext: 'lmn',
  durationDays: 365,
  records: [],
});

const res = await signing.signAndBroadcast(account.address, [msg]);
console.log(res.transactionHash);
```

## More

- [SDK Documentation](/docs/sdk)
- [Integrations Repo](https://github.com/network-lumen/integrations)


LUMEN NETWORK

DocumentationCenter

Quick Start

Quick Start

Technical

Validators

Getting Started(1)

Getting Started

Resources(2)

Code Repositories

Technical Overview

Validators(1)

Validator Guide

Developers(2)

SDK Documentation

Code Examples

Need Help?

Discord

GitHub

Official Site