xpi-ts

TypeScript SDK for Lotus (XPI) wallets and other applications

A comprehensive TypeScript library providing Bitcoin-like transaction primitives, advanced cryptographic protocols, and RANK protocol support for the Lotus (XPI) blockchain ecosystem.

Features

Cryptography & Signatures

Bitcore Modules - Complete Bitcoin-like transaction primitives adapted for Lotus
- Private/public key management
- HD wallets (BIP32/BIP39)
- Transaction building and signing
- Address generation (P2PKH, P2SH, Taproot)
- Script interpreter
MuSig2 - Multi-signature Schnorr signatures (BIP327)
- 2-round non-interactive signing
- Privacy-preserving multisig (indistinguishable from single-sig)
Taproot - Pay-to-Taproot address support
- Script path spending
- Key path spending
- MuSig2 integration
- RANK protocol integration

RANK Protocol

Social Ranking System - On-chain reputation and content ranking
- Positive/negative/neutral sentiment tracking
- Multi-platform support (Twitter, Lotusia)
- Comment system (RNKC)
- Script builder and parser
- Fee-based spam prevention

Utilities

RPC Client - Full-featured lotusd RPC interface
- Network information
- Block and transaction queries
- Mining information
- Mempool management
Constants & Settings - Lotus-specific network parameters
- Network configurations
- Protocol constants
- Fee calculations
Encoding Utilities - Base58, Base58Check, Base32, Varint

Installation

# Install from npmjs registry
$ npm install xpi-ts

Requirements

Node.js >= 22
TypeScript >= 5.0 (for development)

Quick Start

Basic Transaction

import { Bitcore } from 'xpi-ts'
import { BIP44_COIN_TYPE } from 'xpi-ts/utils/constants'

// Generate mnemonic
const mnemonic = new Bitcore.Mnemonic()
const phrase = mnemonic.phrase

// Derive HD wallet
const hdKey = mnemonic.toHDPrivateKey('passphrase')
const childKey = hdKey.deriveChild(`m/44'/${BIP44_COIN_TYPE}'/0'/0/0`)

// Get private key and address
const privateKey = childKey.privateKey
const address = privateKey.toAddress()

console.log('Address:', address.toString())

// Build transaction
const tx = new Bitcore.Transaction()
  .from(unspentOutput)
  .to(recipientAddress, 100_000_000) // 100 XPI
  .change(changeAddress)
  .sign(privateKey)

console.log('Transaction:', tx.serialize())

HD Wallet (BIP32/BIP39)

import { Bitcore } from 'xpi-ts'
import { BIP44_COIN_TYPE } from 'xpi-ts/utils/constants'

// Generate mnemonic
const mnemonic = new Bitcore.Mnemonic()
const phrase = mnemonic.phrase

// Derive HD wallet
const hdKey = mnemonic.toHDPrivateKey('passphrase')
const childKey = hdKey.deriveChild(`m/44'/${BIP44_COIN_TYPE}'/0'/0/0`)

// Get private key and address
const privateKey = childKey.privateKey
const address = privateKey.toAddress()

console.log('First address:', address.toString())

// Or derive from existing mnemonic
const existingMnemonic = new Bitcore.Mnemonic(
  'your twelve word mnemonic phrase here',
)
const restoredHdKey = existingMnemonic.toHDPrivateKey()

MuSig2 Multi-Signature

import { Bitcore } from 'xpi-ts'

// Create MuSig2 signer
const signer = new Bitcore.MuSig2Signer({
  signers: [alicePubKey, bobPubKey],
  myPrivateKey: alicePrivKey,
})

// Round 1: Generate nonces
const prepare = signer.prepare(message)
// Share prepare.myPublicNonces with other signers

// Round 2: Collect partial signatures
const myPartialSig = signer.createPartialSignature(
  prepare,
  allPublicNonces,
  message,
)
// Collect partial signatures from other signers

// Aggregate final signature
const result = signer.sign(prepare, allPublicNonces, message, allPartialSigs)

RANK Social Ranking

import { Bitcore, RANK } from 'xpi-ts'

// Create RANK script
const rankScript = RANK.toScriptRANK(
  'positive', // sentiment
  'twitter', // platform
  '@username', // profileId
  '1234567890', // postId (optional)
)

// Create RNKC script (comment) - returns array of buffers
const rnkcScripts = RANK.toScriptRNKC({
  platform: 'twitter',
  profileId: '@original_author',
  postId: '0987654321',
  comment: 'Great post!',
})

