LBB Certificate SDK

A comprehensive TypeScript SDK for managing LBB Gold Certificate NFTs on the SixProtocol blockchain. This SDK provides dual-chain support for both Cosmos and EVM operations, enabling seamless certificate lifecycle management including deployment, minting, querying, and freeze/unfreeze operations.

Installation

npm install lbb-certificate-sdk
# or
yarn add lbb-certificate-sdk

Features

• 🪙 Dual-Chain Support: Manage certificates on both Cosmos and EVM chains
• 🔐 Wallet Management: Support for mnemonic, private key, and random wallet creation
• 📜 Schema Deployment: Deploy NFT schemas on Cosmos blockchain
• 🏗️ Contract Deployment: Deploy EVM NFT contracts with automatic linking
• 🎯 Smart Minting: Automatic and manual token ID strategies
• 🧊 Freeze/Unfreeze: Certificate collateralization management
• 💰 Balance Queries: Check wallet balances across both chains
• 📊 Analytics: Schema statistics and metadata retrieval
• 🔍 Query Operations: Comprehensive blockchain data querying

Quick Start

import { LBBCertificateSDK } from 'lbb-certificate-sdk';

// Initialize SDK
const sdk = new LBBCertificateSDK({
    network: 'fivenet', // or 'sixnet'
    mnemonic: 'your twelve word mnemonic phrase here...'
});

// Initialize the wallet
await sdk.initialize();

// Deploy a new certificate schema
const deployResult = await sdk.deployCertificateSchema({
    name: 'My Gold Certificate'
});

// Mint a certificate
const mintResult = await sdk.mintCertificateNFT({
    schemaCode: deployResult.schemaCode,
    certificateDetails: {
        status: 'TCI',
        gold_standard: 'LBI',
        weight: 'hash_value_here',
        cert_number: 'CERT001',
        customer_id: 'CUST001',
        issue_date: new Date().toISOString()
    }
});

Configuration

SDK Initialization Options

interface LBBSDKConfig {
    network: 'fivenet' | 'sixnet';
    privateKey?: string;        // EVM private key
    mnemonic?: string;          // 12-word mnemonic phrase
    useRandomWallet?: boolean;  // Generate random wallet if no keys provided
}

// Method 1: Using configuration object (recommended)
const sdk = new LBBCertificateSDK({
    network: 'fivenet',
    mnemonic: 'your mnemonic here'
});

// Method 2: Legacy constructor
const sdk = new LBBCertificateSDK(
    'private_key_here',    // EVM private key (optional)
    'mnemonic_here',       // Mnemonic (optional)  
    'fivenet'              // Network
);

Networks

• fivenet: Testnet environment for development and testing
• sixnet: Mainnet environment for production

Core Operations

1. Schema Management

Deploy Certificate Schema

const deployResult = await sdk.deployCertificateSchema({
    name: 'LBB Gold Certificate',           // Schema name
    organizationId: 'my-org',               // Optional organization ID
    tokenIdStrategy: 'auto'                 // 'auto' or 'manual'
});

console.log('Schema Code:', deployResult.schemaCode);
console.log('Transaction Hash:', deployResult.txHash);

Get Schema Information

// Get schema details from blockchain
const schemaInfo = await sdk.getNFTSchema('fivenet', 'SCHEMA_CODE');

// Get comprehensive schema statistics
const stats = await sdk.getSchemaStats('SCHEMA_CODE');
console.log('Total Tokens:', stats.totalTokens);
console.log('Next Token ID:', stats.nextAvailableTokenId);

// Get schema info with recommendations
const info = await sdk.getSchemaInfo('SCHEMA_CODE');
console.log('Recommendations:', info.recommendations);

Get All User Schemas

// Get all schemas owned by current wallet
const mySchemas = await sdk.getAllSchemas();

// Get schemas for specific address
const schemas = await sdk.getAllSchemas('fivenet', '6x1abc...def');

2. Certificate Minting

Mint Certificate on Cosmos

const mintResult = await sdk.mintCertificateNFT({
    schemaCode: 'YOUR_SCHEMA_CODE',
    tokenId: '1',                    // Optional - auto-generated if not provided
    certificateDetails: {
        status: 'TCI',               // 'TCI' (active) or 'TCL' (collateralized)
        gold_standard: 'LBI',        // 'LBI' or 'LBA'
        weight: 'weight_hash',       // Weight hash value
        cert_number: 'CERT001',      // Certificate number
        customer_id: 'CUST001',      // Customer identifier
        issue_date: '2024-01-01T00:00:00Z'
    },
    recipientAddress: '6x1abc...def', // Optional - defaults to wallet address
    imageUrl: 'https://...',          // Optional custom image
    tokenIdStrategy: 'auto'           // Override default strategy
});

Certificate Details Interface

