# PureChainLib User Manual

Version 1.0.5

Complete Guide for Zero Gas Cost Blockchain Development

# 1 Getting Started

## 1.1 System Requirements

Before installing PureChainLib, ensure your system meets the following requirements:

Component | Minimum Version | Recommended Version
--- | --- | ---
Node.js | 16.0.0 | 18.0.0 or later
npm | 8.0.0 | 9.0.0 or later
Operating System | Windows 10, macOS 10.14, Ubuntu 18.04 | Latest stable versions
RAM | 4 GB | 8 GB or more
Disk Space | 500 MB | 1 GB or more

## 1.2 Installation

### Installing via npm

The recommended way to install PureChainLib is through npm:

    npm install purechainlib

For global installation (to use CLI tools):

    npm install -g purechainlib

### Installing from Source

To install from the source code:

    # Clone the repository
    git clone https://github.com/islarpee000/purechainlib.git

    # Navigate to the project directory
    cd purechainlib

    # Install dependencies
    npm install

    # Build the project
    npm run build

### Verifying Installation

Create a test file to verify the installation:

    // test-install.js
    const { PureChain } = require('purechainlib');

    console.log('PureChainLib installed successfully!');
    const purechain = new PureChain();
    console.log('PureChain instance created');

Run the test:

    node test-install.js

## 1.3 Initial Setup

### Project Structure

Create a new project directory and initialize it:

    mkdir my-purechain-project
    cd my-purechain-project
    npm init -y
    npm install purechainlib

### Basic Configuration File

Create a configuration file for your project:

    // config.js
    module.exports = {
      network: 'testnet', // or 'mainnet' when available
      apiPort: 3000,
      wsPort: 3001,
      dataDir: './blockchain-data',
      logLevel: 'info'
    };

### Environment Variables

Create a `.env` file for sensitive configuration:

    # .env
    NODE_ENV=development
    API_PORT=3000
    WS_PORT=3001
    DATA_DIR=./blockchain-data
    LOG_LEVEL=info

## 1.4 Understanding Zero Gas Cost

Key Concept: PureChain operates with ZERO gas costs. This revolutionary feature means all transactions, contract deployments, and interactions are completely free.

### What Zero Gas Cost Means

Operation | Traditional Blockchain | PureChain
--- | --- | ---
Simple Transfer | $0.50 - $5.00 | FREE ($0.00)
Token Contract Deployment | $50 - $500 | FREE ($0.00)
NFT Minting | $10 - $100 | FREE ($0.00)
Smart Contract Interaction | $1 - $20 | FREE ($0.00)

### Implementation in Code

When using PureChainLib, you don't need to:

- Check wallet balance for gas
- Calculate gas prices
- Set gas limits
- Worry about failed transactions due to insufficient gas

    // Traditional blockchain (NOT needed in PureChain)
    const gasPrice = await web3.eth.getGasPrice();
    const gasLimit = 21000;
    const totalCost = gasPrice * gasLimit;

    // PureChain - Simple and free!
    const result = await purechain.contractEngine.deployContract(config, deployer, 0);

# 2 Basic Operations

## 2.1 Connecting to PureChain

### Default Connection

The simplest way to connect to PureChain:

    const { PureChain } = require('purechainlib');

    async function connect() {
      // Creates instance with default testnet configuration
      const purechain = new PureChain();

      // Start the connection
      await purechain.start();

      console.log('Connected to:', purechain.networkConfig.name);
      console.log('Chain ID:', purechain.networkConfig.chainId);
      console.log('RPC URL:', purechain.networkConfig.rpcUrl);

      // Always stop when done
      await purechain.stop();
    }

    connect();

### Custom Configuration

Connect with specific configuration options:

    const { PureChain } = require('purechainlib');

    async function customConnect() {
      const purechain = new PureChain({
        networkConfig: 'testnet',
        blockchain: {
          difficulty: 2,
          miningReward: 100
        },
        api: {
          port: 3000,
          rateLimit: {
            windowMs: 15 * 60 * 1000,
            max: 100
          }
        },
        storage: {
          type: 'memory'
        }
      });

      await purechain.start();

      // Your blockchain operations

      await purechain.stop();
    }

    customConnect();

### Connection States

Monitor connection status:

    const purechain = new PureChain();

    // Before connection
    console.log('Provider:', purechain.provider); // null

    // Start connection
    await purechain.start();
    console.log('Provider connected:', purechain.provider !== null); // true

    // Check network details
    if (purechain.provider) {
      const blockNumber = await purechain.provider.getBlockNumber();
      console.log('Current block:', blockNumber);
    }

    // Disconnect
    await purechain.stop();
    console.log('Provider disconnected');

## 2.2 Creating Transactions

### Simple Transfer Transaction

    const { PureChain, Transaction, TransactionType } = require('purechainlib');

    async function createTransfer() {
      const purechain = new PureChain();
      await purechain.start();

      // Method 1: Using blockchain.createTransaction
      purechain.blockchain.createTransaction({
        from: 'alice',
        to: 'bob',
        amount: 100,
        timestamp: Date.now()
      });

      // Method 2: Using Transaction class
      const tx = new Transaction({
        from: 'alice',
        to: 'bob',
        amount: 100,
        type: TransactionType.TRANSFER,
        data: { message: 'Payment for services' }
      });

      // Transaction properties
      console.log('Transaction ID:', tx.id);
      console.log('From:', tx.from);
      console.log('To:', tx.to);
      console.log('Amount:', tx.amount);
      console.log('Fee:', tx.fee); // Always 0
      console.log('Timestamp:', new Date(tx.timestamp).toISOString());

      // Add to blockchain
      purechain.blockchain.addTransaction(tx);

      await purechain.stop();
    }

    createTransfer();

### Transaction Types

PureChain supports multiple transaction types:

Type | Purpose | Required Fields
--- | --- | ---
TRANSFER | Send funds between addresses | from, to, amount
CONTRACT_CREATION | Deploy new smart contract | from, data (contract code)
CONTRACT_CALL | Interact with smart contract | from, to (contract), data (method)
STAKE | Stake tokens for PoS | from, amount, data (duration)
UNSTAKE | Remove staked tokens | from, amount

### Batch Transactions

    async function batchTransactions() {
      const purechain = new PureChain();
      await purechain.start();

      // Create multiple transactions
      const transactions = [
        { from: 'alice', to: 'bob', amount: 50 },
        { from: 'alice', to: 'charlie', amount: 30 },
        { from: 'bob', to: 'david', amount: 20 },
        { from: 'charlie', to: 'eve', amount: 10 }
      ];

      // Add all transactions to pending pool
      transactions.forEach(tx => {
        purechain.blockchain.createTransaction({
          ...tx,
          timestamp: Date.now()
        });
      });

      console.log('Pending transactions:', purechain.blockchain.pendingTransactions.length);

      // Mine all transactions in one block
      await purechain.blockchain.minePendingTransactions('miner');

      console.log('All transactions processed!');
      console.log('Total gas cost: 0');

      await purechain.stop();
    }

    batchTransactions();

## 2.3 Mining Blocks

### Manual Mining

    async function mineBlocks() {
      const purechain = new PureChain();
      await purechain.start();

      // Add some transactions
      purechain.blockchain.createTransaction({
        from: 'alice',
        to: 'bob',
        amount: 100,
        timestamp: Date.now()
      });

      console.log('Before mining:');
      console.log('Pending transactions:', purechain.blockchain.pendingTransactions.length);
      console.log('Chain length:', purechain.blockchain.chain.length);

      // Mine the block
      const minerAddress = 'miner1';
      await purechain.blockchain.minePendingTransactions(minerAddress);

      console.log('\\nAfter mining:');
      console.log('Pending transactions:', purechain.blockchain.pendingTransactions.length);
      console.log('Chain length:', purechain.blockchain.chain.length);
      console.log('Miner reward:', purechain.blockchain.getBalance(minerAddress));

      // Get the latest block
      const latestBlock = purechain.blockchain.getLatestBlock();
      console.log('\\nLatest block:');
      console.log('Index:', latestBlock.index);
      console.log('Hash:', latestBlock.hash);
      console.log('Transactions:', latestBlock.transactions.length);
      console.log('Timestamp:', new Date(latestBlock.timestamp).toISOString());

      await purechain.stop();
    }

    mineBlocks();

### Automatic Mining

    async function autoMining() {
      const purechain = new PureChain();
      await purechain.start();

      let blocksMined = 0;
      const minerAddress = 'autoMiner';

      // Set up automatic mining every 10 seconds
      const miningInterval = setInterval(async () => {
        if (purechain.blockchain.pendingTransactions.length > 0) {
          console.log(`Mining block #${blocksMined + 1}...`);
          await purechain.blockchain.minePendingTransactions(minerAddress);
          blocksMined++;
          console.log(`Block mined! Total blocks: ${blocksMined}`);
        }
      }, 10000); // 10 seconds

      // Simulate transactions
      const users = ['alice', 'bob', 'charlie', 'david', 'eve'];

      const txInterval = setInterval(() => {
        const from = users[Math.floor(Math.random() * users.length)];
        const to = users[Math.floor(Math.random() * users.length)];
        if (from !== to) {
          purechain.blockchain.createTransaction({
            from,
            to,
            amount: Math.floor(Math.random() * 100) + 1,
            timestamp: Date.now()
          });
          console.log(`Transaction: ${from} -> ${to}`);
        }
      }, 3000); // Every 3 seconds

      // Run for 1 minute
      setTimeout(async () => {
        clearInterval(miningInterval);
        clearInterval(txInterval);

        console.log('\\nMining Summary:');
        console.log('Total blocks mined:', blocksMined);
        console.log('Miner balance:', purechain.blockchain.getBalance(minerAddress));
        console.log('Chain valid:', purechain.blockchain.isChainValid());

        await purechain.stop();
      }, 60000);
    }

    autoMining();

