@lobstercove/lichen-sdk 1.0.0

package/dist/thalllend.js

@@ -0,0 +1,206 @@
+import { PublicKey } from './publickey.js';
+const PROGRAM_SYMBOL_CANDIDATES = ['LEND', 'lend', 'THALLLEND', 'thalllend'];
+const MAX_U64 = (1n << 64n) - 1n;
+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 encodeUserAmountArgs(user, amount) {
+    return buildLayoutArgs([0x20, 0x08], [
+        user.toBytes(),
+        u64LE(amount, 'amount'),
+    ]);
+}
+function encodeUserLookupArgs(user) {
+    return buildLayoutArgs([0x20], [normalizeAddress(user).toBytes()]);
+}
+function encodeLiquidateArgs(liquidator, params) {
+    return buildLayoutArgs([0x20, 0x20, 0x08], [
+        liquidator.toBytes(),
+        normalizeAddress(params.borrower).toBytes(),
+        u64LE(params.repayAmount, 'repayAmount'),
+    ]);
+}
+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 ?? `ThallLend ${functionName} returned code ${code}`);
+    }
+    if (result.success === false && result.error) {
+        throw new Error(result.error);
+    }
+}
+function decodeU64Return(result, functionName) {
+    ensureReadonlySuccess(result, functionName);
+    if (!result.returnData) {
+        throw new Error(`ThallLend ${functionName} did not return payload data`);
+    }
+    const bytes = decodeReturnData(result.returnData);
+    if (bytes.length < 8) {
+        throw new Error(`ThallLend ${functionName} payload was shorter than expected`);
+    }
+    return readU64(bytes, 0);
+}
+function decodeAccountInfo(result) {
+    ensureReadonlySuccess(result, 'get_account_info');
+    if (!result.returnData) {
+        throw new Error('ThallLend get_account_info did not return account data');
+    }
+    const bytes = decodeReturnData(result.returnData);
+    if (bytes.length < 24) {
+        throw new Error('ThallLend get_account_info payload was shorter than expected');
+    }
+    return {
+        deposit: readU64(bytes, 0),
+        borrow: readU64(bytes, 8),
+        healthFactorBps: readU64(bytes, 16),
+    };
+}
+function decodeProtocolStats(result) {
+    ensureReadonlySuccess(result, 'get_protocol_stats');
+    if (!result.returnData) {
+        throw new Error('ThallLend get_protocol_stats did not return stats data');
+    }
+    const bytes = decodeReturnData(result.returnData);
+    if (bytes.length < 32) {
+        throw new Error('ThallLend get_protocol_stats payload was shorter than expected');
+    }
+    return {
+        totalDeposits: readU64(bytes, 0),
+        totalBorrows: readU64(bytes, 8),
+        utilizationPct: readU64(bytes, 16),
+        reserves: readU64(bytes, 24),
+    };
+}
+function decodeInterestRate(result) {
+    ensureReadonlySuccess(result, 'get_interest_rate');
+    if (!result.returnData) {
+        throw new Error('ThallLend get_interest_rate did not return rate data');
+    }
+    const bytes = decodeReturnData(result.returnData);
+    if (bytes.length < 24) {
+        throw new Error('ThallLend get_interest_rate payload was shorter than expected');
+    }
+    return {
+        ratePerSlot: readU64(bytes, 0),
+        utilizationPct: readU64(bytes, 8),
+        totalAvailable: readU64(bytes, 16),
+    };
+}
+export class ThallLendClient {
+    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 ThallLend program via getSymbolRegistry("LEND")');
+    }
+    async getAccountInfo(user) {
+        return decodeAccountInfo(await this.callReadonly('get_account_info', encodeUserLookupArgs(user)));
+    }
+    async getProtocolStats() {
+        return decodeProtocolStats(await this.callReadonly('get_protocol_stats'));
+    }
+    async getInterestRate() {
+        return decodeInterestRate(await this.callReadonly('get_interest_rate'));
+    }
+    async getDepositCount() {
+        return decodeU64Return(await this.callReadonly('get_deposit_count'), 'get_deposit_count');
+    }
+    async getBorrowCount() {
+        return decodeU64Return(await this.callReadonly('get_borrow_count'), 'get_borrow_count');
+    }
+    async getLiquidationCount() {
+        return decodeU64Return(await this.callReadonly('get_liquidation_count'), 'get_liquidation_count');
+    }
+    async getStats() {
+        const stats = await this.connection.getThallLendStats();
+        return {
+            totalDeposits: stats.total_deposits ?? 0,
+            totalBorrows: stats.total_borrows ?? 0,
+            reserves: stats.reserves ?? 0,
+            depositCount: stats.deposit_count ?? 0,
+            borrowCount: stats.borrow_count ?? 0,
+            liquidationCount: stats.liquidation_count ?? 0,
+            paused: Boolean(stats.paused),
+        };
+    }
+    async deposit(depositor, amount) {
+        const programId = await this.getProgramId();
+        const args = encodeUserAmountArgs(depositor.pubkey(), amount);
+        return this.connection.callContract(depositor, programId, 'deposit', args, normalizeUnsignedU64(amount, 'amount'));
+    }
+    async withdraw(depositor, amount) {
+        const programId = await this.getProgramId();
+        const args = encodeUserAmountArgs(depositor.pubkey(), amount);
+        return this.connection.callContract(depositor, programId, 'withdraw', args);
+    }
+    async borrow(borrower, amount) {
+        const programId = await this.getProgramId();
+        const args = encodeUserAmountArgs(borrower.pubkey(), amount);
+        return this.connection.callContract(borrower, programId, 'borrow', args);
+    }
+    async repay(borrower, amount) {
+        const programId = await this.getProgramId();
+        const args = encodeUserAmountArgs(borrower.pubkey(), amount);
+        return this.connection.callContract(borrower, programId, 'repay', args, normalizeUnsignedU64(amount, 'amount'));
+    }
+    async liquidate(liquidator, params) {
+        const programId = await this.getProgramId();
+        const args = encodeLiquidateArgs(liquidator.pubkey(), params);
+        return this.connection.callContract(liquidator, programId, 'liquidate', args, normalizeUnsignedU64(params.repayAmount, 'repayAmount'));
+    }
+}

package/dist/transaction.d.ts

@@ -0,0 +1,100 @@
+import { PublicKey } from './publickey.js';
+import { Keypair } from './keypair.js';
+import { PqSignature } from './pq.js';
+/**
+ * Transaction instruction
+ */
+export interface Instruction {
+    programId: PublicKey;
+    accounts: PublicKey[];
+    data: Uint8Array;
+}
+/**
+ * Transaction message (before signing)
+ */
+export interface Message {
+    instructions: Instruction[];
+    recentBlockhash: string;
+    computeBudget?: number;
+    computeUnitPrice?: number;
+}
+/**
+ * Signed transaction
+ */
+export interface Transaction {
+    signatures: PqSignature[];
+    message: Message;
+}
+/**
+ * Transaction builder
+ */
+export declare class TransactionBuilder {
+    private instructions;
+    private recentBlockhash?;
+    /**
+     * Add an instruction
+     */
+    add(instruction: Instruction): this;
+    /**
+     * Set recent blockhash
+     */
+    setRecentBlockhash(blockhash: string): this;
+    /**
+     * Build the message (ready for signing)
+     */
+    build(): Message;
+    /**
+     * Build and sign the transaction
+     */
+    buildAndSign(keypair: Keypair): Transaction;
+    /**
+     * Create a transfer instruction
+     *
+     * P9-SDK-01: `amount` accepts `number | bigint` to avoid silent truncation
+     * for values exceeding `Number.MAX_SAFE_INTEGER` (2^53 - 1).
+     * Using `bigint` is recommended for large LICN amounts.
+     */
+    static transfer(from: PublicKey, to: PublicKey, amount: number | bigint): Instruction;
+    /**
+     * Create a stake instruction
+     *
+     * P9-SDK-01: `amount` accepts `number | bigint`.
+     */
+    static stake(from: PublicKey, validator: PublicKey, amount: number | bigint): Instruction;
+    /**
+     * Create an unstake request instruction
+     *
+     * P9-SDK-01: `amount` accepts `number | bigint`.
+     */
+    static unstake(from: PublicKey, validator: PublicKey, amount: number | bigint): Instruction;
+    /**
+     * Contract program ID: [0xFF; 32]
+     */
+    private static readonly CONTRACT_PROGRAM_ID;
+    /**
+     * Create a deploy contract instruction.
+     *
+     * @param deployer - The deployer's public key (signer, pays deploy fee)
+     * @param code - WASM bytecode
+     * @param initData - Optional initialization data (default: empty)
+     */
+    static deployContract(deployer: PublicKey, code: Uint8Array, initData?: Uint8Array): Instruction;
+    /**
+     * Create a call contract instruction.
+     *
+     * @param caller - The caller's public key (signer)
+     * @param contract - The contract's public key
+     * @param functionName - Contract function to call
+     * @param args - Serialized function arguments (default: empty)
+     * @param value - Native LICN to send with the call in spores (default: 0)
+     */
+    static callContract(caller: PublicKey, contract: PublicKey, functionName: string, args?: Uint8Array, value?: number | bigint): Instruction;
+    /**
+     * Create an upgrade contract instruction (owner only).
+     *
+     * @param owner - The contract owner's public key (signer)
+     * @param contract - The contract's public key
+     * @param code - New WASM bytecode
+     */
+    static upgradeContract(owner: PublicKey, contract: PublicKey, code: Uint8Array): Instruction;
+}

