BIQ Logger - Solana Program

A Solana program built with the Pinocchio library for logging proof data with authority management.

Colosseum jury, please also check the other biq repos listed under our organization: https://github.com/biqProtocol

Features

• Authority Management: Master signer can add/remove authorities
• Proof Logging: Authorized signers can log structured proof data
• PDA Storage: Uses Program Derived Addresses for secure data storage
• Flexible Data Structure: Supports variable-length event IDs and optional location/area fields
• TypeScript Client: Full-featured TypeScript/JavaScript client library

TypeScript Client

This project includes a comprehensive TypeScript client for easy integration:

npm install @biqprotocol/biq-logger

import { BiqLoggerClient, ProofData } from '@biqprotocol/biq-logger';

const client = new BiqLoggerClient(connection, programId);
const instruction = client.createLogProofInstruction(accounts, proofData);

See client/README.md for complete documentation.

Program Structure

Instructions

1. AddAuthority: Adds a new authority to the authorized list
2. RemoveAuthority: Removes an authority from the authorized list
3. LogProof: Logs proof data (only callable by authorized signers)

Data Structures

ProofData

• version: 1 byte - Data structure version
• beacon_id: 32 bytes - Beacon identifier (Pubkey)
• nonce: 16 bytes - Random nonce
• timestamp: 4 bytes - Unix timestamp
• signature: 64 bytes - Cryptographic signature
• event_ids: Variable length - Array of 16-byte event identifiers
• location_id: Optional 1 byte - Location identifier
• area_id: Optional 1 byte - Area identifier

AuthorityList

• Stored in a PDA derived from seed "authority_list"
• Contains a vector of authorized public keys

Usage

1. Setup

Make sure you have the Solana CLI and Rust installed:

# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Install Solana CLI
sh -c "$(curl -sSfL https://release.solana.com/v1.18.0/install)"

2. Build the Program

cargo build

For Solana deployment, you would typically use:

cargo build-sbf

Note: Building with cargo build-sbf requires the Solana CLI tools to be installed.

3. Deploy to Networks

The project includes a comprehensive deployment script that supports multiple networks:

# Show help and available options
./deploy.sh --help

# Deploy to local validator (default: http://localhost:8899)
./deploy.sh local

# Deploy to devnet (default)
./deploy.sh devnet

# Deploy to mainnet-beta (requires real SOL)
./deploy.sh mainnet-beta

# Deploy to custom RPC
./deploy.sh custom http://localhost:8899
./deploy.sh custom https://api.mainnet-beta.solana.com

Local Validator Deployment

For local development, first start a local validator:

# Start local validator with reset
solana-test-validator --reset

# Or with specific ports
solana-test-validator --reset --rpc-port 8899 --faucet-port 9900

# Deploy to local validator
./deploy.sh local

Devnet Deployment

For testing on devnet (free SOL via airdrops):

./deploy.sh devnet

The script will automatically request an airdrop if your wallet balance is low.

Mainnet Deployment

For production deployment (requires real SOL):

./deploy.sh mainnet-beta

⚠️ Warning: Mainnet deployment costs real SOL and includes safety confirmations.

Custom RPC Deployment

For deploying to custom RPC endpoints:

# Custom local RPC
./deploy.sh custom http://localhost:8899

# Custom mainnet RPC (like QuickNode, Alchemy, etc.)
./deploy.sh custom https://your-rpc-endpoint.com

4. Manual Deployment (Legacy)

4. Manual Deployment (Legacy)

If you prefer manual deployment without the script:

# Start local validator
solana-test-validator

# Deploy program
solana program deploy target/deploy/biq_logger.so

5. Client Usage

use biq_logger::{BiqLoggerClient, ProofData};
use pinocchio::pubkey::Pubkey;

// Create proof data
let proof_data = ProofData::new(
    1, // version
    beacon_id,
    nonce,
    timestamp,
    signature,
    event_ids,
    Some(location_id),
    Some(area_id),
);

// Create instruction to log proof
let (authority_list_pda, instruction_data) = BiqLoggerClient::log_proof_instruction(
    &program_id,
    &authority_pubkey,
    &user_id_pubkey,
    proof_data,
)?;

Configuration

Master Signer

Update the MASTER_SIGNER constant in src/lib.rs with your actual master public key:

pub const MASTER_SIGNER: [u8; 32] = [1u8; 32]; // Replace with your actual master key

⚠️ Security Note: The current master signer is a placeholder. Replace it with your actual master key before deployment.

Account Structure

AddAuthority / RemoveAuthority

• Account 0: [signer] Master signer
• Account 1: [writable] Authority list PDA
• Account 2: [] Authority to add/remove
• Account 3: [] System program

LogProof

• Account 0: [signer] Authority
• Account 1: [] User ID account
• Account 2: [] Authority list PDA

Error Codes

• 1: Authority already exists (AddAuthority)
• 2: Authority not found (RemoveAuthority)
• 3: Unauthorized (LogProof)

Testing

Run the test suite:

cargo test

Tests cover:

• Proof data serialization/deserialization
• Authority list management
• Client instruction creation
• Data validation

Development

Project Structure

src/
├── lib.rs          # Main program entry point
├── instructions.rs # Instruction handlers
├── state.rs        # Data structures
├── client.rs       # Client utilities
└── tests.rs        # Test suite

Adding New Features

1. Update data structures in state.rs
2. Add instruction handlers in instructions.rs
3. Update the instruction enum in lib.rs
4. Add client utilities in client.rs
5. Write tests in tests.rs

Security Considerations

• Always verify signer accounts in instructions
• Validate PDA derivations
• Implement proper access controls
• Validate input data structures
• Use secure random number generation for nonces
• Implement replay attack protection

License

This project is licensed under the MIT License.