## 2.4 Checking Balances

### Individual Balance Check

    async function checkBalance() {
      const purechain = new PureChain();
      await purechain.start();

      // Create some transactions
      purechain.blockchain.createTransaction({
        from: 'genesis',
        to: 'alice',
        amount: 1000,
        timestamp: Date.now()
      });

      purechain.blockchain.createTransaction({
        from: 'genesis',
        to: 'bob',
        amount: 500,
        timestamp: Date.now()
      });

      // Mine the transactions
      await purechain.blockchain.minePendingTransactions('miner');

      // Check balances
      const aliceBalance = purechain.blockchain.getBalance('alice');
      const bobBalance = purechain.blockchain.getBalance('bob');
      const minerBalance = purechain.blockchain.getBalance('miner');

      console.log('Balances:');
      console.log('Alice:', aliceBalance);
      console.log('Bob:', bobBalance);
      console.log('Miner:', minerBalance);

      await purechain.stop();
    }

    checkBalance();

### Balance History

    async function balanceHistory() {
      const purechain = new PureChain();
      await purechain.start();

      const address = 'alice';
      const history = [];

      // Transaction 1
      purechain.blockchain.createTransaction({
        from: 'genesis',
        to: address,
        amount: 1000,
        timestamp: Date.now()
      });
      await purechain.blockchain.minePendingTransactions('miner');
      history.push({
        block: purechain.blockchain.chain.length - 1,
        balance: purechain.blockchain.getBalance(address)
      });

      // Transaction 2
      purechain.blockchain.createTransaction({
        from: address,
        to: 'bob',
        amount: 300,
        timestamp: Date.now()
      });
      await purechain.blockchain.minePendingTransactions('miner');
      history.push({
        block: purechain.blockchain.chain.length - 1,
        balance: purechain.blockchain.getBalance(address)
      });

      // Transaction 3
      purechain.blockchain.createTransaction({
        from: 'charlie',
        to: address,
        amount: 150,
        timestamp: Date.now()
      });
      await purechain.blockchain.minePendingTransactions('miner');
      history.push({
        block: purechain.blockchain.chain.length - 1,
        balance: purechain.blockchain.getBalance(address)
      });

      console.log(`Balance history for ${address}:`);
      history.forEach(entry => {
        console.log(`Block #${entry.block}: ${entry.balance}`);
      });

      await purechain.stop();
    }

    balanceHistory();

### Multiple Address Balances

    async function multipleBalances() {
      const purechain = new PureChain();
      await purechain.start();

      // Setup initial distribution
      const initialDistribution = [
        { to: 'alice', amount: 1000 },
        { to: 'bob', amount: 750 },
        { to: 'charlie', amount: 500 },
        { to: 'david', amount: 250 },
        { to: 'eve', amount: 100 }
      ];

      // Create distribution transactions
      initialDistribution.forEach(dist => {
        purechain.blockchain.createTransaction({
          from: 'genesis',
          to: dist.to,
          amount: dist.amount,
          timestamp: Date.now()
        });
      });

      // Mine the distribution
      await purechain.blockchain.minePendingTransactions('miner');

      // Check all balances
      const addresses = ['alice', 'bob', 'charlie', 'david', 'eve', 'miner'];
      const balances = {};

      addresses.forEach(addr => {
        balances[addr] = purechain.blockchain.getBalance(addr);
      });

      // Display as table
      console.log('\\nAccount Balances:');
      console.log('==================');
      Object.entries(balances).forEach(([addr, balance]) => {
        console.log(`${addr.padEnd(10)} : ${balance}`);
      });

      // Calculate total supply
      const totalSupply = Object.values(balances).reduce((sum, bal) => sum + bal, 0);
      console.log('==================');
      console.log(`Total      : ${totalSupply}`);

      await purechain.stop();
    }

    multipleBalances();

# 3 Smart Contract Development

## 3.1 Contract Types Overview

PureChain provides five pre-built contract types and support for custom contracts:

Contract Type | Use Case | Key Features
--- | --- | ---
TOKEN | Fungible tokens (like ERC-20) | Transfer, Approve, Mint, Burn
NFT | Non-fungible tokens | Mint, Transfer, Metadata, Collections
ESCROW | Secure payment holding | Create, Release, Refund, Dispute
VOTING | Governance and decisions | Proposals, Vote, Tally, Execute
STORAGE | On-chain data storage | Set, Get, Delete, Access Control
CUSTOM | User-defined logic | Fully customizable

## 3.2 Token Contracts

### Deploying a Token Contract

    const { PureChain, ContractType } = require('purechainlib');

    async function deployToken() {
      const purechain = new PureChain();
      await purechain.start();

      // Token configuration
      const tokenConfig = {
        type: ContractType.TOKEN,
        name: 'MyToken',
        symbol: 'MTK',
        initialSupply: 1000000,
        decimals: 18,
        metadata: {
          description: 'My custom token on PureChain',
          website: 'https://mytoken.com',
          whitepaper: 'https://mytoken.com/whitepaper.pdf'
        }
      };

      // Deploy the token (FREE - no gas cost!)
      const deployerAddress = 'tokenDeployer';
      const deployerBalance = 0; // No balance needed for gas!

      const result = await purechain.contractEngine.deployContract(
        tokenConfig,
        deployerAddress,
        deployerBalance
      );

      if (result.success) {
        console.log('Token deployed successfully!');
        console.log('Contract address:', result.contractAddress);
        console.log('Deployment cost:', result.deploymentCost); // Always 0
        console.log('Transaction ID:', result.transactionId);

        // Store the contract for later use
        const tokenContract = result.contract;

        // Check initial supply
        const totalSupply = tokenContract.execute('totalSupply', [], deployerAddress);
        console.log('Total supply:', totalSupply.result);

        const deployerTokenBalance = tokenContract.execute('balanceOf', [deployerAddress], 'anyone');
        console.log('Deployer balance:', deployerTokenBalance.result);
      } else {
        console.log('Deployment failed:', result.error);
      }

      await purechain.stop();
    }

    deployToken();

### Token Operations

    async function tokenOperations() {
      const purechain = new PureChain();
      await purechain.start();

      // Deploy token first
      const result = await purechain.contractEngine.deployContract({
        type: ContractType.TOKEN,
        name: 'TestToken',
        symbol: 'TEST',
        initialSupply: 1000000,
        decimals: 18
      }, 'owner', 0);

      if (result.success) {
        const token = result.contract;

        // 1. Transfer tokens
        console.log('\\n--- Transfer Operation ---');
        const transferResult = token.execute('transfer', ['alice', 1000], 'owner');
        console.log('Transfer to Alice:', transferResult.success);

        // 2. Check balance
        const aliceBalance = token.execute('balanceOf', ['alice'], 'anyone');
        console.log('Alice balance:', aliceBalance.result);

        // 3. Approve spending
        console.log('\\n--- Approval Operation ---');
        const approveResult = token.execute('approve', ['bob', 500], 'alice');
        console.log('Alice approved Bob:', approveResult.success);

        // 4. Check allowance
        const allowance = token.execute('allowance', ['alice', 'bob'], 'anyone');
        console.log('Bob allowance from Alice:', allowance.result);

        // 5. Transfer from (using allowance)
        console.log('\\n--- TransferFrom Operation ---');
        const transferFromResult = token.execute('transferFrom', ['alice', 'charlie', 200], 'bob');
        console.log('Bob transferred from Alice to Charlie:', transferFromResult.success);

        // 6. Mint new tokens (if mintable)
        console.log('\\n--- Minting Operation ---');
        const mintResult = token.execute('mint', ['david', 5000], 'owner');
        console.log('Minted to David:', mintResult.success);

        // 7. Burn tokens
        console.log('\\n--- Burning Operation ---');
        const burnResult = token.execute('burn', [100], 'alice');
        console.log('Alice burned tokens:', burnResult.success);

        // Final balances
        console.log('\\n--- Final Balances ---');
        const addresses = ['owner', 'alice', 'bob', 'charlie', 'david'];
        addresses.forEach(addr => {
          const bal = token.execute('balanceOf', [addr], 'anyone');
          console.log(`${addr}: ${bal.result}`);
        });
      }

      await purechain.stop();
    }

    tokenOperations();