package/dist/transaction.js

@@ -0,0 +1,202 @@
+// Lichen SDK - Transaction Types and Builder
+import { PublicKey } from './publickey.js';
+import { encodeMessage } from './bincode.js';
+/**
+ * Transaction builder
+ */
+export class TransactionBuilder {
+    constructor() {
+        this.instructions = [];
+    }
+    /**
+     * Add an instruction
+     */
+    add(instruction) {
+        this.instructions.push(instruction);
+        return this;
+    }
+    /**
+     * Set recent blockhash
+     */
+    setRecentBlockhash(blockhash) {
+        this.recentBlockhash = blockhash;
+        return this;
+    }
+    /**
+     * Build the message (ready for signing)
+     */
+    build() {
+        if (!this.recentBlockhash) {
+            throw new Error('Recent blockhash not set');
+        }
+        if (this.instructions.length === 0) {
+            throw new Error('No instructions added');
+        }
+        return {
+            instructions: this.instructions,
+            recentBlockhash: this.recentBlockhash,
+        };
+    }
+    /**
+     * Build and sign the transaction
+     */
+    buildAndSign(keypair) {
+        const message = this.build();
+        const messageBytes = encodeMessage(message);
+        const signature = keypair.sign(messageBytes);
+        return {
+            signatures: [signature],
+            message,
+        };
+    }
+    /**
+     * Create a transfer instruction
+     *
+     * P9-SDK-01: `amount` accepts `number | bigint` to avoid silent truncation
+     * for values exceeding `Number.MAX_SAFE_INTEGER` (2^53 - 1).
+     * Using `bigint` is recommended for large LICN amounts.
+     */
+    static transfer(from, to, amount) {
+        const amt = BigInt(amount);
+        if (amt < 0n)
+            throw new Error('Transfer amount must be non-negative');
+        if (amt > 0xffffffffffffffffn)
+            throw new Error('Transfer amount exceeds u64 max');
+        // Encode transfer data (program-specific format)
+        const data = new Uint8Array(9);
+        data[0] = 0; // Transfer instruction type
+        const view = new DataView(data.buffer);
+        view.setBigUint64(1, amt, true);
+        return {
+            programId: new PublicKey('11111111111111111111111111111111'), // System program (all-zero pubkey)
+            accounts: [from, to],
+            data,
+        };
+    }
+    /**
+     * Create a stake instruction
+     *
+     * P9-SDK-01: `amount` accepts `number | bigint`.
+     */
+    static stake(from, validator, amount) {
+        const amt = BigInt(amount);
+        if (amt < 0n)
+            throw new Error('Stake amount must be non-negative');
+        if (amt > 0xffffffffffffffffn)
+            throw new Error('Stake amount exceeds u64 max');
+        const data = new Uint8Array(9);
+        data[0] = 9; // Stake instruction type
+        const view = new DataView(data.buffer);
+        view.setBigUint64(1, amt, true);
+        return {
+            programId: new PublicKey('11111111111111111111111111111111'), // System program (all-zero pubkey)
+            accounts: [from, validator],
+            data,
+        };
+    }
+    /**
+     * Create an unstake request instruction
+     *
+     * P9-SDK-01: `amount` accepts `number | bigint`.
+     */
+    static unstake(from, validator, amount) {
+        const amt = BigInt(amount);
+        if (amt < 0n)
+            throw new Error('Unstake amount must be non-negative');
+        if (amt > 0xffffffffffffffffn)
+            throw new Error('Unstake amount exceeds u64 max');
+        const data = new Uint8Array(9);
+        data[0] = 10; // Unstake request instruction type
+        const view = new DataView(data.buffer);
+        view.setBigUint64(1, amt, true);
+        return {
+            programId: new PublicKey('11111111111111111111111111111111'), // System program (all-zero pubkey)
+            accounts: [from, validator],
+            data,
+        };
+    }
+    /**
+     * Create a deploy contract instruction.
+     *
+     * @param deployer - The deployer's public key (signer, pays deploy fee)
+     * @param code - WASM bytecode
+     * @param initData - Optional initialization data (default: empty)
+     */
+    static deployContract(deployer, code, initData = new Uint8Array(0)) {
+        if (code.length < 4 || code[0] !== 0x00 || code[1] !== 0x61 || code[2] !== 0x73 || code[3] !== 0x6d) {
+            throw new Error('Invalid WASM bytecode: missing magic header (\\0asm)');
+        }
+        if (code.length > 512 * 1024) {
+            throw new Error('Contract code exceeds 512 KB limit');
+        }
+        // ContractInstruction::Deploy serialized as JSON (matches core serde_json format)
+        const payload = JSON.stringify({
+            Deploy: {
+                code: Array.from(code),
+                init_data: Array.from(initData),
+            },
+        });
+        const data = new TextEncoder().encode(payload);
+        return {
+            programId: TransactionBuilder.CONTRACT_PROGRAM_ID,
+            accounts: [deployer],
+            data,
+        };
+    }
+    /**
+     * Create a call contract instruction.
+     *
+     * @param caller - The caller's public key (signer)
+     * @param contract - The contract's public key
+     * @param functionName - Contract function to call
+     * @param args - Serialized function arguments (default: empty)
+     * @param value - Native LICN to send with the call in spores (default: 0)
+     */
+    static callContract(caller, contract, functionName, args = new Uint8Array(0), value = 0) {
+        const val = BigInt(value);
+        if (val < 0n)
+            throw new Error('Call value must be non-negative');
+        if (val > 0xffffffffffffffffn)
+            throw new Error('Call value exceeds u64 max');
+        // ContractInstruction::Call serialized as JSON (matches core serde_json format)
+        const payload = JSON.stringify({
+            Call: {
+                function: functionName,
+                args: Array.from(args),
+                value: Number(val),
+            },
+        });
+        const data = new TextEncoder().encode(payload);
+        return {
+            programId: TransactionBuilder.CONTRACT_PROGRAM_ID,
+            accounts: [caller, contract],
+            data,
+        };
+    }
+    /**
+     * Create an upgrade contract instruction (owner only).
+     *
+     * @param owner - The contract owner's public key (signer)
+     * @param contract - The contract's public key
+     * @param code - New WASM bytecode
+     */
+    static upgradeContract(owner, contract, code) {
+        if (code.length < 4 || code[0] !== 0x00 || code[1] !== 0x61 || code[2] !== 0x73 || code[3] !== 0x6d) {
+            throw new Error('Invalid WASM bytecode: missing magic header (\\0asm)');
+        }
+        if (code.length > 512 * 1024) {
+            throw new Error('Contract code exceeds 512 KB limit');
+        }
+        const payload = JSON.stringify({ Upgrade: { code: Array.from(code) } });
+        const data = new TextEncoder().encode(payload);
+        return {
+            programId: TransactionBuilder.CONTRACT_PROGRAM_ID,
+            accounts: [owner, contract],
+            data,
+        };
+    }
+}
+/**
+ * Contract program ID: [0xFF; 32]
+ */
+TransactionBuilder.CONTRACT_PROGRAM_ID = new PublicKey(new Uint8Array(32).fill(0xFF));

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@lobstercove/lichen-sdk",
+  "version": "1.0.0",
+  "description": "Official JavaScript/TypeScript SDK for Lichen blockchain",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "tsc --noEmit",
+    "prepare": "npm run build"
+  },
+  "keywords": [
+    "lichen",
+    "blockchain",
+    "crypto",
+    "licn",
+    "web3"
+  ],
+  "author": "Lichen Labs <hello@lichen.network>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lobstercove/lichen.git",
+    "directory": "sdk/js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20.19.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.32",
+    "@types/ws": "^8.5.10",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.3.3"
+  },
+  "dependencies": {
+    "@noble/post-quantum": "^0.6.0",
+    "bs58": "^5.0.0",
+    "ws": "^8.16.0"
+  }
+}