// Add to transaction
const tx = new Bitcore.Transaction()
  .from(utxo)
  .addOutput(
    new Bitcore.Output({
      script: rankScript,
      satoshis: 0,
    }),
  )
  // Add RNKC scripts (outIdx 1 and 2)
  .addOutput(
    new Bitcore.Output({
      script: rnkcScripts[0],
      satoshis: 0,
    }),
  )
  .addOutput(
    new Bitcore.Output({
      script: rnkcScripts[1] || Buffer.from('6a', 'hex'), // OP_RETURN if only one script needed
      satoshis: 0,
    }),
  )
  .to(address, amount)

Taproot Addresses

import { Bitcore } from 'xpi-ts'

// Create simple Taproot address (key-path only)
const privateKey = new Bitcore.PrivateKey()
const internalPubKey = privateKey.publicKey

const taprootScript = Bitcore.buildKeyPathTaproot(internalPubKey)
const taprootAddress = taprootScript.toAddress()

console.log('Taproot address:', taprootAddress?.toString())

// Taproot with script paths
const script1 = new Bitcore.Script()
  .add(internalPubKey.toBuffer())
  .add(Bitcore.Opcode.OP_CHECKSIG)

const script2 = new Bitcore.Script()
  .add(720) // ~1 day timelock (30 blocks per hour (2min average) * 24 hours per day)
  .add(Bitcore.Opcode.OP_CHECKSEQUENCEVERIFY)
  .add(Bitcore.Opcode.OP_DROP)
  .add(internalPubKey.toBuffer())
  .add(Bitcore.Opcode.OP_CHECKSIG)

// Build tree with script paths
const tree = {
  left: { script: script1 },
  right: { script: script2 },
}

const taprootWithScripts = Bitcore.buildScriptPathTaproot(internalPubKey, tree)
const addressWithScripts = taprootWithScripts.toAddress()

console.log('Taproot with scripts:', addressWithScripts?.toString())

RPC Client

import { Bitcore } from 'xpi-ts'
import { type RPCConfig, RPCClient } from 'xpi-ts/lib/rpc'

// Configure daemon connection
const config: RPCConfig = {
  user: 'rpcuser',
  password: 'rpcpass',
  address: '127.0.0.1',
  port: 10604,
}

const rpcClient = new RPCClient(config)

// Get blockchain info
const blockCount = await rpcClient.getBlockCount()
const blockHash = await rpcClient.getBlockHash(blockCount)
const block = await rpcClient.getBlock(blockHash)

// Get transaction info
const tx = await rpcClient.getRawTransaction(txid)

// Send raw transaction
const txid = await rpcClient.sendRawTransaction(tx.serialize())
console.log('Transaction ID:', txid)

Core Modules

Bitcore

Bitcoin-like transaction primitives adapted for Lotus XPI:

Transaction building - Inputs, outputs, signing
Script system - P2PKH, P2SH, P2TR, custom scripts
Cryptography - ECDSA, Schnorr signatures
Addresses - P2PKH, P2SH, P2TR (X-addresses)
HD Wallets - BIP32 derivation, BIP39 mnemonics
Encoding - Base58, Base58Check, Varint

import * as Bitcore from 'xpi-ts/lib/bitcore'
// or
import { PrivateKey, Transaction, Address } from 'xpi-ts'

MuSig2

Multi-signature Schnorr signatures:

2-round signing - Non-interactive nonce exchange
Security - Replay protection, nonce aggregation
Privacy - Indistinguishable from single signatures

import { MuSig2Session, MuSig2Signer } from 'xpi-ts/lib/bitcore/musig2'

RANK Protocol

On-chain social ranking and reputation system:

Sentiment tracking - Positive/negative/neutral
Multi-platform - Twitter, Lotusia
Comments - RNKC protocol
Spam prevention - Fee-based filtering

import { toScriptRANK, toScriptRNKC, ScriptProcessor } from 'xpi-ts/lib/rank'

Taproot

Pay-to-Taproot support with script paths:

Key path spending - Standard Taproot addresses
Script path spending - MAST-like script trees
MuSig2 integration - Multi-sig via Taproot
RANK integration - RANK protocol via Taproot

import { Taproot } from 'xpi-ts/lib/bitcore/taproot'

RPC Client

Full-featured RPC client for lotusd:

Network queries - Get network info, peers, blocks
Transaction handling - Send raw transactions, query mempool
Mining info - Get block height, difficulty, hash rate
Type-safe - Full TypeScript support