### Advanced Token Features

    async function advancedTokenFeatures() {
      const purechain = new PureChain();
      await purechain.start();

      // Deploy token with advanced features
      const result = await purechain.contractEngine.deployContract({
        type: ContractType.TOKEN,
        name: 'AdvancedToken',
        symbol: 'ADV',
        initialSupply: 10000000,
        decimals: 18,
        metadata: {
          // Tokenomics
          maxSupply: 100000000,
          mintable: true,
          burnable: true,
          pausable: true,

          // Vesting schedule
          vestingEnabled: true,
          vestingSchedule: [
            { recipient: 'team', amount: 1000000, releaseTime: Date.now() + 365 * 24 * 60 * 60 * 1000 },
            { recipient: 'advisors', amount: 500000, releaseTime: Date.now() + 180 * 24 * 60 * 60 * 1000 }
          ],

          // Tax/Fee structure
          transferFee: 0, // No fees on PureChain!

          // Governance
          governanceEnabled: true,
          proposalThreshold: 100000,
          votingPeriod: 7 * 24 * 60 * 60 * 1000 // 7 days
        }
      }, 'owner', 0);

      if (result.success) {
        const token = result.contract;

        // Pause transfers
        token.execute('pause', [], 'owner');
        console.log('Token paused');

        // Try transfer while paused (should fail)
        const pausedTransfer = token.execute('transfer', ['alice', 100], 'owner');
        console.log('Transfer while paused:', pausedTransfer.success); // false

        // Unpause
        token.execute('unpause', [], 'owner');
        console.log('Token unpaused');

        // Now transfer works
        const unpausedTransfer = token.execute('transfer', ['alice', 100], 'owner');
        console.log('Transfer after unpause:', unpausedTransfer.success); // true

        // Check vesting
        const vestingInfo = token.execute('getVestingInfo', ['team'], 'anyone');
        console.log('Team vesting info:', vestingInfo.result);

        // Create governance proposal
        const proposal = token.execute('createProposal', [
          'Increase max supply to 200M',
          'INCREASE_MAX_SUPPLY',
          200000000
        ], 'owner');
        console.log('Proposal created:', proposal.result);
      }

      await purechain.stop();
    }

    advancedTokenFeatures();

## 3.3 NFT Contracts

### Deploying NFT Collection

    async function deployNFTCollection() {
      const purechain = new PureChain();
      await purechain.start();

      const nftConfig = {
        type: ContractType.NFT,
        name: 'CryptoArt Collection',
        metadata: {
          description: 'Unique digital art on PureChain',
          maxSupply: 10000,
          baseURI: 'https://api.cryptoart.com/metadata/',
          royaltyPercentage: 5, // 5% royalty on secondary sales
          artist: 'artistAddress',

          // Collection traits
          traits: [
            { name: 'Background', options: ['Blue', 'Red', 'Green', 'Purple'] },
            { name: 'Style', options: ['Abstract', 'Realistic', 'Surreal'] },
            { name: 'Rarity', options: ['Common', 'Rare', 'Epic', 'Legendary'] }
          ]
        }
      };

      const result = await purechain.contractEngine.deployContract(
        nftConfig,
        'artistAddress',
        0
      );

      if (result.success) {
        console.log('NFT Collection deployed:', result.contractAddress);
        console.log('Gas cost:', result.deploymentCost); // 0
      }

      await purechain.stop();
    }

    deployNFTCollection();

### Minting NFTs

    async function mintNFTs() {
      const purechain = new PureChain();
      await purechain.start();

      // Deploy NFT collection
      const result = await purechain.contractEngine.deployContract({
        type: ContractType.NFT,
        name: 'Digital Collectibles'
      }, 'creator', 0);

      if (result.success) {
        const nftContract = result.contract;

        // Mint single NFT
        const mintResult = nftContract.execute('mintNFT', [
          'collector1', // recipient
          {
            tokenId: 1,
            name: 'Genesis #1',
            description: 'The first NFT in the collection',
            image: 'ipfs://QmXxx...',
            attributes: [
              { trait_type: 'Generation', value: 1 },
              { trait_type: 'Rarity', value: 'Legendary' },
              { trait_type: 'Power', value: 100 }
            ],
            animation_url: 'ipfs://QmYyy...',
            external_url: 'https://collection.com/token/1'
          }
        ], 'creator');

        console.log('NFT #1 minted:', mintResult.success);

        // Batch mint NFTs
        console.log('\\nBatch minting NFTs...');
        for (let i = 2; i <= 10; i++) {
          const batchMint = nftContract.execute('mintNFT', [
            'collector2',
            {
              tokenId: i,
              name: `Collectible #${i}`,
              description: `NFT number ${i} in the series`,
              image: `ipfs://Qm${i}...`,
              attributes: [
                { trait_type: 'Generation', value: 1 },
                { trait_type: 'Number', value: i },
                { trait_type: 'Rarity', value: i <= 3 ? 'Rare' : 'Common' }
              ]
            }
          ], 'creator');

          console.log(`NFT #${i} minted:`, batchMint.success);
        }

        // Check ownership
        const owner1 = nftContract.execute('ownerOf', [1], 'anyone');
        console.log('\\nOwner of NFT #1:', owner1.result);

        const balance = nftContract.execute('balanceOf', ['collector2'], 'anyone');
        console.log('Collector2 owns:', balance.result, 'NFTs');

        // Get NFT metadata
        const metadata = nftContract.execute('tokenURI', [1], 'anyone');
        console.log('\\nNFT #1 metadata:', metadata.result);
      }

      await purechain.stop();
    }

    mintNFTs();

### NFT Marketplace Operations

    async function nftMarketplace() {
      const purechain = new PureChain();
      await purechain.start();

      // Deploy NFT and marketplace contracts
      const nftResult = await purechain.contractEngine.deployContract({
        type: ContractType.NFT,
        name: 'Marketplace NFTs'
      }, 'marketplace', 0);

      if (nftResult.success) {
        const nft = nftResult.contract;

        // Mint NFTs to different users
        nft.execute('mintNFT', ['seller1', { tokenId: 1, name: 'Art #1' }], 'marketplace');
        nft.execute('mintNFT', ['seller2', { tokenId: 2, name: 'Art #2' }], 'marketplace');

        // List NFT for sale
        console.log('\\n--- Listing NFTs ---');
        const listing1 = nft.execute('listForSale', [1, 1000], 'seller1');
        console.log('NFT #1 listed for 1000:', listing1.success);

        const listing2 = nft.execute('listForSale', [2, 1500], 'seller2');
        console.log('NFT #2 listed for 1500:', listing2.success);

        // View listings
        const listings = nft.execute('getListings', [], 'anyone');
        console.log('\\nActive listings:', listings.result);

        // Buy NFT (transfer happens automatically, no gas!)
        console.log('\\n--- Purchasing NFT ---');
        const purchase = nft.execute('buyNFT', [1], 'buyer1');
        console.log('NFT #1 purchased:', purchase.success);

        // Check new ownership
        const newOwner = nft.execute('ownerOf', [1], 'anyone');
        console.log('New owner of NFT #1:', newOwner.result);

        // Transfer NFT
        console.log('\\n--- Transfer NFT ---');
        const transfer = nft.execute('transferFrom', ['buyer1', 'collector', 1], 'buyer1');
        console.log('NFT transferred:', transfer.success);

        // Approve another user to transfer
        console.log('\\n--- Approval ---');
        const approve = nft.execute('approve', ['agent', 2], 'seller2');
        console.log('Agent approved for NFT #2:', approve.success);

        // Agent transfers on behalf
        const agentTransfer = nft.execute('transferFrom', ['seller2', 'finalOwner', 2], 'agent');
        console.log('Agent transferred NFT #2:', agentTransfer.success);
      }

      await purechain.stop();
    }

    nftMarketplace();

## 3.4 Escrow Contracts

### Creating Escrow Agreements

    async function createEscrow() {
      const purechain = new PureChain();
      await purechain.start();

      // Deploy escrow contract
      const result = await purechain.contractEngine.deployContract({
        type: ContractType.ESCROW,
        name: 'Secure Escrow Service',
        metadata: {
          description: 'Trustless escrow on PureChain',
          arbitrator: 'arbitratorAddress',
          fee: 0, // No fees on PureChain!
          disputeWindow: 3 * 24 * 60 * 60 * 1000 // 3 days
        }
      }, 'escrowService', 0);

      if (result.success) {
        const escrow = result.contract;

        // Create an escrow agreement
        const createResult = escrow.execute('createEscrow', [
          'buyer123',      // buyer
          'seller456',     // seller
          5000,           // amount
          Date.now() + 7 * 24 * 60 * 60 * 1000, // deadline (7 days)
          'Purchase of digital goods'  // description
        ], 'escrowService');

        console.log('Escrow created:', createResult.success);
        console.log('Escrow ID:', createResult.result);

        const escrowId = createResult.result;

        // Check escrow details
        const details = escrow.execute('getEscrowDetails', [escrowId], 'anyone');
        console.log('\\nEscrow Details:');
        console.log('Buyer:', details.result.buyer);
        console.log('Seller:', details.result.seller);
        console.log('Amount:', details.result.amount);
        console.log('Status:', details.result.status);
        console.log('Deadline:', new Date(details.result.deadline).toISOString());
      }

      await purechain.stop();
    }

    createEscrow();

### Escrow Workflow

    async function escrowWorkflow() {
      const purechain = new PureChain();
      await purechain.start();

      // Deploy escrow
      const result = await purechain.contractEngine.deployContract({
        type: ContractType.ESCROW,
        name: 'Escrow Platform'
      }, 'platform', 0);

      if (result.success) {
        const escrow = result.contract;

        // Step 1: Create escrow
        console.log('Step 1: Creating escrow...');
        const create = escrow.execute('createEscrow', [
          'buyer',
          'seller',
          1000,
          Date.now() + 86400000,
          'Service payment'
        ], 'platform');

        const escrowId = create.result;
        console.log('Escrow ID:', escrowId);

        // Step 2: Buyer deposits funds (in real implementation)
        console.log('\\nStep 2: Buyer depositing funds...');
        const deposit = escrow.execute('deposit', [escrowId, 1000], 'buyer');
        console.log('Deposit successful:', deposit.success);

        // Step 3: Seller delivers service/product
        console.log('\\nStep 3: Seller marking as delivered...');
        const deliver = escrow.execute('markDelivered', [escrowId], 'seller');
        console.log('Marked as delivered:', deliver.success);

        // Step 4: Buyer confirms receipt
        console.log('\\nStep 4: Buyer confirming receipt...');
        const confirm = escrow.execute('confirmReceipt', [escrowId], 'buyer');
        console.log('Receipt confirmed:', confirm.success);

        // Step 5: Funds released to seller
        console.log('\\nStep 5: Releasing funds...');
        const release = escrow.execute('releaseFunds', [escrowId], 'platform');
        console.log('Funds released:', release.success);

        // Check final status
        const finalStatus = escrow.execute('getEscrowDetails', [escrowId], 'anyone');
        console.log('\\nFinal status:', finalStatus.result.status);
        console.log('Transaction completed with 0 gas fees!');
      }

      await purechain.stop();
    }

    escrowWorkflow();

### Dispute Resolution

    async function escrowDispute() {
      const purechain = new PureChain();
      await purechain.start();

      const result = await purechain.contractEngine.deployContract({
        type: ContractType.ESCROW,
        name: 'Dispute Resolution'
      }, 'arbitrator', 0);

      if (result.success) {
        const escrow = result.contract;

        // Create escrow
        const create = escrow.execute('createEscrow', [
          'buyer',
          'seller',
          2000,
          Date.now() + 86400000,
          'Disputed transaction'
        ], 'arbitrator');

        const escrowId = create.result;

        // Simulate dispute scenario
        console.log('Creating dispute scenario...');

        // Buyer deposits
        escrow.execute('deposit', [escrowId, 2000], 'buyer');

        // Seller claims delivery
        escrow.execute('markDelivered', [escrowId], 'seller');

        // Buyer raises dispute instead of confirming
        console.log('\\nBuyer raising dispute...');
        const dispute = escrow.execute('raiseDispute', [
          escrowId,
          'Product not as described'
        ], 'buyer');
        console.log('Dispute raised:', dispute.success);

        // Seller responds to dispute
        console.log('\\nSeller responding to dispute...');
        const response = escrow.execute('respondToDispute', [
          escrowId,
          'Product was delivered as agreed'
        ], 'seller');
        console.log('Response submitted:', response.success);

        // Arbitrator reviews and decides
        console.log('\\nArbitrator making decision...');

        // Option 1: Rule in favor of buyer (refund)
        const refund = escrow.execute('resolveDispute', [
          escrowId,
          'REFUND',
          'Evidence supports buyer claim'
        ], 'arbitrator');
        console.log('Dispute resolved with refund:', refund.success);

        // Option 2: Rule in favor of seller (release)
        // const release = escrow.execute('resolveDispute', [
        //   escrowId,
        //   'RELEASE',
        //   'Seller fulfilled obligations'
        // ], 'arbitrator');

        // Option 3: Split decision
        // const split = escrow.execute('resolveDispute', [
        //   escrowId,
        //   'SPLIT',
        //   'Partial fulfillment',
        //   { buyerAmount: 1000, sellerAmount: 1000 }
        // ], 'arbitrator');

        // Check final status
        const status = escrow.execute('getEscrowDetails', [escrowId], 'anyone');
        console.log('\\nFinal escrow status:', status.result.status);
        console.log('Resolution:', status.result.resolution);
      }

      await purechain.stop();
    }

    escrowDispute();

## 3.5 Voting Contracts

### Creating Proposals

    async function createVotingProposal() {
      const purechain = new PureChain();
      await purechain.start();

      // Deploy voting contract
      const result = await purechain.contractEngine.deployContract({
        type: ContractType.VOTING,
        name: 'DAO Governance',
        metadata: {
          description: 'Decentralized governance system',
          quorum: 100, // Minimum votes needed
          votingPeriod: 7 * 24 * 60 * 60 * 1000, // 7 days
          proposalThreshold: 10, // Min tokens to create proposal
          voteWeight: 'TOKEN_BASED' // or 'ONE_PERSON_ONE_VOTE'
        }
      }, 'daoAdmin', 0);

      if (result.success) {
        const voting = result.contract;

        // Create proposal
        const proposal = voting.execute('createProposal', [
          'Should we implement feature X?',
          'This proposal suggests implementing feature X which will improve...',
          ['Yes', 'No', 'Abstain'], // Options
          Date.now() + 7 * 24 * 60 * 60 * 1000 // End time
        ], 'proposer');

        console.log('Proposal created!');
        console.log('Proposal ID:', proposal.result);

        // Get proposal details
        const details = voting.execute('getProposal', [proposal.result], 'anyone');
        console.log('\\nProposal Details:');
        console.log('Title:', details.result.title);
        console.log('Options:', details.result.options);
        console.log('End time:', new Date(details.result.endTime).toISOString());
        console.log('Status:', details.result.status);
      }

      await purechain.stop();
    }

    createVotingProposal();

### Voting Process

    async function votingProcess() {
      const purechain = new PureChain();
      await purechain.start();

      // Deploy voting contract
      const result = await purechain.contractEngine.deployContract({
        type: ContractType.VOTING,
        name: 'Community Voting'
      }, 'admin', 0);

      if (result.success) {
        const voting = result.contract;

        // Create multiple proposals
        console.log('Creating proposals...');

        const proposal1 = voting.execute('createProposal', [
          'Increase rewards by 20%?',
          'Should we increase staking rewards?',
          ['Yes', 'No'],
          Date.now() + 3600000 // 1 hour
        ], 'admin');

        const proposal2 = voting.execute('createProposal', [
          'Add new feature?',
          'Should we add feature Y?',
          ['Strongly Agree', 'Agree', 'Neutral', 'Disagree', 'Strongly Disagree'],
          Date.now() + 7200000 // 2 hours
        ], 'admin');

        console.log('Proposal 1 ID:', proposal1.result);
        console.log('Proposal 2 ID:', proposal2.result);

        // Simulate voting
        console.log('\\nSimulating votes...');

        const voters = ['alice', 'bob', 'charlie', 'david', 'eve'];

        // Vote on proposal 1
        voters.forEach((voter, index) => {
          const vote = voting.execute('vote', [
            proposal1.result,
            index % 2 === 0 ? 0 : 1 // Alternate Yes/No
          ], voter);
          console.log(`${voter} voted:`, vote.success);
        });

        // Vote on proposal 2
        voters.forEach((voter, index) => {
          const vote = voting.execute('vote', [
            proposal2.result,
            index // Different option for each
          ], voter);
          console.log(`${voter} voted on P2:`, vote.success);
        });

        // Check current results
        console.log('\\nCurrent Results:');

        const results1 = voting.execute('getResults', [proposal1.result], 'anyone');
        console.log('Proposal 1 results:', results1.result);

        const results2 = voting.execute('getResults', [proposal2.result], 'anyone');
        console.log('Proposal 2 results:', results2.result);

        // Check if user has voted
        const hasVoted = voting.execute('hasVoted', [proposal1.result, 'alice'], 'anyone');
        console.log('\\nAlice has voted on P1:', hasVoted.result);

        // Get all active proposals
        const activeProposals = voting.execute('getActiveProposals', [], 'anyone');
        console.log('\\nActive proposals:', activeProposals.result.length);
      }

      await purechain.stop();
    }

    votingProcess();

## 3.6 Storage Contracts

### Key-Value Storage

    async function keyValueStorage() {
      const purechain = new PureChain();
      await purechain.start();

      // Deploy storage contract
      const result = await purechain.contractEngine.deployContract({
        type: ContractType.STORAGE,
        name: 'Data Vault',
        metadata: {
          description: 'Decentralized storage on PureChain',
          maxSize: 1000000, // Max storage size in bytes
          accessControl: true,
          encryption: false // Handle encryption client-side
        }
      }, 'storageOwner', 0);

      if (result.success) {
        const storage = result.contract;

        // Store different data types
        console.log('Storing data...');

        // String data
        storage.execute('set', ['username', 'alice123'], 'user1');

        // Number data
        storage.execute('set', ['score', 9500], 'user1');

        // Object data
        storage.execute('set', ['profile', {
          name: 'Alice',
          age: 28,
          email: 'alice@example.com',
          preferences: {
            theme: 'dark',
            notifications: true
          }
        }], 'user1');

        // Array data
        storage.execute('set', ['achievements', [
          'First Login',
          'Profile Complete',
          '100 Transactions'
        ]], 'user1');

        // Retrieve data
        console.log('\\nRetrieving data...');

        const username = storage.execute('get', ['username'], 'anyone');
        console.log('Username:', username.result);

        const profile = storage.execute('get', ['profile'], 'anyone');
        console.log('Profile:', profile.result);

        const achievements = storage.execute('get', ['achievements'], 'anyone');
        console.log('Achievements:', achievements.result);

        // Update data
        console.log('\\nUpdating data...');
        storage.execute('set', ['score', 10000], 'user1');
        const newScore = storage.execute('get', ['score'], 'anyone');
        console.log('Updated score:', newScore.result);

        // Delete data
        console.log('\\nDeleting data...');
        storage.execute('delete', ['username'], 'user1');
        const deleted = storage.execute('get', ['username'], 'anyone');
        console.log('After deletion:', deleted.result); // null or undefined

        // List all keys
        const keys = storage.execute('listKeys', [], 'user1');
        console.log('\\nAll keys:', keys.result);
      }

      await purechain.stop();
    }

    keyValueStorage();

