suprana-web3

Suprana JavaScript SDK - A Solana-compatible blockchain library for the Suprana Network.

Overview

suprana-web3 is the official JavaScript SDK for interacting with the Suprana blockchain. Built on top of @solana/web3.js, it provides full Solana API compatibility while offering Suprana-specific configurations and helpers.

Features

• 100% Solana API Compatible - Use all @solana/web3.js functionality seamlessly
• Suprana Network Presets - Pre-configured connections for Mainnet, Testnet, and Devnet
• Type-Safe - Full TypeScript support with comprehensive type definitions
• SUP Token Utilities - Helper functions for SUP token conversions
• Zero Learning Curve - If you know Solana, you know Suprana

Installation

npm install suprana-web3

or

yarn add suprana-web3

or

pnpm add suprana-web3

Quick Start

Connecting to Suprana Testnet

import { createSupranaConnection } from 'suprana-web3'

// Connect to Suprana testnet
const connection = createSupranaConnection('testnet')

// Get current slot
const slot = await connection.getSlot()
console.log('Current slot:', slot)

// Get network version
const version = await connection.getVersion()
console.log('Network version:', version)

Using Network Helpers

import { getSupranaTestnet, getSupranaMainnet } from 'suprana-web3'

// Quick testnet connection
const testnet = getSupranaTestnet()

// Quick mainnet connection
const mainnet = getSupranaMainnet()

Working with Accounts

import {
  createSupranaConnection,
  Keypair,
  PublicKey,
  lamportsToSup
} from 'suprana-web3'

const connection = createSupranaConnection('testnet')

// Generate a new keypair
const keypair = Keypair.generate()
console.log('Public key:', keypair.publicKey.toBase58())

// Get account balance
const publicKey = new PublicKey('YourPublicKeyHere...')
const balance = await connection.getBalance(publicKey)
console.log('Balance:', lamportsToSup(balance), 'SUP')

Sending Transactions

import {
  createSupranaConnection,
  Keypair,
  PublicKey,
  Transaction,
  SystemProgram,
  supToLamports,
  sendAndConfirmTransaction
} from 'suprana-web3'

const connection = createSupranaConnection('testnet')
const fromKeypair = Keypair.fromSecretKey(yourSecretKey)
const toPublicKey = new PublicKey('RecipientPublicKey...')

// Create transfer transaction
const transaction = new Transaction().add(
  SystemProgram.transfer({
    fromPubkey: fromKeypair.publicKey,
    toPubkey: toPublicKey,
    lamports: supToLamports(1.5), // Send 1.5 SUP
  })
)

// Send and confirm transaction
const signature = await sendAndConfirmTransaction(
  connection,
  transaction,
  [fromKeypair]
)

console.log('Transaction signature:', signature)

Custom RPC Endpoint

import { createCustomSupranaConnection } from 'suprana-web3'

const connection = createCustomSupranaConnection('https://your-custom-rpc.suprana.net')

API Reference

Network Connections

createSupranaConnection(network?, config?)

Create a connection to a Suprana network.

Parameters:

• network (optional): 'mainnet' | 'testnet' | 'devnet' - Default: 'testnet'
• config (optional): ConnectionConfig - Custom connection configuration

Returns: Connection

Example:

const connection = createSupranaConnection('testnet')

createCustomSupranaConnection(endpoint, config?)

Create a connection to a custom Suprana RPC endpoint.

Parameters:

• endpoint: string - Custom RPC endpoint URL
• config (optional): ConnectionConfig - Custom connection configuration

Returns: Connection

getSupranaTestnet()

Quick helper to get a testnet connection.

Returns: Connection

getSupranaMainnet()

Quick helper to get a mainnet connection.

Returns: Connection

Token Utilities

supToLamports(sup)

Convert SUP tokens to lamports.

Parameters:

• sup: number - Amount in SUP

Returns: number - Amount in lamports

Example:

const lamports = supToLamports(1.5) // 1500000000

lamportsToSup(lamports)

Convert lamports to SUP tokens.

Parameters:

• lamports: number - Amount in lamports

Returns: number - Amount in SUP

Example:

const sup = lamportsToSup(1500000000) // 1.5

Constants

SUPRANA_NETWORKS

Object containing all Suprana network endpoints:

{
  mainnet: 'https://api.mainnet.suprana.network',
  testnet: 'https://api.testnet.suprana.network',
  devnet: 'https://api.devnet.suprana.network',
}

SUPRANA_CONSTANTS

Suprana-specific constants:

{
  NATIVE_TOKEN_SYMBOL: 'SUP',
  LAMPORTS_PER_SUP: 1000000000,
  SLOTS_PER_EPOCH: 432000,
  TARGET_SLOT_TIME_MS: 400,
}

Solana Compatibility

Since Suprana is Solana-compatible, you can use all @solana/web3.js functionality directly:

import {
  Connection,
  PublicKey,
  Transaction,
  SystemProgram,
  Keypair,
  // ... any @solana/web3.js export
} from 'suprana-web3'

All Solana APIs work the same way on Suprana. The main differences are:

1. Network endpoints - Use Suprana RPC endpoints
2. Token symbol - SUP instead of SOL
3. Pre-configured helpers - Suprana-specific convenience functions

Examples

Get Block Information

import { createSupranaConnection } from 'suprana-web3'

const connection = createSupranaConnection('testnet')

const slot = await connection.getSlot()
const block = await connection.getBlock(slot)

console.log('Block:', block)
console.log('Transactions:', block?.transactions.length)

Get Account Info

import { createSupranaConnection, PublicKey } from 'suprana-web3'

const connection = createSupranaConnection('testnet')
const publicKey = new PublicKey('YourPublicKeyHere...')

const accountInfo = await connection.getAccountInfo(publicKey)

if (accountInfo) {
  console.log('Owner:', accountInfo.owner.toBase58())
  console.log('Lamports:', accountInfo.lamports)
  console.log('Executable:', accountInfo.executable)
}

Subscribe to Account Changes

import { createSupranaConnection, PublicKey } from 'suprana-web3'

const connection = createSupranaConnection('testnet')
const publicKey = new PublicKey('YourPublicKeyHere...')

const subscriptionId = connection.onAccountChange(
  publicKey,
  (accountInfo) => {
    console.log('Account updated!')
    console.log('New balance:', accountInfo.lamports)
  },
  'confirmed'
)

// Later: unsubscribe
// await connection.removeAccountChangeListener(subscriptionId)

Get Recent Performance Samples

import { createSupranaConnection } from 'suprana-web3'

const connection = createSupranaConnection('testnet')
const samples = await connection.getRecentPerformanceSamples(10)

samples.forEach(sample => {
  console.log('Slot:', sample.slot)
  console.log('TPS:', sample.numTransactions / sample.samplePeriodSecs)
})

TypeScript Support

This library is written in TypeScript and includes full type definitions:

import {
  Connection,
  SupranaNetwork,
  ConnectionConfig
} from 'suprana-web3'

const network: SupranaNetwork = 'testnet'
const config: ConnectionConfig = { commitment: 'confirmed' }
const connection: Connection = createSupranaConnection(network, config)

Network Endpoints

| Network | Endpoint | |---------|----------| | Mainnet | https://mainnet.suprana.net | | Testnet | https://testnet.suprana.net | | Devnet | https://devnet.suprana.net |

Error Handling

import { createSupranaConnection, PublicKey } from 'suprana-web3'

const connection = createSupranaConnection('testnet')

try {
  const balance = await connection.getBalance(
    new PublicKey('InvalidPublicKey')
  )
} catch (error) {
  console.error('Error getting balance:', error)
}

Migration from @solana/web3.js

If you have existing Solana code, migrating to Suprana is simple:

// Before (Solana)
import { Connection } from '@solana/web3.js'
const connection = new Connection('https://api.devnet.solana.com')

// After (Suprana)
import { createSupranaConnection } from 'suprana-web3'
const connection = createSupranaConnection('testnet')

// Or use all the same @solana/web3.js APIs
import { Connection } from 'suprana-web3'
const connection = new Connection('https://testnet.suprana.net')

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - see LICENSE file for details

Support

• Documentation: https://docs.suprana.network
• GitHub: https://github.com/Suprana-Labs/suprana-web3js
• Issues: https://github.com/Suprana-Labs/suprana-web3js/issues
• Discord: https://discord.gg/suprana

Acknowledgments

Built on top of the excellent @solana/web3.js library.