Ruby Web3 Manager

A comprehensive Web3 manager for Ruby Chain support. This package provides easy-to-use methods for wallet management, token operations, smart contract interactions, and transaction monitoring.

Features

• 🔐 Wallet Management - Create and manage Ruby format wallets
• 💰 Balance Checking - Get native token and RBC20 token balances
• 📝 Transaction Operations - Send native tokens and interact with smart contracts
• 🪙 Token Operations - Full RBC20 token support (transfer, balance, approve)
• 🖼️ NFT Support - RBC721 NFT transfers and ownership checks
• 📊 Transaction Details - Comprehensive transaction decoding and event parsing
• ✉️ Message Signing - Sign and verify messages for authentication

Installation

npm install ruby-web3-manager

Quick Start

const RubyWeb3Manager = require("ruby-web3-manager");

// Initialize with Ruby Mainnet
const manager = new RubyWeb3Manager("RUBY_MAINNET");



## Supported Networks

- `RUBY_MAINNET` - Ruby Chain Mainnet
- `RUBY_TESTNET` - Ruby Chain Testnet


## Wallet Management

### Create New Wallet

```javascript
// Create a new wallet with Ruby format addresses
const wallet = manager.createWallet();

console.log("Ruby Address:", wallet.address);
// Example: r742d6a4b6e1a3b2a69de6dbf7f01ed13b2108b2c

console.log("Private Key:", wallet.privateKey);
// Example: rPVT_abc123... (Ruby format private key)

Validate Address

// Check if an address is valid (both Ruby and Hex formats supported)
const isValid = manager.validateAddress(
  "r742d6a4b6e1a3b2a69de6dbf7f01ed13b2108b2c"
);
console.log("Is valid address:", isValid); // true or false

Balance Operations

Get Native Token Balance

// Get balance for Ruby format address
const balance = await manager.getBalance(
  "r742d6a4b6e1a3b2a69de6dbf7f01ed13b2108b2c"
);

console.log("Balance Details:", {
  address: balance.address, // Ruby format
  balanceRuby: balance.balanceRuby, // Human readable
  balanceWei: balance.balanceWei, // Wei amount
  network: balance.network,
});

// Example output:
// {
//   address: 'r742d6a4b6e1a3b2a69de6dbf7f01ed13b2108b2c',
//   balanceRuby: '2.5',
//   balanceWei: '2500000000000000000',
//   network: 'RUBY_MAINNET'
// }

Get RBC20 Token Balance

// Get token balance for a wallet
const tokenBalance = await manager.getTokenBalance(
  "r89205a3a3b2a69de6dbf7f01ed13b2108b2c43e7", // Token address
  "r742d6a4b6e1a3b2a69de6dbf7f01ed13b2108b2c" // Wallet address
);

console.log("Token Balance:", {
  balance: tokenBalance.balance, // Human readable
  balanceRaw: tokenBalance.balanceRaw, // Raw amount
  symbol: tokenBalance.symbol, // Token symbol
  name: tokenBalance.name, // Token name
  decimals: tokenBalance.decimals, // Token decimals
  walletAddress: tokenBalance.walletAddress, // Ruby format
  tokenAddress: tokenBalance.tokenAddress, // Ruby format
});

// Example output:
// {
//   balance: '100.5',
//   balanceRaw: '100500000000000000000',
//   symbol: 'USDT',
//   name: 'Tether USD',
//   decimals: 18,
//   walletAddress: 'r742d6a4b6e1a3b2a69de6dbf7f01ed13b2108b2c',
//   tokenAddress: 'r89205a3a3b2a69de6dbf7f01ed13b2108b2c43e7'
// }

Transaction Operations

Send Native Tokens

// Send RUBY tokens
const receipt = await manager.sendCoin(
  "r742d6a4b6e1a3b2a69de6dbf7f01ed13b2108b2c", // From address
  "rPVT_abc123...", // Private key (Ruby format)
  "r89205a3a3b2a69de6dbf7f01ed13b2108b2c43e7", // To address
  "1.5", // Amount in RUBY
  {
    gasLimit: 21000, // Optional gas limit
    gasPrice: "20", // Optional gas price in gwei
  }
);

console.log("Transaction Receipt:", {
  transactionHash: receipt.transactionHash, // Ruby format hash
  from: receipt.from, // Ruby format
  to: receipt.to, // Ruby format
  amount: receipt.amount,
  status: receipt.status, // 'success' or 'failed'
  blockNumber: receipt.blockNumber,
  gasUsed: receipt.gasUsed,
});

// Example output:
// {
//   transactionHash: 'rH16179f121cef19f4a1f063a63846d87fa6508a09a5300a3bbeb5ec6392c3798d',
//   from: 'r742d6a4b6e1a3b2a69de6dbf7f01ed13b2108b2c',
//   to: 'r89205a3a3b2a69de6dbf7f01ed13b2108b2c43e7',
//   amount: '1.5',
//   status: 'success',
//   blockNumber: 2924534,
//   gasUsed: '21000'
// }

Transfer RBC20 Tokens

// Transfer RBC20 tokens
const transferReceipt = await manager.transferToken(
  "r742d6a4b6e1a3b2a69de6dbf7f01ed13b2108b2c", // From address
  "rPVT_abc123...", // Private key
  "r89205a3a3b2a69de6dbf7f01ed13b2108b2c43e7", // Token address
  "rae0ccf50794dce11741a0d68046076f563ca089d", // To address
  "100.5", // Amount
  {
    gasLimit: 65000, // Optional gas limit for token transfers
  }
);

console.log("Token Transfer Receipt:", transferReceipt);

Approve RBC20 Token Spending

// Approve another address to spend your tokens
const approveReceipt = await manager.approveToken(
  "r742d6a4b6e1a3b2a69de6dbf7f01ed13b2108b2c", // From address
  "rPVT_abc123...", // Private key
  "r89205a3a3b2a69de6dbf7f01ed13b2108b2c43e7", // Token address
  "r875c1c66cfeaccb3547836f1c27487194b6c78f0", // Spender address
  "500", // Amount to approve
  {
    gasLimit: 45000,
  }
);

console.log("Approval Receipt:", approveReceipt);

Smart Contract Interactions

Call Contract View Functions (Read)

// Call a read-only contract function
const result = await manager.callContractFunction(
  "r2c804eaa07194cbe7e9524db2614ad8f31d5e649", // Contract address
  [
    {
      constant: true,
      inputs: [{ name: "_owner", type: "address" }],
      name: "balanceOf",
      outputs: [{ name: "balance", type: "uint256" }],
      type: "function",
    },
  ], // Contract ABI
  "balanceOf", // Function name
  ["r742d6a4b6e1a3b2a69de6dbf7f01ed13b2108b2c"] // Parameters
);

console.log("Contract Call Result:", result);

Send Contract Transaction (Write)

// Execute a state-changing contract function
const contractReceipt = await manager.sendContractTransaction(
  "r742d6a4b6e1a3b2a69de6dbf7f01ed13b2108b2c", // From address
  "rPVT_abc123...", // Private key
  "r2c804eaa07194cbe7e9524db2614ad8f31d5e649", // Contract address
  [
    {
      constant: false,
      inputs: [
        { name: "_to", type: "address" },
        { name: "_value", type: "uint256" },
      ],
      name: "transfer",
      outputs: [{ name: "", type: "bool" }],
      type: "function",
    },
  ], // Contract ABI
  "transfer", // Function name
  [
    "rae0ccf50794dce11741a0d68046076f563ca089d", // _to parameter
    "1000000000000000000", // _value parameter (1 token in wei)
  ], // Function parameters
  {
    gasLimit: 100000,
  }
);

console.log("Contract Transaction Receipt:", contractReceipt);

Deploy New Contract

// Deploy a new smart contract
const deployment = await manager.deployContract(
  'r742d6a4b6e1a3b2a69de6dbf7f01ed13b2108b2c', // From address
  'rPVT_abc123...', // Private key
  [...], // Contract ABI
  '0x606060...', // Contract bytecode
  ['param1', 'param2'], // Constructor arguments
  {
    gasLimit: 2000000
  }
);

console.log('Contract Deployment:', {
  contractAddress: deployment.contractAddress, // Ruby format
  transactionHash: deployment.transactionHash, // Ruby format
  status: deployment.status
});

NFT Operations

Transfer RBC721 NFT

// Transfer an NFT
const nftReceipt = await manager.transferNFT721(
  "r742d6a4b6e1a3b2a69de6dbf7f01ed13b2108b2c", // From address
  "rPVT_abc123...", // Private key
  "r89205a3a3b2a69de6dbf7f01ed13b2108b2c43e7", // NFT contract address
  "r742d6a4b6e1a3b2a69de6dbf7f01ed13b2108b2c", // From (current owner)
  "rae0ccf50794dce11741a0d68046076f563ca089d", // To (new owner)
  "123", // Token ID
  {
    gasLimit: 85000,
  }
);

console.log("NFT Transfer Receipt:", nftReceipt);

Get NFT Owner

// Check who owns an NFT
const ownerInfo = await manager.getNFT721Owner(
  "r89205a3a3b2a69de6dbf7f01ed13b2108b2c43e7", // NFT contract address
  "123" // Token ID
);

console.log("NFT Owner:", ownerInfo.owner); // Ruby format address

Transaction Details

Get Transaction Details

// Get comprehensive transaction details
const txDetails = await manager.getTransactionDetails(
  "rH16179f121cef19f4a1f063a63846d87fa6508a09a5300a3bbeb5ec6392c3798d" // Ruby format hash
);

console.log("Transaction Details:", {
  hash: txDetails.hash, // Ruby format
  from: txDetails.from, // Ruby format
  to: txDetails.to, // Ruby format
  value: txDetails.value, // ETH/RUBY value
  status: txDetails.status,
  blockNumber: txDetails.blockNumber,
  gasUsed: txDetails.gasUsed,
  displayValue: txDetails.displayValue, // Prioritizes token transfers
  functionCall: txDetails.functionCall, // Decoded contract call
  events: txDetails.events, // Decoded events
});

// Example events array:
// [
//   {
//     name: 'Transfer',
//     address: 'r2c804eaa07194cbe7e9524db2614ad8f31d5e649',
//     parameters: {
//       from: 'r875c1c66cfeaccb3547836f1c27487194b6c78f0',
//       to: 'rae0ccf50794dce11741a0d68046076f563ca089d',
//       value: '0.149681084089949856'
//     },
//     logIndex: '0',
//     transactionIndex: '0',
//     blockNumber: '2924534'
//   }
// ]

Utility Functions

Estimate Gas

// Estimate gas cost for a transaction
const gasEstimate = await manager.estimateGas(
  "r742d6a4b6e1a3b2a69de6dbf7f01ed13b2108b2c", // From
  "r89205a3a3b2a69de6dbf7f01ed13b2108b2c43e7", // To
  "1.0", // Value
  "0x" // Data
);

console.log("Gas Estimate:", gasEstimate.gasEstimate);

Get Transaction Count (Nonce)

// Get the next nonce for an address
const nonceInfo = await manager.getTransactionCount(
  "r742d6a4b6e1a3b2a69de6dbf7f01ed13b2108b2c"
);

console.log("Nonce:", nonceInfo.nonce);

Sign and Verify Messages

// Sign a message
const signature = await manager.signMessage(
  "rPVT_abc123...", // Private key
  "Hello, World!" // Message to sign
);

console.log("Signature:", {
  signature: signature.signature,
  messageHash: signature.messageHash,
});

// Verify a signed message
const verification = await manager.verifySignedMessage(
  "Hello, World!", // Original message
  signature.signature, // Signature
  "r742d6a4b6e1a3b2a69de6dbf7f01ed13b2108b2c" // Expected address
);

console.log("Signature Valid:", verification.isValid);

Network Information

Get Current Block Number

const blockNumber = await manager.getBlockNumber();
console.log("Current Block:", blockNumber);

Get Gas Price

const gasPrice = await manager.getGasPrice();
console.log("Current Gas Price:", gasPrice, "gwei");

Error Handling

All methods use try-catch for proper error handling:

try {
  const balance = await manager.getBalance(
    "r742d6a4b6e1a3b2a69de6dbf7f01ed13b2108b2c"
  );
  console.log("Balance:", balance);
} catch (error) {
  console.error("Error getting balance:", error.message);
}

try {
  const receipt = await manager.sendCoin(
    fromAddress,
    privateKey,
    toAddress,
    amount
  );
  console.log("Transaction successful:", receipt.transactionHash);
} catch (error) {
  console.error("Transaction failed:", error.message);
}

Common Use Cases

Complete Token Transfer Flow

async function transferTokens() {
  try {
    const manager = new RubyWeb3Manager("RUBY_MAINNET");

    // 1. Check token balance first
    const tokenBalance = await manager.getTokenBalance(
      "r89205a3a3b2a69de6dbf7f01ed13b2108b2c43e7",
      "r742d6a4b6e1a3b2a69de6dbf7f01ed13b2108b2c"
    );

    console.log(
      `Current ${tokenBalance.symbol} balance:`,
      tokenBalance.balance
    );

    // 2. Transfer tokens
    const receipt = await manager.transferToken(
      "r742d6a4b6e1a3b2a69de6dbf7f01ed13b2108b2c",
      "rPVT_abc123...",
      "r89205a3a3b2a69de6dbf7f01ed13b2108b2c43e7",
      "rae0ccf50794dce11741a0d68046076f563ca089d",
      "50.0"
    );

    console.log(
      "Transfer successful! Transaction hash:",
      receipt.transactionHash
    );

    // 3. Wait and check transaction details
    setTimeout(async () => {
      const txDetails = await manager.getTransactionDetails(
        receipt.transactionHash
      );
      console.log("Transaction status:", txDetails.status);
      console.log("Gas used:", txDetails.gasUsed);
    }, 30000);
  } catch (error) {
    console.error("Transfer failed:", error.message);
  }
}

Security Notes

• 🔒 Never commit private keys to version control
• 🔒 Use environment variables for sensitive data
• 🔒 Validate all inputs before processing
• 🔒 Use testnets for development and testing

License

MIT

Happy Building! 🚀