### Access Control

    async function storageAccessControl() {
      const purechain = new PureChain();
      await purechain.start();

      const result = await purechain.contractEngine.deployContract({
        type: ContractType.STORAGE,
        name: 'Private Storage'
      }, 'admin', 0);

      if (result.success) {
        const storage = result.contract;

        // Set private data
        console.log('Setting private data...');
        storage.execute('setPrivate', ['secret', 'my-secret-data'], 'owner');

        // Try to read as different user (should fail)
        const unauthorized = storage.execute('get', ['secret'], 'hacker');
        console.log('Unauthorized access:', unauthorized.success); // false

        // Grant access to specific user
        console.log('\\nGranting access...');
        storage.execute('grantAccess', ['secret', 'trustedUser'], 'owner');

        // Now trusted user can read
        const authorized = storage.execute('get', ['secret'], 'trustedUser');
        console.log('Authorized access:', authorized.result);

        // Revoke access
        console.log('\\nRevoking access...');
        storage.execute('revokeAccess', ['secret', 'trustedUser'], 'owner');

        // Access revoked
        const revoked = storage.execute('get', ['secret'], 'trustedUser');
        console.log('After revocation:', revoked.success); // false

        // Set public data
        console.log('\\nSetting public data...');
        storage.execute('setPublic', ['announcement', 'Hello World!'], 'owner');

        // Anyone can read public data
        const publicData = storage.execute('get', ['announcement'], 'anyone');
        console.log('Public data:', publicData.result);
      }

      await purechain.stop();
    }

    storageAccessControl();

## 3.7 Custom Contracts

### Creating Custom Logic

    async function customContract() {
      const purechain = new PureChain();
      await purechain.start();

      // Define custom contract
      const customConfig = {
        type: ContractType.CUSTOM,
        name: 'GameContract',
        metadata: {
          description: 'Custom game logic contract',
          version: '1.0.0'
        },
        customMethods: {
          // Initialize game
          initGame: (params, state, caller) => {
            const [gameName, maxPlayers] = params;
            state.games = state.games || {};
            state.games[gameName] = {
              creator: caller,
              maxPlayers,
              players: [],
              status: 'WAITING',
              createdAt: Date.now()
            };
            return { success: true, gameId: gameName };
          },

          // Join game
          joinGame: (params, state, caller) => {
            const [gameId] = params;
            const game = state.games?.[gameId];

            if (!game) return { success: false, error: 'Game not found' };
            if (game.players.includes(caller)) return { success: false, error: 'Already joined' };
            if (game.players.length >= game.maxPlayers) return { success: false, error: 'Game full' };

            game.players.push(caller);
            if (game.players.length === game.maxPlayers) {
              game.status = 'IN_PROGRESS';
            }

            return { success: true, players: game.players.length };
          },

          // Make move
          makeMove: (params, state, caller) => {
            const [gameId, move] = params;
            const game = state.games?.[gameId];

            if (!game) return { success: false, error: 'Game not found' };
            if (!game.players.includes(caller)) return { success: false, error: 'Not a player' };
            if (game.status !== 'IN_PROGRESS') return { success: false, error: 'Game not active' };

            state.moves = state.moves || {};
            state.moves[gameId] = state.moves[gameId] || [];
            state.moves[gameId].push({
              player: caller,
              move,
              timestamp: Date.now()
            });

            return { success: true, moveCount: state.moves[gameId].length };
          },

          // End game
          endGame: (params, state, caller) => {
            const [gameId, winner] = params;
            const game = state.games?.[gameId];

            if (!game) return { success: false, error: 'Game not found' };
            if (game.creator !== caller) return { success: false, error: 'Only creator can end' };

            game.status = 'COMPLETED';
            game.winner = winner;
            game.endedAt = Date.now();

            return { success: true, winner };
          },

          // Get game status
          getGameStatus: (params, state) => {
            const [gameId] = params;
            return state.games?.[gameId] || null;
          },

          // List active games
          listActiveGames: (params, state) => {
            const games = state.games || {};
            return Object.entries(games)
              .filter(([_, game]) => game.status === 'WAITING' || game.status === 'IN_PROGRESS')
              .map(([id, game]) => ({
                id,
                players: game.players.length,
                maxPlayers: game.maxPlayers,
                status: game.status
              }));
          }
        }
      };

      // Deploy custom contract
      const result = await purechain.contractEngine.deployContract(
        customConfig,
        'gameOwner',
        0
      );

      if (result.success) {
        const game = result.contract;

        // Create a game
        console.log('Creating game...');
        const create = game.execute('initGame', ['Chess Match 1', 2], 'alice');
        console.log('Game created:', create.result);

        // Players join
        console.log('\\nPlayers joining...');
        game.execute('joinGame', ['Chess Match 1'], 'alice');
        game.execute('joinGame', ['Chess Match 1'], 'bob');

        // Make moves
        console.log('\\nMaking moves...');
        game.execute('makeMove', ['Chess Match 1', 'e2-e4'], 'alice');
        game.execute('makeMove', ['Chess Match 1', 'e7-e5'], 'bob');

        // Check status
        const status = game.execute('getGameStatus', ['Chess Match 1'], 'anyone');
        console.log('\\nGame status:', status.result);

        // End game
        game.execute('endGame', ['Chess Match 1', 'alice'], 'alice');
        console.log('\\nGame ended!');

        // List games
        const activeGames = game.execute('listActiveGames', [], 'anyone');
        console.log('Active games:', activeGames.result);
      }

      await purechain.stop();
    }

    customContract();

# 4 Network Configuration

## 4.1 Network Types

Network | Chain ID | RPC URL | Status
--- | --- | --- | ---
Testnet | 900520900520 | https://purechainnode.com:8547 | Active
Mainnet | 900520900520 | Coming Soon | Not Launched
Local | 1337 | http://localhost:8545 | Development

### Connecting to Different Networks

    const { PureChain } = require('purechainlib');

    // Testnet (default)
    const testnet = new PureChain();

    // Explicit testnet
    const testnetExplicit = new PureChain({
      networkConfig: 'testnet'
    });

    // Local development
    const local = new PureChain({
      networkConfig: 'local'
    });

    // Mainnet (when available)
    const mainnet = new PureChain({
      networkConfig: 'mainnet'
    });

## 4.2 Custom Networks

    const customNetwork = new PureChain({
      networkConfig: {
        name: 'Custom PureChain Network',
        chainId: 999999,
        rpcUrl: 'https://custom.purechain.com:8547',
        explorerUrl: 'https://explorer.custom.purechain.com/api/v1',
        nativeCurrency: {
          name: 'Custom Token',
          symbol: 'CTK',
          decimals: 18
        },
        isTestnet: true,
        blockTime: 5000, // 5 seconds
        consensus: 'PoS'
      }
    });

    await customNetwork.start();
    console.log('Connected to:', customNetwork.networkConfig.name);

## 4.3 Switching Networks

    async function networkSwitching() {
      const purechain = new PureChain();

      // Start with testnet
      await purechain.start();
      console.log('Initial network:', purechain.networkConfig.name);

      // Switch to local
      await purechain.switchNetwork('local');
      console.log('Switched to:', purechain.networkConfig.name);

      // Switch to custom network
      await purechain.switchNetwork({
        name: 'Private Network',
        chainId: 12345,
        rpcUrl: 'http://192.168.1.100:8545',
        explorerUrl: null,
        nativeCurrency: {
          name: 'Private Token',
          symbol: 'PVT',
          decimals: 18
        },
        isTestnet: false
      });
      console.log('Switched to:', purechain.networkConfig.name);

      await purechain.stop();
    }

    networkSwitching();

# 5 Explorer Integration

## 5.1 Transaction Queries

    async function queryTransactions() {
      const purechain = new PureChain();
      await purechain.start();

      // Get transaction by hash
      const txHash = '0x9734d1e5...';
      const tx = await purechain.explorer.getTransaction(txHash);

      if (tx.success) {
        console.log('Transaction Details:');
        console.log('From:', tx.data.from);
        console.log('To:', tx.data.to);
        console.log('Amount:', tx.data.amount);
        console.log('Status:', tx.data.status);
        console.log('Block:', tx.data.blockNumber);
        console.log('Gas Cost:', 0); // Always 0 on PureChain
      }

      // Get transaction receipt
      const receipt = await purechain.explorer.getTransactionReceipt(txHash);
      console.log('Receipt:', receipt.data);

      // Get printable receipt
      const htmlReceipt = await purechain.explorer.getPrintableReceipt(txHash);
      // Can be saved as HTML file for printing

      await purechain.stop();
    }

    queryTransactions();