import { type RPCConfig, RPCClient } from 'xpi-ts/lib/rpc'

Examples

The library includes comprehensive examples in the examples/ directory:

Taproot Examples

taproot-example.ts - Basic Taproot usage
taproot-rank-multisig.ts - RANK protocol with multisig
taproot-rank-timelock.ts - Timelock scripts
taproot-rnkc-moderation.ts - Moderation scripts

MuSig2 Examples

musig2-example.ts - Basic 2-of-2 signing
musig2-session-example.ts - Session management
musig2-browser-compatibility.ts - Browser usage

NFT Examples

nft-class-example.ts - NFT class usage
nft-examples.ts - NFT creation and transfer

Running Examples

# Basic example
npx tsx examples/taproot-example.ts

# MuSig2 signing
npx tsx examples/musig2-example.ts

# RANK protocol
npx tsx examples/rank-example.ts

Documentation

Comprehensive documentation is available in the docs/ directory:

Getting Started

MuSig2 Start Here - Introduction to MuSig2
MuSig2 Quick Reference - Quick reference guide
Taproot Quickstart - Taproot introduction

Testing

# Run all tests
npm test

# Run specific test suite
npm test -- test/crypto/musig2/

# Run with coverage
npm run test:coverage

Development

Build

# Run full gulp build pipeline (clean + types + esm + cjs + export validation)
npm run build

# Run targeted pipeline stages
npm run build:clean
npm run build:types
npm run build:esm
npm run build:cjs
npm run build:validate

# Watch mode (rebuilds types + esm + cjs)
npm run build:watch

Linting & Formatting

# Format code
npm run format

# Lint code
npm run lint

Lotus Network Information

Lotus (XPI) is a Bitcoin-based cryptocurrency with several key differences:

Decimals: 6 (1 XPI = 1,000,000 satoshis) vs Bitcoin's 8
Supply: Inflationary with no hard cap
Consensus: Proof-of-Work (SHA-256d)
Features: OP_RETURN data, Taproot, RANK protocol

Network Resources:

Official Website: https://lotusia.org
Documentation: https://lotusia.org/docs
Block Explorer: https://explorer.lotusia.org
Full Node (lotusd): https://github.com/LotusiaStewardship/lotusd

Community

Discord: Lotusia
Telegram: Lotusia Discourse
GitHub: LotusiaStewardship

Contributing

Contributions are welcome! Please:

Read the relevant documentation thoroughly
Follow the existing code style (Prettier + ESLint)
Add tests for new features
Update documentation as needed
Submit a pull request

Development Setup

# Clone repository
git clone https://github.com/LotusiaStewardship/xpi-ts.git
cd xpi-ts

# Install dependencies
npm install

# Build library
npm run build

# Run tests
npm test

License

Related Projects

lotusd - Lotus full node implementation
https://github.com/LotusiaStewardship/lotusd
lotus-web-wallet - Lotus web wallet with full Taproot support
https://github.com/LotusiaStewardship/lotus-web-wallet

Built with ❤️ for the Lotus Ecosystem 🌸

Name		Name	Last commit message	Last commit date
Latest commit History 64 Commits
docs/plans/coinbase-parsing		docs/plans/coinbase-parsing
examples		examples
lib		lib
test		test
utils		utils
.gitignore		.gitignore
.npmignore		.npmignore
.prettierignore		.prettierignore
.prettierrc.json		.prettierrc.json
LICENSE		LICENSE
README.md		README.md
eslint.config.mjs		eslint.config.mjs
gulpfile.js		gulpfile.js
index.ts		index.ts
jest.config.js		jest.config.js
package-lock.json		package-lock.json
package.json		package.json
tsconfig.cjs.json		tsconfig.cjs.json
tsconfig.json		tsconfig.json
tsconfig.types.json		tsconfig.types.json

Folders and files

Latest commit

History

Repository files navigation

xpi-ts

Features

Cryptography & Signatures

RANK Protocol

Utilities

Installation

Requirements

Quick Start

Basic Transaction

HD Wallet (BIP32/BIP39)

MuSig2 Multi-Signature

RANK Social Ranking

Taproot Addresses

RPC Client

Core Modules

Bitcore

MuSig2

RANK Protocol

Taproot

RPC Client

Examples

Taproot Examples

MuSig2 Examples

NFT Examples

Running Examples

Documentation

Getting Started

Architecture & Implementation

Security

API References

Testing

Development

Build

Linting & Formatting

Lotus Network Information

Community

Contributing

Development Setup

License

Related Projects

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages