Solbids SDK

A TypeScript SDK for integrating with Solbids Layer 2 auction infrastructure on Solana.

Features

• 🏗️ Layer 2 Auction Infrastructure: Off-chain bidding with on-chain settlement
• 🌳 Merkle Tree Proofs: Cryptographic verification of bid inclusion
• 🔐 Secure Verification: On-chain result validation and dispute resolution
• ⚡ Real-time Updates: WebSocket support for live auction data
• 🛡️ Type Safety: Full TypeScript support with comprehensive type definitions

Installation

npm install @solbids/sdk
# or
yarn add @solbids/sdk

Quick Start

import { SolbidsSDK, generateAuctionId } from '@solbids/sdk';

// Initialize SDK
const sdk = new SolbidsSDK({
    rpcUrl: 'https://api.devnet.solana.com',
    programId: 'YOUR_PROGRAM_ID',
    backendUrl: 'https://api.solbids.com',
    commitment: 'confirmed'
});

await sdk.initialize();

// Create an auction
const auctionId = generateAuctionId();
const auction = await sdk.createAuction({
    startTime: Date.now() / 1000,
    endTime: Date.now() / 1000 + 3600, // 1 hour
    minBid: 1_000_000, // 0.001 SOL
    metadata: 'Epic NFT Auction'
}, creatorKeypair);

// Place a bid
const bid = await sdk.placeBid(
    auction.auctionId,
    2_000_000, // 0.002 SOL
    bidderKeypair
);

// End auction and get results
const bids = [
    { bidder: 'Bidder1Address', amount: 2_000_000, timestamp: Date.now() / 1000 },
    // ... more bids
];

const result = await sdk.endAuction(auction.auctionId, bids);
console.log('Winner:', result.winner, 'Final Amount:', result.finalAmount);

// Verify bid proof
const proof = sdk.getBidProof(auction.auctionId, bids, 0);
const isValid = await sdk.verifyBidProof(
    auction.auctionId,
    bids[0].bidder,
    bids[0].amount,
    bids[0].timestamp,
    proof
);

Architecture

Solbids implements a Layer 2 auction protocol with the following components:

Off-Chain Layer (Fast Execution)

• Real-time Bidding: WebSocket connections for instant bid updates
• State Management: PostgreSQL + Redis for auction and bid storage
• Merkle Trees: Cryptographic proofs for bid verification

On-Chain Layer (Final Settlement)

• State Commitment: Auction results committed to Solana blockchain
• Verification: On-chain programs verify Merkle proofs
• Settlement: Funds transferred based on verified results

Security Model

• Operator Authority: Authorized backend can commit results
• Merkle Proofs: Verify individual bids without revealing all data
• Dispute Resolution: Challenge mechanism for invalid bids
• Emergency Controls: Pause functionality for security incidents

API Reference

Core Classes

SolbidsSDK

Main SDK class for interacting with Solbids infrastructure.

const sdk = new SolbidsSDK({
    rpcUrl: string,           // Solana RPC endpoint
    programId: string,        // Solbids program ID
    backendUrl: string,       // Backend API URL
    commitment: string,       // Solana commitment level
    apiKey?: string          // Optional API key
});

MerkleTree

Utility class for generating and verifying Merkle proofs.

const merkleTree = new MerkleTree();
const leaf = merkleTree.generateBidLeaf(auctionId, bidder, amount, timestamp);
const proof = merkleTree.getBidProof(auctionId, bids, bidIndex);
const isValid = merkleTree.verifyProof(leaf, proof, root);

Auction Management

Create Auction

const result = await sdk.createAuction({
    startTime: number,
    endTime: number,
    minBid: number,
    metadata?: string
}, creatorKeypair);

Place Bid

const result = await sdk.placeBid(
    auctionId: string,
    amount: number,
    bidderKeypair: Keypair,
    bidData?: Buffer
);

End Auction

const result = await sdk.endAuction(auctionId, bids);

Verification

Verify Bid Proof

const proof = sdk.getBidProof(auctionId, bids, bidIndex);
const isValid = await sdk.verifyBidProof(
    auctionId,
    bidder,
    amount,
    timestamp,
    proof
);

Verify Auction Result

const isValid = await sdk.verifyAuctionResult(
    auctionId,
    stateRoot,
    winner,
    finalAmount,
    finalitySlot
);

Data Retrieval

Get Auction Data

const auction = await sdk.getAuctionData(auctionId);

Listen to Updates

const unsubscribe = sdk.onAuctionUpdate(auctionId, (data) => {
    console.log('Auction update:', data);
});

Advanced Usage

Custom Merkle Tree Operations

// Generate state root for entire auction
const stateRoot = sdk.generateStateRoot(
    auctionId,
    bids,
    winner,
    finalAmount,
    endTime
);

// Batch verify multiple bids
const verifications = await sdk.batchVerifyBids(auctionId, [
    { bidder, bidAmount, bidTimestamp, proof },
    // ... more
]);

Event Listening

// Listen to real-time bid updates
const unsubscribe = sdk.onAuctionUpdate(auctionId, (update) => {
    switch (update.type) {
        case 'newBid':
            console.log('New bid:', update.bid);
            break;
        case 'auctionEnd':
            console.log('Auction ended');
            break;
    }
});

// Clean up when done
unsubscribe();

Error Handling

try {
    const result = await sdk.placeBid(auctionId, amount, bidderKeypair);
    console.log('Bid successful:', result.transaction);
} catch (error) {
    if (error.message.includes('BidTooLow')) {
        console.log('Bid amount too low');
    } else if (error.message.includes('AuctionNotActive')) {
        console.log('Auction not active');
    } else {
        console.error('Unexpected error:', error);
    }
}

Configuration

Environment Variables

# Solana Configuration
SOLANA_RPC_URL=https://api.devnet.solana.com
SOLBIDS_PROGRAM_ID=your_program_id_here

# Backend Configuration
SOLBIDS_BACKEND_URL=https://api.solbids.com
SOLBIDS_API_KEY=your_api_key_here

# Commitment Level
SOLBIDS_COMMITMENT=confirmed

SDK Options

const sdk = new SolbidsSDK({
    rpcUrl: process.env.SOLANA_RPC_URL,
    programId: process.env.SOLBIDS_PROGRAM_ID,
    backendUrl: process.env.SOLBIDS_BACKEND_URL,
    commitment: process.env.SOLBIDS_COMMITMENT as Commitment,
    apiKey: process.env.SOLBIDS_API_KEY
});

Security Considerations

• API Key Management: Store API keys securely, rotate regularly
• Keypair Security: Never expose private keys in client applications
• Proof Verification: Always verify proofs before accepting results
• Rate Limiting: Implement rate limiting for auction operations
• Error Handling: Handle network failures and timeouts gracefully

Examples

See the /examples directory for complete integration examples:

• basic-auction.js - Simple auction creation and bidding
• advanced-verification.js - Merkle proof verification
• real-time-updates.js - WebSocket event handling

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Submit a pull request

License

MIT License - see LICENSE file for details.

Support

• 📖 Documentation
• 💬 Discord
• 🐛 Issue Tracker
• 📧 Email Support