## 5.2 Block Exploration

    async function exploreBlocks() {
      const purechain = new PureChain();
      await purechain.start();

      // Get latest block
      const latest = await purechain.explorer.getLatestBlock();
      console.log('Latest Block:', latest.data.number);

      // Get specific block
      const blockNumber = 12345;
      const block = await purechain.explorer.getBlock(blockNumber);

      if (block.success) {
        console.log('Block Details:');
        console.log('Number:', block.data.number);
        console.log('Hash:', block.data.hash);
        console.log('Transactions:', block.data.transactions.length);
        console.log('Timestamp:', new Date(block.data.timestamp).toISOString());
        console.log('Miner:', block.data.miner);
      }

      await purechain.stop();
    }

    exploreBlocks();

## 5.3 Account Information

    async function accountInfo() {
      const purechain = new PureChain();
      await purechain.start();

      const address = '0x44A393FA...';
      const account = await purechain.explorer.getAccount(address);

      if (account.success) {
        console.log('Account Information:');
        console.log('Address:', address);
        console.log('Balance:', account.data.balance);
        console.log('Transaction Count:', account.data.transactionCount);
        console.log('Contract:', account.data.isContract);

        // Get transaction history
        if (account.data.transactions) {
          console.log('\\nRecent Transactions:');
          account.data.transactions.slice(0, 5).forEach(tx => {
            console.log(`- ${tx.hash}: ${tx.from} -> ${tx.to} (${tx.amount})`);
          });
        }
      }

      await purechain.stop();
    }

    accountInfo();

# 6 API Development

## 6.1 REST API Setup

    const { PureChain } = require('purechainlib');
    const express = require('express');

    async function setupAPI() {
      const purechain = new PureChain({
        api: {
          port: 3000,
          cors: true,
          rateLimit: {
            windowMs: 15 * 60 * 1000,
            max: 100
          }
        }
      });

      await purechain.start();

      // API is now running on port 3000
      console.log('API running on http://localhost:3000');

      // Available endpoints:
      // GET  /api/v1/blocks
      // GET  /api/v1/blocks/latest
      // GET  /api/v1/blocks/:number
      // POST /api/v1/transactions
      // GET  /api/v1/transactions/:hash
      // GET  /api/v1/balance/:address
      // GET  /api/v1/contracts
      // POST /api/v1/contracts/deploy
      // POST /api/v1/contracts/:address/execute
    }

    setupAPI();

### Custom API Endpoints

    async function customEndpoints() {
      const purechain = new PureChain();
      await purechain.start();

      // Access the Express app
      const app = purechain.api.app;

      // Add custom endpoints
      app.get('/api/v1/stats', (req, res) => {
        const stats = {
          chainLength: purechain.blockchain.chain.length,
          pendingTransactions: purechain.blockchain.pendingTransactions.length,
          totalContracts: purechain.contractEngine.getAllContracts().length,
          gasCost: 0,
          networkName: purechain.networkConfig.name
        };
        res.json(stats);
      });

      app.get('/api/v1/richlist', (req, res) => {
        // Get all unique addresses and their balances
        const addresses = new Set();
        purechain.blockchain.chain.forEach(block => {
          block.transactions.forEach(tx => {
            addresses.add(tx.from);
            addresses.add(tx.to);
          });
        });

        const balances = Array.from(addresses)
          .map(addr => ({
            address: addr,
            balance: purechain.blockchain.getBalance(addr)
          }))
          .sort((a, b) => b.balance - a.balance)
          .slice(0, 10);

        res.json(balances);
      });

      console.log('Custom endpoints added');
    }

    customEndpoints();

## 6.2 WebSocket Events

    const WebSocket = require('ws');

    async function websocketEvents() {
      const purechain = new PureChain();
      await purechain.start();

      // Connect to WebSocket
      const ws = new WebSocket('ws://localhost:3000');

      ws.on('open', () => {
        console.log('WebSocket connected');

        // Subscribe to events
        ws.send(JSON.stringify({
          type: 'subscribe',
          events: ['newBlock', 'newTransaction', 'contractDeployed']
        }));
      });

      ws.on('message', (data) => {
        const message = JSON.parse(data);

        switch(message.type) {
          case 'newBlock':
            console.log('New block mined:', message.data.index);
            break;

          case 'newTransaction':
            console.log('New transaction:', message.data.id);
            break;

          case 'contractDeployed':
            console.log('Contract deployed:', message.data.address);
            break;
        }
      });

      // Simulate activity
      setTimeout(() => {
        purechain.blockchain.createTransaction({
          from: 'alice',
          to: 'bob',
          amount: 100,
          timestamp: Date.now()
        });
      }, 2000);

      setTimeout(async () => {
        await purechain.blockchain.minePendingTransactions('miner');
      }, 5000);
    }

    websocketEvents();

## 6.3 Custom Endpoints

    async function advancedAPI() {
      const purechain = new PureChain();
      await purechain.start();

      const app = purechain.api.app;

      // Token faucet endpoint
      app.post('/api/v1/faucet', async (req, res) => {
        const { address } = req.body;

        if (!address) {
          return res.status(400).json({ error: 'Address required' });
        }

        // Create faucet transaction
        purechain.blockchain.createTransaction({
          from: 'faucet',
          to: address,
          amount: 100,
          timestamp: Date.now()
        });

        // Mine immediately
        await purechain.blockchain.minePendingTransactions('faucet');

        const balance = purechain.blockchain.getBalance(address);

        res.json({
          success: true,
          amount: 100,
          newBalance: balance,
          gasCost: 0
        });
      });

      // Batch transaction endpoint
      app.post('/api/v1/batch-transfer', async (req, res) => {
        const { transfers } = req.body;

        if (!Array.isArray(transfers)) {
          return res.status(400).json({ error: 'Transfers array required' });
        }

        const results = [];

        transfers.forEach(transfer => {
          purechain.blockchain.createTransaction({
            from: transfer.from,
            to: transfer.to,
            amount: transfer.amount,
            timestamp: Date.now()
          });
          results.push({
            from: transfer.from,
            to: transfer.to,
            amount: transfer.amount,
            status: 'pending'
          });
        });

        // Mine all transactions
        await purechain.blockchain.minePendingTransactions('batcher');

        res.json({
          success: true,
          transactions: results.length,
          totalGasCost: 0,
          results
        });
      });

      // Smart contract interaction endpoint
      app.post('/api/v1/contract-call', async (req, res) => {
        const { contractAddress, method, params, caller } = req.body;

        const contract = purechain.contractEngine.getContract(contractAddress);

        if (!contract) {
          return res.status(404).json({ error: 'Contract not found' });
        }

        const result = contract.execute(method, params, caller);

        res.json({
          success: result.success,
          result: result.result,
          gasCost: 0,
          error: result.error
        });
      });

      console.log('Advanced API endpoints configured');
    }

    advancedAPI();

# 7 Advanced Features

## 7.1 Consensus Mechanisms

### Proof of Work (PoW)

    const { PureChain, ConsensusType } = require('purechainlib');

    async function proofOfWork() {
      const purechain = new PureChain({
        blockchain: {
          consensus: ConsensusType.POW,
          difficulty: 4, // Number of leading zeros required
          miningReward: 100
        }
      });

      await purechain.start();

      // Mining with PoW
      console.log('Mining with Proof of Work...');
      console.time('Mining time');

      await purechain.blockchain.minePendingTransactions('miner');

      console.timeEnd('Mining time');

      const latestBlock = purechain.blockchain.getLatestBlock();
      console.log('Block hash:', latestBlock.hash);
      console.log('Nonce:', latestBlock.nonce);
      console.log('Difficulty:', purechain.blockchain.difficulty);

      await purechain.stop();
    }

    proofOfWork();

### Proof of Stake (PoS)

    async function proofOfStake() {
      const purechain = new PureChain({
        blockchain: {
          consensus: ConsensusType.POS,
          minStake: 1000
        }
      });

      await purechain.start();

      // Register validators
      const validators = [
        { address: 'validator1', stake: 5000 },
        { address: 'validator2', stake: 3000 },
        { address: 'validator3', stake: 2000 }
      ];

      validators.forEach(v => {
        purechain.blockchain.consensus.addValidator(v.address, v.stake);
      });

      // Select validator based on stake
      const selectedValidator = purechain.blockchain.consensus.selectValidator();
      console.log('Selected validator:', selectedValidator);

      // Mine block with selected validator
      await purechain.blockchain.minePendingTransactions(selectedValidator);

      console.log('Block mined by:', selectedValidator);
      console.log('Validator reward:', purechain.blockchain.getBalance(selectedValidator));

      await purechain.stop();
    }

    proofOfStake();

## 7.2 P2P Networking

    async function p2pNetwork() {
      const purechain = new PureChain({
        network: {
          port: 6001,
          peers: [
            'ws://localhost:6002',
            'ws://localhost:6003'
          ]
        }
      });

      await purechain.start();

      // Add new peer
      purechain.network.addPeer('ws://localhost:6004');

      // Broadcast transaction to peers
      const tx = {
        from: 'alice',
        to: 'bob',
        amount: 100,
        timestamp: Date.now()
      };

      purechain.network.broadcastTransaction(tx);

      // Handle incoming messages
      purechain.network.on('transaction', (tx) => {
        console.log('Received transaction from peer:', tx);
      });

      purechain.network.on('block', (block) => {
        console.log('Received block from peer:', block);
      });

      // Get connected peers
      const peers = purechain.network.getPeers();
      console.log('Connected peers:', peers.length);

      await purechain.stop();
    }

    p2pNetwork();