interface CertificateDetails {
    status: 'TCI' | 'TCL';           // TCI = Active, TCL = Collateralized
    gold_standard: 'LBI' | 'LBA';    // Gold standard classification  
    weight: string;                   // Weight hash (not actual weight)
    cert_number: string;             // Certificate number
    cert_numberHash?: string;        // Optional hash of cert number
    customer_id: string;             // Customer ID
    customer_idHash?: string;        // Optional hash of customer ID
    issue_date: string;              // ISO date string
}

3. Token ID Strategies

The SDK supports two token ID strategies:

• Auto: Sequential numbering (1, 2, 3, ...)
• Manual: User-provided custom IDs

// Set strategy for a schema
sdk.setTokenIdStrategy('SCHEMA_CODE', 'manual');

// Get current strategy
const strategy = await sdk.getTokenIdStrategy('SCHEMA_CODE');

// The SDK automatically detects strategy based on existing tokens
// First token sets the pattern for the entire schema

4. Freeze/Unfreeze Operations

// Freeze certificate (collateralize)
const freezeResult = await sdk.freezeCertificate({
    schemaCode: 'SCHEMA_CODE',
    tokenId: '1'
});

// Unfreeze certificate (make available)
const unfreezeResult = await sdk.unfreezeCertificate({
    schemaCode: 'SCHEMA_CODE', 
    tokenId: '1'
});

5. EVM Operations

Deploy EVM Contract

const evmResult = await sdk.deployEvmContract({
    contractName: 'LBB Gold Certificate',
    contractSymbol: 'LBBGOLD',
    contractMetadataURI: 'https://...'
});

Mint on EVM

const evmMintResult = await sdk.mintEvmCertificateNFT({
    tokenId: '1',
    contractAddress: '0x123...',
    recipientAddress: '0x456...'
});

Combined Deployment

Deploy both Cosmos schema and EVM contract together:

const result = await sdk.deployNFT({
    name: 'LBB Gold Certificate',
    symbol: 'LBBGOLD',
    contractMetadataURI: 'https://metadata.uri'
});

console.log('Schema Code:', result.schemaCode);
console.log('Contract Address:', result.contractAddress);

6. Wallet & Balance Operations

Get Wallet Information

// Get wallet addresses
const cosmosAddress = sdk.getCosmosAddress();
const evmAddress = sdk.getEvmAddress();
const mnemonic = sdk.getMnemonic(); // Be careful with this in production

// Check if SDK is ready
const isReady = sdk.isReady();

Check Balances

// Get Cosmos balance (USIX tokens)
const cosmosBalance = await sdk.getCosmosBalance();
console.log(`Balance: ${cosmosBalance.balance} ${cosmosBalance.denom}`);

// Get EVM balance (native tokens)
const evmBalance = await sdk.getEvmBalance();
console.log(`Balance: ${evmBalance.balanceFormatted} ${evmBalance.symbol}`);

// Get both balances
const allBalances = await sdk.getAllBalances();

7. Query Operations

Get NFT Metadata

const metadata = await sdk.getNFTMetadata('fivenet', 'SCHEMA_CODE', '1');
if (metadata.success) {
    console.log('NFT Data:', metadata.metadata);
}

Get Token Statistics

// Get next available token ID
const nextToken = await sdk.getNextAvailableTokenId('SCHEMA_CODE');

// Get current token count
const count = await sdk.getCurrentTokenCount('SCHEMA_CODE');

Utility Functions

Schema Name Transformation

// Transform schema code to readable name
const readableName = sdk.transformSchemaCodeToName('LBB_GOLD_CERTIFICATE');
// Returns: "LBB Gold Certificate"

// Handle organization prefixes
const orgName = sdk.transformSchemaCodeToName('sixprotocol.dual_chain_gold_nft');  
// Returns: "Sixprotocol Dual Chain Gold NFT"

Error Handling

The SDK uses consistent error handling patterns:

try {
    const result = await sdk.mintCertificateNFT(config);
    if (result.success) {
        console.log('Success:', result.data);
    } else {
        console.error('Error:', result.error);
    }
} catch (error) {
    console.error('Exception:', error.message);
}

Network Configuration

The SDK automatically configures network settings:

// Fivenet (Testnet)
- Cosmos RPC: https://rpc1.fivenet.sixprotocol.net:443
- Cosmos API: https://api1.fivenet.sixprotocol.net:443  
- EVM RPC: https://rpc-evm.fivenet.sixprotocol.net
- Native Token: USIX (Cosmos), SIX (EVM)

// Sixnet (Mainnet)
- Cosmos RPC: https://sixnet-rpc.sixprotocol.net
- Cosmos API: https://sixnet-api.sixprotocol.net
- EVM RPC: https://sixnet-rpc-evm.sixprotocol.net
- Native Token: USIX (Cosmos), SIX (EVM)

Best Practices

1. Wallet Security

// ✅ Good: Use environment variables
const sdk = new LBBCertificateSDK({
    network: 'fivenet',
    mnemonic: process.env.WALLET_MNEMONIC
});

