XION Blockchain Backend POC

A Node.js backend proof-of-concept for interacting with the XION blockchain network. This project provides a comprehensive set of utilities for wallet management, blockchain queries, and transaction execution on the XION testnet.

Features

🔗 Blockchain Connection

• Connect to XION testnet RPC endpoints
• Support for both query-only and signing clients
• CosmWasm smart contract integration

💼 Wallet Management

• Generate new wallets with mnemonics
• Import wallets from existing mnemonics
• Address derivation and management
• Multi-wallet support

🔍 Blockchain Queries

• Account balance checking
• Transaction lookup by hash
• Block data retrieval
• Smart contract state queries
• Chain height monitoring

💸 Transaction Operations

• Token transfers between addresses
• Smart contract execution
• Contract deployment (upload & instantiate)
• Gas fee estimation and management

Prerequisites

• Node.js (v14 or higher)
• npm or yarn
• XION testnet tokens for transactions

Installation

1. Clone the repository:

git clone <repository-url>
cd poc-backend-blockchain

2. Install dependencies:

npm install

3. Create a .env file in the root directory:

XION_MNEMONIC="your 24-word mnemonic phrase here"
XION_RPC_URL="https://rpc.xion-testnet-2.burnt.com"
XION_CHAIN_ID="xion-testnet-2"

Project Structure

├── config.js              # Configuration and environment variables
├── xion-connect.js         # Blockchain connection utilities
├── xion-wallets.js         # Wallet management functions
├── xion-queries.js         # Blockchain query operations
├── xion-transactions.js    # Transaction execution functions
├── examples.js             # Usage examples and demonstrations
└── package.json           # Project dependencies

Usage

Basic Setup

const { getMyAddress } = require('./xion-wallets');
const { getBalance } = require('./xion-queries');
const { sendTokens } = require('./xion-transactions');

// Get your wallet address
const address = await getMyAddress();
console.log('My address:', address);

// Check balance
const balance = await getBalance(address);
console.log('Balance:', balance, 'uxion');

Wallet Operations

const { generateWallet, getAddressFromMnemonic } = require('./xion-wallets');

// Generate a new wallet
const newWallet = await generateWallet();
console.log('New wallet:', newWallet.address);
console.log('Mnemonic:', newWallet.mnemonic);

// Get address from existing mnemonic
const address = await getAddressFromMnemonic('your mnemonic here');

Blockchain Queries

const { getTransaction, getBlock, getChainHeight } = require('./xion-queries');

// Get transaction details
const tx = await getTransaction('transaction_hash_here');

// Get latest block
const latestBlock = await getBlock();

// Get current chain height
const height = await getChainHeight();

Token Transfers

const { sendTokens } = require('./xion-transactions');

// Send tokens
const result = await sendTokens(
    'recipient_address_here',
    '1000',           // amount in uxion
    'uxion',          // denomination
    'Transfer memo'   // optional memo
);

console.log('Transaction hash:', result.transactionHash);

Smart Contract Interaction

const { executeContract, queryContract } = require('./xion-transactions');
const { queryContract } = require('./xion-queries');

// Execute contract function
const executeResult = await executeContract(
    'contract_address_here',
    { increment: {} },  // execute message
    []                  // optional funds
);

// Query contract state
const queryResult = await queryContract(
    'contract_address_here',
    { get_count: {} }   // query message
);

Running Examples

The project includes a comprehensive example file that demonstrates all features:

node examples.js

This will:

1. Connect to the XION blockchain
2. Display your wallet address and balance
3. Execute a smart contract function
4. Query contract state
5. Show transaction results

Configuration

The config.js file manages all configuration settings:

• XION_RPC_URL: RPC endpoint for blockchain connection
• CHAIN_ID: Network chain identifier
• MNEMONIC: Your wallet's recovery phrase

The configuration includes validation to ensure required environment variables are set.

Error Handling

All functions include proper error handling and will throw descriptive errors for:

• Missing configuration
• Network connection issues
• Invalid addresses or transaction parameters
• Insufficient funds
• Contract execution failures

Security Notes

⚠️ Important Security Considerations:

• Never commit your .env file or mnemonic to version control
• Use testnet tokens only for development
• Store production mnemonics securely
• Validate all user inputs before processing transactions

Dependencies

• @cosmjs/stargate: Cosmos SDK client library
• @cosmjs/cosmwasm-stargate: CosmWasm integration
• @cosmjs/proto-signing: Transaction signing utilities
• @cosmjs/encoding: Encoding/decoding utilities
• dotenv: Environment variable management

Network Information

• Testnet RPC: https://rpc.xion-testnet-2.burnt.com
• Chain ID: xion-testnet-2
• Address Prefix: xion
• Native Token: uxion

Contributing

This is a proof-of-concept project for learning XION blockchain development. Feel free to extend and modify the code for your specific use cases.

License

ISC License - see package.json for details.