
# 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