// ❌ Bad: Hard-code credentials
const sdk = new LBBCertificateSDK({
    network: 'fivenet', 
    mnemonic: 'word1 word2 word3...' // Never do this!
});

2. Error Handling

// Always check for success before accessing data
const result = await sdk.mintCertificateNFT(config);
if (!result.success) {
    throw new Error(`Mint failed: ${result.error}`);
}

3. Token ID Management

// Let the SDK handle token IDs for consistency
const mintConfig = {
    schemaCode: 'SCHEMA_CODE',
    certificateDetails: details
    // Don't specify tokenId - let SDK auto-generate
};

4. Network Selection

// Use testnet for development
const devSdk = new LBBCertificateSDK({ network: 'fivenet' });

// Use mainnet for production  
const prodSdk = new LBBCertificateSDK({ network: 'sixnet' });

Examples

Complete Certificate Lifecycle

import { LBBCertificateSDK } from 'lbb-certificate-sdk';

async function certificateLifecycle() {
    // 1. Initialize SDK
    const sdk = new LBBCertificateSDK({
        network: 'fivenet',
        mnemonic: process.env.MNEMONIC
    });
    await sdk.initialize();

    // 2. Deploy schema
    const schema = await sdk.deployCertificateSchema({
        name: 'Premium Gold Certificate'
    });
    
    // 3. Mint certificate
    const mint = await sdk.mintCertificateNFT({
        schemaCode: schema.schemaCode,
        certificateDetails: {
            status: 'TCI',
            gold_standard: 'LBI', 
            weight: 'hash123',
            cert_number: 'PREM001',
            customer_id: 'CUST001',
            issue_date: new Date().toISOString()
        }
    });

    // 4. Query certificate
    const metadata = await sdk.getNFTMetadata(
        'fivenet', 
        schema.schemaCode, 
        mint.tokenId
    );

    // 5. Freeze certificate (collateralize)
    await sdk.freezeCertificate({
        schemaCode: schema.schemaCode,
        tokenId: mint.tokenId
    });

    console.log('Certificate lifecycle completed!');
}

Batch Operations

async function batchMint() {
    const sdk = new LBBCertificateSDK({
        network: 'fivenet',
        mnemonic: process.env.MNEMONIC
    });
    await sdk.initialize();

    const certificates = [
        { cert_number: 'CERT001', customer_id: 'CUST001' },
        { cert_number: 'CERT002', customer_id: 'CUST002' },
        { cert_number: 'CERT003', customer_id: 'CUST003' }
    ];

    const results = [];
    for (const cert of certificates) {
        const result = await sdk.mintCertificateNFT({
            schemaCode: 'YOUR_SCHEMA_CODE',
            certificateDetails: {
                status: 'TCI',
                gold_standard: 'LBI',
                weight: 'hash_value',
                cert_number: cert.cert_number,
                customer_id: cert.customer_id,
                issue_date: new Date().toISOString()
            }
        });
        results.push(result);
    }

    console.log(`Minted ${results.length} certificates`);
}

API Reference

Class: LBBCertificateSDK

Constructor

• new LBBCertificateSDK(config: LBBSDKConfig)
• new LBBCertificateSDK(privateKey?, mnemonic?, network?) (legacy)

Core Methods

• initialize(): Promise<void>
• deployCertificateSchema(config): Promise<DeployResult>
• mintCertificateNFT(config): Promise<MintResult>
• freezeCertificate(config): Promise<ActionResult>
• unfreezeCertificate(config): Promise<ActionResult>

Query Methods

• getNFTSchema(network?, schemaCode?): Promise<SchemaResult>
• getNFTMetadata(network?, schemaCode?, tokenId?): Promise<MetadataResult>
• getAllSchemas(network?, ownerAddress?): Promise<SchemasResult>
• getSchemaStats(schemaCode): Promise<StatsResult>
• getSchemaInfo(schemaCode): Promise<InfoResult>

Wallet Methods

• getCosmosBalance(): Promise<BalanceResult>
• getEvmBalance(): Promise<BalanceResult>
• getAllBalances(): Promise<AllBalancesResult>
• getCosmosAddress(): string | null
• getEvmAddress(): string | null

Utility Methods

• transformSchemaCodeToName(schemaCode): string
• setTokenIdStrategy(schemaCode, strategy): void
• getTokenIdStrategy(schemaCode): Promise<TokenIdStrategy>
• isReady(): boolean

Development

Install Dependencies

npm install

Build

npm run build

Test

npm test

Lint

npm run lint

Format

npm run format

Changelog

v1.0.0

• Initial release with dual-chain support
• Complete certificate lifecycle management
• Automatic token ID strategies
• Comprehensive query operations

License

MIT License - see LICENSE file for details.

Support

For issues and questions:

• GitHub Issues: Repository Issues
• Documentation: SDK Documentation

Contributing

Contributions are welcome! Please read our contributing guidelines and submit pull requests to the development branch.