## 7.3 Database Storage

    async function databaseStorage() {
      const purechain = new PureChain({
        storage: {
          type: 'persistent',
          path: './blockchain-data'
        }
      });

      await purechain.start();

      // Save blockchain to database
      await purechain.database.saveBlockchain(purechain.blockchain);
      console.log('Blockchain saved to database');

      // Load blockchain from database
      const loadedBlockchain = await purechain.database.loadBlockchain();
      console.log('Loaded chain length:', loadedBlockchain.chain.length);

      // Save contracts
      const contracts = purechain.contractEngine.getAllContracts();
      await purechain.database.saveContracts(contracts);

      // Query specific data
      const block = await purechain.database.getBlock(5);
      const tx = await purechain.database.getTransaction('txHash');

      await purechain.stop();
    }

    databaseStorage();

# 8 Complete Examples

## 8.1 Building a DApp

    const { PureChain, ContractType } = require('purechainlib');

    async function buildCompleteDApp() {
      console.log('Building Complete DApp on PureChain...');
      console.log('=====================================\\n');

      const purechain = new PureChain();
      await purechain.start();

      // Step 1: Deploy Core Contracts
      console.log('Step 1: Deploying Core Contracts');
      console.log('---------------------------------');

      // Deploy governance token
      const tokenResult = await purechain.contractEngine.deployContract({
        type: ContractType.TOKEN,
        name: 'DAppToken',
        symbol: 'DAPP',
        initialSupply: 100000000,
        decimals: 18,
        metadata: {
          description: 'Governance token for our DApp',
          mintable: true,
          burnable: true
        }
      }, 'dappFoundation', 0);

      console.log('✓ Token deployed:', tokenResult.contractAddress);

      // Deploy voting contract
      const votingResult = await purechain.contractEngine.deployContract({
        type: ContractType.VOTING,
        name: 'DAppGovernance',
        metadata: {
          quorum: 1000,
          votingPeriod: 7 * 24 * 60 * 60 * 1000
        }
      }, 'dappFoundation', 0);

      console.log('✓ Voting deployed:', votingResult.contractAddress);

      // Deploy NFT rewards
      const nftResult = await purechain.contractEngine.deployContract({
        type: ContractType.NFT,
        name: 'DAppRewards',
        metadata: {
          description: 'Achievement NFTs for active users'
        }
      }, 'dappFoundation', 0);

      console.log('✓ NFT Rewards deployed:', nftResult.contractAddress);

      // Deploy storage for user data
      const storageResult = await purechain.contractEngine.deployContract({
        type: ContractType.STORAGE,
        name: 'UserProfiles'
      }, 'dappFoundation', 0);

      console.log('✓ Storage deployed:', storageResult.contractAddress);

      // Step 2: Initialize DApp
      console.log('\\nStep 2: Initializing DApp');
      console.log('-------------------------');

      const token = tokenResult.contract;
      const voting = votingResult.contract;
      const nft = nftResult.contract;
      const storage = storageResult.contract;

      // Distribute tokens to initial users
      const initialUsers = [
        { address: 'alice', amount: 10000, role: 'developer' },
        { address: 'bob', amount: 5000, role: 'designer' },
        { address: 'charlie', amount: 5000, role: 'marketer' },
        { address: 'david', amount: 2000, role: 'tester' },
        { address: 'eve', amount: 2000, role: 'community' }
      ];

      initialUsers.forEach(user => {
        token.execute('transfer', [user.address, user.amount], 'dappFoundation');
        storage.execute('set', [`profile_${user.address}`, {
          address: user.address,
          role: user.role,
          joinedAt: Date.now(),
          reputation: 0
        }], 'dappFoundation');
        console.log(`✓ ${user.address}: ${user.amount} tokens, role: ${user.role}`);
      });

      // Step 3: Create First Proposal
      console.log('\\nStep 3: Creating Governance Proposal');
      console.log('------------------------------------');

      const proposalResult = voting.execute('createProposal', [
        'Should we add staking features?',
        'Proposal to add staking mechanism to earn rewards',
        ['Yes', 'No', 'Abstain'],
        Date.now() + 24 * 60 * 60 * 1000 // 24 hours
      ], 'alice');

      const proposalId = proposalResult.result;
      console.log('✓ Proposal created:', proposalId);

      // Step 4: Voting Process
      console.log('\\nStep 4: Voting on Proposal');
      console.log('--------------------------');

      voting.execute('vote', [proposalId, 0], 'alice'); // Yes
      voting.execute('vote', [proposalId, 0], 'bob'); // Yes
      voting.execute('vote', [proposalId, 1], 'charlie'); // No
      voting.execute('vote', [proposalId, 0], 'david'); // Yes
      voting.execute('vote', [proposalId, 2], 'eve'); // Abstain

      const results = voting.execute('getResults', [proposalId], 'anyone');
      console.log('Voting results:', results.result);

      // Step 5: Reward Active Participants
      console.log('\\nStep 5: Distributing NFT Rewards');
      console.log('--------------------------------');

      const voters = ['alice', 'bob', 'charlie', 'david', 'eve'];
      voters.forEach((voter, index) => {
        nft.execute('mintNFT', [
          voter,
          {
            tokenId: index + 1,
            name: `Governance Badge #${index + 1}`,
            description: 'Awarded for participating in governance',
            image: `ipfs://badge${index + 1}`,
            attributes: [
              { trait_type: 'Type', value: 'Governance' },
              { trait_type: 'Proposal', value: proposalId },
              { trait_type: 'Date', value: new Date().toISOString() }
            ]
          }
        ], 'dappFoundation');
        console.log(`✓ NFT badge awarded to ${voter}`);
      });

      // Step 6: Update User Reputation
      console.log('\\nStep 6: Updating User Reputation');
      console.log('--------------------------------');

      voters.forEach(voter => {
        const profile = storage.execute('get', [`profile_${voter}`], 'anyone').result;
        profile.reputation += 10;
        profile.participationCount = (profile.participationCount || 0) + 1;
        storage.execute('set', [`profile_${voter}`, profile], 'dappFoundation');
        console.log(`✓ ${voter} reputation: ${profile.reputation}`);
      });

      // Step 7: DApp Statistics
      console.log('\\nStep 7: DApp Statistics');
      console.log('-----------------------');

      const stats = {
        totalUsers: initialUsers.length,
        totalTokenSupply: token.execute('totalSupply', [], 'anyone').result,
        activeProposals: 1,
        totalVotes: 5,
        nftsDistributed: voters.length,
        totalGasCost: 0
      };

      console.log('DApp Statistics:', stats);

      // Step 8: Create Dashboard Data
      console.log('\\nStep 8: Dashboard Summary');
      console.log('-------------------------');

      storage.execute('set', ['dashboard', {
        stats,
        latestProposal: proposalId,
        topHolders: initialUsers.slice(0, 3).map(u => u.address),
        recentActivity: [
          { type: 'proposal_created', user: 'alice', timestamp: Date.now() },
          { type: 'votes_cast', count: 5, timestamp: Date.now() },
          { type: 'nfts_minted', count: 5, timestamp: Date.now() }
        ]
      }], 'dappFoundation');

      const dashboard = storage.execute('get', ['dashboard'], 'anyone').result;
      console.log('Dashboard data stored');

      console.log('\\n=====================================');
      console.log('DApp Successfully Deployed!');
      console.log('Total Gas Cost: 0 (Free on PureChain)');
      console.log('=====================================');

      await purechain.stop();
    }

    buildCompleteDApp();

## 8.2 Token Economy

    async function createTokenEconomy() {
      console.log('Creating Complete Token Economy');
      console.log('================================\\n');

      const purechain = new PureChain();
      await purechain.start();

      // Deploy main token
      const mainToken = await purechain.contractEngine.deployContract({
        type: ContractType.TOKEN,
        name: 'EconomyToken',
        symbol: 'ECO',
        initialSupply: 1000000000,
        decimals: 18
      }, 'treasury', 0);

      // Deploy staking token
      const stakingToken = await purechain.contractEngine.deployContract({
        type: ContractType.TOKEN,
        name: 'StakedECO',
        symbol: 'sECO',
        initialSupply: 0,
        decimals: 18
      }, 'treasury', 0);

      // Deploy liquidity pool token
      const lpToken = await purechain.contractEngine.deployContract({
        type: ContractType.TOKEN,
        name: 'ECO-LP',
        symbol: 'ECO-LP',
        initialSupply: 0,
        decimals: 18
      }, 'treasury', 0);

      console.log('Tokens deployed:');
      console.log('Main token:', mainToken.contractAddress);
      console.log('Staking token:', stakingToken.contractAddress);
      console.log('LP token:', lpToken.contractAddress);

      // Token distribution
      const distribution = [
        { category: 'Public Sale', amount: 400000000, address: 'publicSale' },
        { category: 'Team', amount: 150000000, address: 'team' },
        { category: 'Advisors', amount: 50000000, address: 'advisors' },
        { category: 'Marketing', amount: 100000000, address: 'marketing' },
        { category: 'Development', amount: 100000000, address: 'development' },
        { category: 'Liquidity', amount: 100000000, address: 'liquidity' },
        { category: 'Staking Rewards', amount: 100000000, address: 'stakingRewards' }
      ];

      console.log('\\nToken Distribution:');
      distribution.forEach(d => {
        mainToken.contract.execute('transfer', [d.address, d.amount], 'treasury');
        console.log(`${d.category}: ${d.amount / 1000000}M ECO`);
      });

      // Simulate economic activity
      console.log('\\nSimulating Economic Activity:');

      // Users buy tokens
      mainToken.contract.execute('transfer', ['user1', 1000000], 'publicSale');
      mainToken.contract.execute('transfer', ['user2', 500000], 'publicSale');
      mainToken.contract.execute('transfer', ['user3', 250000], 'publicSale');

      // Users stake tokens
      console.log('Users staking tokens...');
      stakingToken.contract.execute('mint', ['user1', 1000000], 'stakingRewards');

      // Create trading pairs
      console.log('Creating liquidity pools...');
      lpToken.contract.execute('mint', ['liquidityProvider', 1000000], 'liquidity');

      console.log('\\nEconomy Statistics:');
      console.log('Total Supply:', mainToken.contract.execute('totalSupply', [], 'anyone').result);
      console.log('Circulating Supply:', 1750000);
      console.log('Staked:', 1000000);
      console.log('Total Value Locked: $0 (No fees!)');

      await purechain.stop();
    }

    createTokenEconomy();

