@lobstercove/lichen-sdk 1.0.0

package/README.md

@@ -0,0 +1,50 @@
+# Lichen JavaScript/TypeScript SDK
+
+Official SDK for interacting with Lichen blockchain.
+
+## Installation
+
+```bash
+npm install @lobstercove/lichen-sdk
+```
+
+## Quick Start
+
+```typescript
+import { Connection, Keypair, PublicKey } from '@lobstercove/lichen-sdk';
+
+// Connect to Lichen
+const connection = new Connection('http://localhost:8899');
+
+// Generate a native PQ keypair
+const keypair = Keypair.generate();
+console.log('Address:', keypair.pubkey().toBase58());
+
+// Get account balance
+const pubkey = new PublicKey('YourPublicKeyHere...');
+const balance = await connection.getBalance(pubkey);
+console.log(`Balance: ${balance.licn} LICN`);
+
+// Subscribe to blocks
+connection.onBlock((block) => {
+  console.log('New block:', block);
+});
+```
+
+## Documentation
+
+See the [JavaScript SDK reference](https://developers.lichen.network/sdk-js.html) for detailed API reference.
+
+## Features
+
+- ✅ Complete RPC client (24 endpoints)
+- ✅ WebSocket subscriptions (real-time events)
+- ✅ Native PQ keypairs and self-contained signatures
+- ✅ Transaction builder
+- ✅ TypeScript types
+- ✅ Address and PQ public-key utilities
+- ✅ Full blockchain interaction
+
+## License
+
+MIT

package/dist/bincode.d.ts

@@ -0,0 +1,5 @@
+import type { Message, Transaction } from './transaction.js';
+export declare function hexToBytes(hex: string): Uint8Array;
+export declare function bytesToHex(bytes: Uint8Array): string;
+export declare function encodeMessage(message: Message): Uint8Array;
+export declare function encodeTransaction(transaction: Transaction): Uint8Array;

package/dist/bincode.js

@@ -0,0 +1,91 @@
+// Minimal bincode encoder for Lichen transactions
+import { bytesToHex as pqBytesToHex, hexToBytes as pqHexToBytes, toPqSignature, } from './pq.js';
+const textEncoder = new TextEncoder();
+function encodeU64LE(value) {
+    const out = new Uint8Array(8);
+    const view = new DataView(out.buffer);
+    view.setBigUint64(0, BigInt(value), true);
+    return out;
+}
+function encodeU32LE(value) {
+    const out = new Uint8Array(4);
+    const view = new DataView(out.buffer);
+    view.setUint32(0, value, true);
+    return out;
+}
+function encodeOptionU64(value) {
+    if (value === undefined || value === null) {
+        return new Uint8Array([0x00]); // None
+    }
+    return concat([new Uint8Array([0x01]), encodeU64LE(value)]); // Some(value)
+}
+function concat(parts) {
+    const total = parts.reduce((sum, part) => sum + part.length, 0);
+    const out = new Uint8Array(total);
+    let offset = 0;
+    for (const part of parts) {
+        out.set(part, offset);
+        offset += part.length;
+    }
+    return out;
+}
+function encodeBytes(data) {
+    return concat([encodeU64LE(data.length), data]);
+}
+function encodeString(value) {
+    const encoded = textEncoder.encode(value);
+    return concat([encodeU64LE(encoded.length), encoded]);
+}
+function encodeVec(items) {
+    return concat([encodeU64LE(items.length), ...items]);
+}
+export function hexToBytes(hex) {
+    return pqHexToBytes(hex);
+}
+export function bytesToHex(bytes) {
+    return pqBytesToHex(bytes);
+}
+function encodeU8(value) {
+    return Uint8Array.of(value & 0xff);
+}
+function encodePubkey(pubkey) {
+    const bytes = pubkey.toBytes();
+    if (bytes.length !== 32) {
+        throw new Error('PublicKey must be 32 bytes');
+    }
+    return bytes;
+}
+function encodeInstruction(ix) {
+    const programId = encodePubkey(ix.programId);
+    const accounts = encodeVec(ix.accounts.map(encodePubkey));
+    const data = encodeBytes(ix.data);
+    return concat([programId, accounts, data]);
+}
+function encodePqPublicKey(publicKey) {
+    return concat([encodeU8(publicKey.schemeVersion), encodeBytes(publicKey.toBytes())]);
+}
+function encodePqSignature(signature) {
+    return concat([
+        encodeU8(signature.schemeVersion),
+        encodePqPublicKey(signature.publicKey),
+        encodeBytes(signature.toBytes()),
+    ]);
+}
+export function encodeMessage(message) {
+    const instructions = encodeVec(message.instructions.map(encodeInstruction));
+    const blockhash = hexToBytes(message.recentBlockhash);
+    if (blockhash.length !== 32) {
+        throw new Error('Blockhash must be 32 bytes');
+    }
+    const computeBudget = encodeOptionU64(message.computeBudget);
+    const computeUnitPrice = encodeOptionU64(message.computeUnitPrice);
+    return concat([instructions, blockhash, computeBudget, computeUnitPrice]);
+}
+export function encodeTransaction(transaction) {
+    const sigBytes = transaction.signatures.map((signature) => encodePqSignature(toPqSignature(signature)));
+    const encodedSigs = concat([encodeU64LE(sigBytes.length), ...sigBytes]);
+    const messageBytes = encodeMessage(transaction.message);
+    // tx_type: Native=0 (u32 LE)
+    const txType = encodeU32LE(0);
+    return concat([encodedSigs, messageBytes, txType]);
+}

package/dist/bountyboard.d.ts

@@ -0,0 +1,57 @@
+import { Connection } from './connection.js';
+import { Keypair } from './keypair.js';
+import { PublicKey } from './publickey.js';
+export declare const BOUNTY_STATUS_OPEN = 0;
+export declare const BOUNTY_STATUS_COMPLETED = 1;
+export declare const BOUNTY_STATUS_CANCELLED = 2;
+export interface BountyBoardBountyInfo {
+    creator: PublicKey;
+    titleHash: Uint8Array;
+    rewardAmount: bigint;
+    deadlineSlot: bigint;
+    status: number;
+    submissionCount: number;
+    createdSlot: bigint;
+    approvedIdx: number;
+}
+export interface BountyBoardPlatformStats {
+    bountyCount: bigint;
+    completedCount: bigint;
+    rewardVolume: bigint;
+    cancelCount: bigint;
+}
+export interface BountyBoardStats {
+    bountyCount: number;
+    completedCount: number;
+    totalRewardVolume: number;
+    cancelCount: number;
+    paused: boolean;
+}
+export interface CreateBountyParams {
+    titleHash: Uint8Array;
+    rewardAmount: number | bigint;
+    deadlineSlot: number | bigint;
+}
+export interface SubmitWorkParams {
+    bountyId: number | bigint;
+    proofHash: Uint8Array;
+}
+export interface ApproveWorkParams {
+    bountyId: number | bigint;
+    submissionIdx: number;
+}
+export declare class BountyBoardClient {
+    private readonly connection;
+    private resolvedProgram?;
+    constructor(connection: Connection, programId?: PublicKey);
+    private callReadonly;
+    getProgramId(): Promise<PublicKey>;
+    getBounty(bountyId: number | bigint): Promise<BountyBoardBountyInfo | null>;
+    getBountyCount(): Promise<bigint>;
+    getPlatformStats(): Promise<BountyBoardPlatformStats>;
+    getStats(): Promise<BountyBoardStats>;
+    createBounty(creator: Keypair, params: CreateBountyParams): Promise<string>;
+    submitWork(worker: Keypair, params: SubmitWorkParams): Promise<string>;
+    approveWork(creator: Keypair, params: ApproveWorkParams): Promise<string>;
+    cancelBounty(creator: Keypair, bountyId: number | bigint): Promise<string>;
+}

package/dist/bountyboard.js

@@ -0,0 +1,205 @@
+import { PublicKey } from './publickey.js';
+const PROGRAM_SYMBOL_CANDIDATES = ['BOUNTY', 'bounty', 'BountyBoard', 'BOUNTYBOARD', 'bountyboard'];
+const MAX_U64 = (1n << 64n) - 1n;
+const BOUNTY_DATA_SIZE = 91;
+const PLATFORM_STATS_SIZE = 32;
+// Bounty status constants
+export const BOUNTY_STATUS_OPEN = 0;
+export const BOUNTY_STATUS_COMPLETED = 1;
+export const BOUNTY_STATUS_CANCELLED = 2;
+function normalizeAddress(value) {
+    return value instanceof PublicKey ? value : new PublicKey(value);
+}
+function normalizeUnsignedU64(value, fieldName) {
+    const normalized = typeof value === 'bigint'
+        ? value
+        : Number.isSafeInteger(value) && value >= 0
+            ? BigInt(value)
+            : null;
+    if (normalized === null || normalized < 0n || normalized > MAX_U64) {
+        throw new Error(`${fieldName} must be a u64-safe integer value`);
+    }
+    return normalized;
+}
+function u64LE(value, fieldName) {
+    const out = new Uint8Array(8);
+    new DataView(out.buffer).setBigUint64(0, normalizeUnsignedU64(value, fieldName), true);
+    return out;
+}
+function buildLayoutArgs(layout, chunks) {
+    const header = Uint8Array.from([0xAB, ...layout]);
+    const total = chunks.reduce((sum, chunk) => sum + chunk.length, header.length);
+    const out = new Uint8Array(total);
+    out.set(header, 0);
+    let offset = header.length;
+    for (const chunk of chunks) {
+        out.set(chunk, offset);
+        offset += chunk.length;
+    }
+    return out;
+}
+function decodeReturnData(returnData) {
+    return Uint8Array.from(Buffer.from(returnData, 'base64'));
+}
+function readU64(bytes, offset) {
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    return view.getBigUint64(offset, true);
+}
+function ensureReadonlySuccess(result, functionName, allowedReturnCodes = [0]) {
+    const code = result.returnCode ?? 0;
+    if (!allowedReturnCodes.includes(code)) {
+        throw new Error(result.error ?? `BountyBoard ${functionName} returned code ${code}`);
+    }
+    if (result.success === false && result.error) {
+        throw new Error(result.error);
+    }
+}
+function ensureBytes32(value, fieldName) {
+    if (value.length !== 32) {
+        throw new Error(`${fieldName} must be exactly 32 bytes`);
+    }
+    return value;
+}
+// --- Encoding helpers ---
+function encodeCreateBountyArgs(creator, titleHash, rewardAmount, deadlineSlot) {
+    return buildLayoutArgs([0x20, 0x20, 0x08, 0x08], [creator.toBytes(), ensureBytes32(titleHash, 'titleHash'), u64LE(rewardAmount, 'rewardAmount'), u64LE(deadlineSlot, 'deadlineSlot')]);
+}
+function encodeSubmitWorkArgs(bountyId, worker, proofHash) {
+    return buildLayoutArgs([0x08, 0x20, 0x20], [u64LE(bountyId, 'bountyId'), worker.toBytes(), ensureBytes32(proofHash, 'proofHash')]);
+}
+function encodeApproveWorkArgs(caller, bountyId, submissionIdx) {
+    if (submissionIdx < 0 || submissionIdx > 255) {
+        throw new Error('submissionIdx must be 0-255');
+    }
+    return buildLayoutArgs([0x20, 0x08, 0x01], [caller.toBytes(), u64LE(bountyId, 'bountyId'), Uint8Array.from([submissionIdx])]);
+}
+function encodeCancelBountyArgs(caller, bountyId) {
+    return buildLayoutArgs([0x20, 0x08], [caller.toBytes(), u64LE(bountyId, 'bountyId')]);
+}
+function encodeBountyIdArgs(bountyId) {
+    return buildLayoutArgs([0x08], [u64LE(bountyId, 'bountyId')]);
+}
+// --- Decoding helpers ---
+function decodeBountyInfo(result) {
+    ensureReadonlySuccess(result, 'get_bounty');
+    if (!result.returnData) {
+        throw new Error('BountyBoard get_bounty did not return bounty data');
+    }
+    const bytes = decodeReturnData(result.returnData);
+    if (bytes.length < BOUNTY_DATA_SIZE) {
+        throw new Error('BountyBoard get_bounty payload was shorter than expected');
+    }
+    return {
+        creator: new PublicKey(bytes.slice(0, 32)),
+        titleHash: bytes.slice(32, 64),
+        rewardAmount: readU64(bytes, 64),
+        deadlineSlot: readU64(bytes, 72),
+        status: bytes[80],
+        submissionCount: bytes[81],
+        createdSlot: readU64(bytes, 82),
+        approvedIdx: bytes[90],
+    };
+}
+function decodePlatformStats(result) {
+    ensureReadonlySuccess(result, 'get_platform_stats');
+    if (!result.returnData) {
+        throw new Error('BountyBoard get_platform_stats did not return stats data');
+    }
+    const bytes = decodeReturnData(result.returnData);
+    if (bytes.length < PLATFORM_STATS_SIZE) {
+        throw new Error('BountyBoard get_platform_stats payload was shorter than expected');
+    }
+    return {
+        bountyCount: readU64(bytes, 0),
+        completedCount: readU64(bytes, 8),
+        rewardVolume: readU64(bytes, 16),
+        cancelCount: readU64(bytes, 24),
+    };
+}
+export class BountyBoardClient {
+    constructor(connection, programId) {
+        this.connection = connection;
+        this.resolvedProgram = programId;
+    }
+    async callReadonly(functionName, args = new Uint8Array()) {
+        const programId = await this.getProgramId();
+        return this.connection.callReadonlyContract(programId, functionName, args);
+    }
+    async getProgramId() {
+        if (this.resolvedProgram) {
+            return this.resolvedProgram;
+        }
+        for (const symbol of PROGRAM_SYMBOL_CANDIDATES) {
+            try {
+                const entry = await this.connection.getSymbolRegistry(symbol);
+                if (entry?.program) {
+                    this.resolvedProgram = new PublicKey(entry.program);
+                    return this.resolvedProgram;
+                }
+            }
+            catch {
+                // Try the next known registry alias.
+            }
+        }
+        throw new Error('Unable to resolve the BountyBoard program via getSymbolRegistry("BOUNTY")');
+    }
+    // --- Read methods ---
+    async getBounty(bountyId) {
+        const result = await this.callReadonly('get_bounty', encodeBountyIdArgs(normalizeUnsignedU64(bountyId, 'bountyId')));
+        if ((result.returnCode ?? 0) === 1 || !result.returnData) {
+            return null;
+        }
+        return decodeBountyInfo(result);
+    }
+    async getBountyCount() {
+        const result = await this.callReadonly('get_bounty_count');
+        ensureReadonlySuccess(result, 'get_bounty_count');
+        if (!result.returnData) {
+            return 0n;
+        }
+        const bytes = decodeReturnData(result.returnData);
+        if (bytes.length < 8) {
+            return 0n;
+        }
+        return readU64(bytes, 0);
+    }
+    async getPlatformStats() {
+        return decodePlatformStats(await this.callReadonly('get_platform_stats'));
+    }
+    async getStats() {
+        const stats = await this.connection.getBountyBoardStats();
+        return {
+            bountyCount: stats.bounty_count ?? 0,
+            completedCount: stats.completed_count ?? 0,
+            totalRewardVolume: stats.total_reward_volume ?? 0,
+            cancelCount: stats.cancel_count ?? 0,
+            paused: Boolean(stats.paused),
+        };
+    }
+    // --- Write methods ---
+    async createBounty(creator, params) {
+        const programId = await this.getProgramId();
+        const rewardAmount = normalizeUnsignedU64(params.rewardAmount, 'rewardAmount');
+        const deadlineSlot = normalizeUnsignedU64(params.deadlineSlot, 'deadlineSlot');
+        const args = encodeCreateBountyArgs(creator.pubkey(), params.titleHash, rewardAmount, deadlineSlot);
+        return this.connection.callContract(creator, programId, 'create_bounty', args, rewardAmount);
+    }
+    async submitWork(worker, params) {
+        const programId = await this.getProgramId();
+        const bountyId = normalizeUnsignedU64(params.bountyId, 'bountyId');
+        const args = encodeSubmitWorkArgs(bountyId, worker.pubkey(), params.proofHash);
+        return this.connection.callContract(worker, programId, 'submit_work', args);
+    }
+    async approveWork(creator, params) {
+        const programId = await this.getProgramId();
+        const bountyId = normalizeUnsignedU64(params.bountyId, 'bountyId');
+        const args = encodeApproveWorkArgs(creator.pubkey(), bountyId, params.submissionIdx);
+        return this.connection.callContract(creator, programId, 'approve_work', args);
+    }
+    async cancelBounty(creator, bountyId) {
+        const programId = await this.getProgramId();
+        const normalizedId = normalizeUnsignedU64(bountyId, 'bountyId');
+        const args = encodeCancelBountyArgs(creator.pubkey(), normalizedId);
+        return this.connection.callContract(creator, programId, 'cancel_bounty', args);
+    }
+}