## 8.3 NFT Marketplace

    async function createNFTMarketplace() {
      console.log('Building NFT Marketplace');
      console.log('========================\\n');

      const purechain = new PureChain();
      await purechain.start();

      // Deploy marketplace infrastructure
      const nftCollection = await purechain.contractEngine.deployContract({
        type: ContractType.NFT,
        name: 'PureArt Gallery',
        metadata: {
          description: 'Premium digital art on PureChain',
          maxSupply: 10000,
          royaltyPercentage: 10
        }
      }, 'marketplace', 0);

      const escrow = await purechain.contractEngine.deployContract({
        type: ContractType.ESCROW,
        name: 'NFT Escrow'
      }, 'marketplace', 0);

      const storage = await purechain.contractEngine.deployContract({
        type: ContractType.STORAGE,
        name: 'Marketplace Data'
      }, 'marketplace', 0);

      console.log('Infrastructure deployed');

      // Create NFT collections
      const collections = [
        {
          name: 'Genesis Collection',
          artist: 'artist1',
          pieces: 10,
          basePrice: 1000
        },
        {
          name: 'Abstract Series',
          artist: 'artist2',
          pieces: 5,
          basePrice: 2000
        },
        {
          name: 'Digital Dreams',
          artist: 'artist3',
          pieces: 8,
          basePrice: 1500
        }
      ];

      let tokenId = 1;

      collections.forEach(collection => {
        console.log(`\\nMinting ${collection.name}:`);

        for (let i = 0; i < collection.pieces; i++) {
          const nftData = {
            tokenId: tokenId++,
            name: `${collection.name} #${i + 1}`,
            description: `Piece ${i + 1} from ${collection.name}`,
            image: `ipfs://collection${tokenId}`,
            attributes: [
              { trait_type: 'Collection', value: collection.name },
              { trait_type: 'Artist', value: collection.artist },
              { trait_type: 'Edition', value: i + 1 },
              { trait_type: 'Rarity', value: i < 2 ? 'Rare' : 'Common' }
            ]
          };

          nftCollection.contract.execute('mintNFT', [collection.artist, nftData], 'marketplace');

          // List for sale
          storage.contract.execute('set', [`listing_${nftData.tokenId}`, {
            tokenId: nftData.tokenId,
            seller: collection.artist,
            price: collection.basePrice * (i < 2 ? 2 : 1),
            listed: true,
            createdAt: Date.now()
          }], 'marketplace');

          console.log(`  Minted and listed NFT #${nftData.tokenId}`);
        }
      });

      // Simulate marketplace activity
      console.log('\\nMarketplace Activity:');

      // Purchase NFT
      const purchase1 = {
        buyer: 'collector1',
        tokenId: 1,
        price: 2000
      };

      console.log(`Collector1 purchasing NFT #${purchase1.tokenId}...`);
      nftCollection.contract.execute('transferFrom', ['artist1', purchase1.buyer, purchase1.tokenId], 'marketplace');
      storage.contract.execute('set', [`sale_${Date.now()}`, purchase1], 'marketplace');

      // Secondary sale
      console.log('Secondary market sale...');
      nftCollection.contract.execute('transferFrom', ['collector1', 'collector2', 1], 'marketplace');

      // Auction simulation
      console.log('\\nStarting auction for NFT #5:');
      const auction = {
        tokenId: 5,
        startPrice: 3000,
        endTime: Date.now() + 86400000,
        bids: []
      };

      // Place bids
      const bids = [
        { bidder: 'bidder1', amount: 3500 },
        { bidder: 'bidder2', amount: 4000 },
        { bidder: 'bidder3', amount: 4500 }
      ];

      bids.forEach(bid => {
        auction.bids.push(bid);
        console.log(`  ${bid.bidder} bids ${bid.amount}`);
      });

      storage.contract.execute('set', ['auction_5', auction], 'marketplace');

      // Marketplace statistics
      console.log('\\nMarketplace Statistics:');
      console.log('Total NFTs:', tokenId - 1);
      console.log('Total Sales:', 2);
      console.log('Active Listings:', tokenId - 3);
      console.log('Active Auctions:', 1);
      console.log('Total Volume:', 6500);
      console.log('Gas Fees Collected:', 0);

      await purechain.stop();
    }

    createNFTMarketplace();

# 9 Troubleshooting

## 9.1 Common Issues

Issue: Cannot connect to PureChain network
Solution: Check your internet connection and ensure the RPC URL is correct (https://purechainnode.com:8547)
Issue: Transaction not being mined
Solution: Ensure you call `minePendingTransactions()` after creating transactions
Issue: Contract deployment fails
Solution: Check that all required parameters are provided in the contract configuration

## 9.2 Error Messages

Error Message | Cause | Solution
--- | --- | ---
Network not found | Invalid network name | Use 'testnet', 'mainnet', or 'local'
Contract not found | Invalid contract address | Verify the contract address from deployment result
Invalid transaction | Missing required fields | Ensure from, to, amount, and timestamp are provided
Method not found | Calling non-existent contract method | Check available methods for the contract type

## 9.3 Performance Optimization

### Best Practices

- Batch transactions before mining to reduce block creation overhead
- Use memory storage for testing and development
- Implement caching for frequently accessed data
- Limit block size for faster propagation in P2P networks
- Use WebSocket connections for real-time updates instead of polling

### Configuration Optimization

    const optimizedConfig = {
      blockchain: {
        maxTransactionsPerBlock: 100,
        blockTime: 5000,
        pruneAfterBlocks: 1000
      },
      api: {
        cache: true,
        cacheTime: 60000,
        compression: true
      },
      storage: {
        type: 'indexed',
        indexFields: ['from', 'to', 'contractAddress']
      },
      network: {
        maxPeers: 50,
        messageTimeout: 5000
      }
    };

    const purechain = new PureChain(optimizedConfig);

# 10 API Reference

## 10.1 PureChain Class

### Constructor

    new PureChain(config?: IPureChainConfig)

Parameter | Type | Description
--- | --- | ---
config | IPureChainConfig | Optional configuration object

### Methods

Method | Returns | Description
--- | --- | ---
start() | Promise<void> | Initialize and connect to network
stop() | Promise<void> | Disconnect and cleanup
switchNetwork(network) | Promise<void> | Switch to different network

### Properties

Property | Type | Description
--- | --- | ---
blockchain | Blockchain | Blockchain instance
contractEngine | ContractEngine | Smart contract engine
api | BlockchainAPI | REST API server
network | PeerDiscovery | P2P network manager
database | Database | Storage interface
provider | NetworkProvider | Network connection provider
explorer | PureChainExplorer | Blockchain explorer API
networkConfig | INetworkConfig | Current network configuration

## 10.2 Blockchain Methods

Method | Parameters | Returns | Description
--- | --- | --- | ---
createTransaction | transaction: ITransaction | void | Add transaction to pending pool
minePendingTransactions | minerAddress: string | Promise<void> | Mine all pending transactions
getBalance | address: string | number | Get address balance
getLatestBlock | - | Block | Get most recent block
isChainValid | - | boolean | Validate entire blockchain

## 10.3 Contract Engine

Method | Parameters | Returns | Description
--- | --- | --- | ---
deployContract | config, deployer, balance | IDeployResult | Deploy new smart contract
getContract | address: string | SmartContract | Get contract by address
getAllContracts | - | SmartContract[] | Get all deployed contracts
executeContract | address, method, params, caller | IExecuteResult | Execute contract method

## 10.4 Network Provider

Method | Parameters | Returns | Description
--- | --- | --- | ---
connect | - | Promise<void> | Connect to network
disconnect | - | void | Disconnect from network
getBlockNumber | - | Promise<number> | Get current block number
sendTransaction | tx: ITransaction | Promise<string> | Send transaction to network
call | method, params | Promise<any> | Make RPC call

Note: This manual covers PureChainLib version 1.0.5. For the latest updates and additional features, please refer to the official documentation at https://github.com/islarpee000/purechainlib