solotto 1.0.4 → 1.0.6

package/README.md

@@ -19,6 +19,8 @@ A JavaScript SDK for interacting with the Solotto on-chain lottery program on So
     - [RandomDraw](#randomdraw)
     - [LockLottery](#locklottery)
     - [ClaimExpired](#claimexpired)
+    - [Boost](#boost)
+    - [GetBoosters](#getboosters)
   - [Lottery](#lottery-api)
     - [BuyTickets](#buytickets)
     - [ClaimTicket](#claimticket)
@@ -213,7 +215,89 @@ const result = await manager.ClaimExpired(authority, lotteryId, encoded);
 | `lotteryId` | `String` | — | The lottery ID. |
 | `encoded` | `Boolean` | `false` | If `true`, returns encoded transaction. |
 
-**Returns:** Updated lottery state object on finalization, or the transaction object when encoded.
+**Returns:** Updated lottery state object on finalization, `"Prize has already been claimed"` if the prize was already claimed, or the transaction object when encoded.
+
+---
+
+#### Boost
+
+Boosts a lottery's prize pool by transferring SOL from any wallet. Can be called by anyone, not just the authority. Optionally attaches a memo message to the transaction.
+
+```js
+// Boost lottery #1 with 0.5 SOL
+const result = await manager.Boost(authority, lotteryId, booster, 0.5);
+
+// Boost with a memo message
+const result = await manager.Boost(authority, lotteryId, booster, 1.0, "Good luck everyone!");
+```
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `authority` | `{publicKey}` | — | The lottery authority (only `publicKey` is needed). |
+| `lotteryId` | `String` | — | The lottery ID. |
+| `booster` | `Keypair` | — | The keypair of the wallet sending the boost. |
+| `amount` | `Number` | — | Amount of SOL to boost (e.g. `0.5` for 0.5 SOL). |
+| `message` | `String \| false` | `false` | Optional memo string attached to the transaction. |
+| `encoded` | `Boolean` | `false` | If `true`, returns encoded transaction. |
+
+**Returns:** `"boosted"` on success, `"Draw initiated, cannot boost this prize pool"` if the draw has already started, or the transaction object when encoded.
+
+> **Note:** When a `message` is provided, the SDK automatically prepends a structured memo in the format `:booster:authority,lotteryId,booster,amount:booster:` before your message. This structured prefix is used by `GetBoosters` to index boost history from on-chain transaction memos.
+
+---
+
+#### GetBoosters
+
+Retrieves boost history by scanning on-chain transaction memos. Can filter by authority, lottery ID, or both, and optionally group results by booster wallet address.
+
+```js
+// Get all boosters for a specific lottery
+const boosters = await manager.GetBoosters(authority, lotteryId);
+
+// Get all boosters across all lotteries (up to 500 transactions)
+const allBoosters = await manager.GetBoosters(false, false, false, 500);
+
+// Get boosters grouped by wallet address
+const grouped = await manager.GetBoosters(authority, lotteryId, true);
+```
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `authority` | `{publicKey} \| false` | `false` | Filter by lottery authority. Pass `false` to include all authorities. |
+| `lotteryId` | `Number \| false` | `false` | Filter by lottery ID. Pass `false` to include all lotteries. |
+| `group` | `Boolean` | `false` | If `true`, groups results by booster wallet address. |
+| `limit` | `Number` | `1000` | Maximum number of recent transactions to scan (max 1000). |
+
+**Returns (ungrouped):** An array of booster objects:
+
+```js
+[
+  {
+    lotteryId: 1,
+    authority: "Pubkey...",
+    booster: "Pubkey...",
+    amount: 0.5,
+    signature: "TxSignature...",
+  },
+  // ...
+]
+```
+
+**Returns (grouped, `group = true`):** An object keyed by booster wallet address:
+
+```js
+{
+  "BoosterPubkey...": {
+    boost: [
+      { lotteryId: 1, authority: "Pubkey...", booster: "Pubkey...", amount: 0.5, signature: "TxSig..." },
+      // ...
+    ],
+    total: 1.5,    // Sum of all boost amounts in SOL
+    count: 3,      // Number of boosts
+  },
+  // ...
+}
+```
 
 ---
 
@@ -237,7 +321,7 @@ const result = await lottery.BuyTickets(buyer, authority, lotteryId, amount, enc
 | `amount` | `Number` | `1` | Number of tickets to purchase (1–4). |
 | `encoded` | `Boolean` | `false` | If `true`, returns encoded transaction. |
 
-**Returns:** `"finalized"` on success, or the transaction object when encoded.
+**Returns:** `"finalized"` on success, `"Lottery is not active, no tickets can be sold"` if the lottery is inactive, or the transaction object when encoded.
 
 **Example:**
 
@@ -274,7 +358,7 @@ const result = await lottery.ClaimTicket(authority, lotteryId, winner, encoded);
 | `winner` | `Keypair` | — | The keypair of the winning ticket's owner. |
 | `encoded` | `Boolean` | `false` | If `true`, returns encoded transaction. |
 
-**Returns:** `"finalized"` on success, or the transaction object when encoded.
+**Returns:** `"finalized"` on success, the simulation log array (`string[]`) if the transaction fails simulation, or the transaction object when encoded.
 
 ---
 
@@ -492,7 +576,7 @@ const status = await network.Status(signature, maxRetries, intervalSeconds);
 
 ## Transaction Modes
 
-Every write method (`Initialize`, `RandomDraw`, `LockLottery`, `BuyTickets`, `ClaimTicket`) supports two modes controlled by the `encoded` parameter:
+Every write method (`Initialize`, `RandomDraw`, `LockLottery`, `ClaimExpired`, `Boost`, `BuyTickets`, `ClaimTicket`) supports two modes controlled by the `encoded` parameter:
 
 **Direct Mode** (`encoded = false`, default) — The SDK signs, sends, and confirms the transaction. Requires the keypair to have a `secretKey`. Returns the final status or lottery state.
 

package/SECURITY.md

@@ -0,0 +1,15 @@
+# Security Policy
+
+<a name="reporting"></a>
+## Reporting Security Problems
+
+**DO NOT CREATE A GITHUB ISSUE** to report a security problem.
+
+Please contact the maintainers:
+
+X: @SolDapper
+
+<a name="process"></a>
+## Incident Response Process
+
+Maintainers will respond to security incidents as fast as possible, and will keep you informed of our progress. Thank you.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "solotto",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "description": "Solana lottery client",
   "type": "module",
   "types": "./solotto.d.ts",

package/solotto.d.ts

@@ -138,6 +138,34 @@ declare module "solotto" {
     reconnecting: (event: ReconnectingEvent) => void;
   }
 
+  // ── Booster Types ──────────────────────────────────────────────────
+
+  interface BoosterRecord {
+    /** Lottery numeric identifier. */
+    lotteryId: number;
+    /** Lottery authority public key. */
+    authority: string;
+    /** Booster wallet public key. */
+    booster: string;
+    /** Boost amount in SOL. */
+    amount: number;
+    /** Transaction signature. */
+    signature: string;
+  }
+
+  interface GroupedBooster {
+    /** Array of individual boost records. */
+    boost: BoosterRecord[];
+    /** Total SOL boosted by this wallet. */
+    total: number;
+    /** Number of boosts from this wallet. */
+    count: number;
+  }
+
+  interface GroupedBoostersResult {
+    [boosterAddress: string]: GroupedBooster;
+  }
+
   // ── Authority-like objects ────────────────────────────────────────────
 
   /** An object with at least a `publicKey` property (e.g. a Keypair without the secret key). */
@@ -237,7 +265,7 @@ declare module "solotto" {
       lotteryId: number,
       winner: Keypair,
       encoded?: boolean
-    ): Promise<string | TxResult>;
+    ): Promise<string | string[] | TxResult>;
 
     /** Fetch the on-chain state of a lottery. */
     GetLottery(
@@ -337,5 +365,49 @@ declare module "solotto" {
       lotteryId: number,
       encoded?: boolean
     ): Promise<LotteryState | string | TxResult | undefined>;
+
+    /**
+     * Boost a lottery's prize pool by transferring SOL from any wallet.
+     * @param authority - The lottery authority (only `publicKey` needed).
+     * @param lotteryId - Lottery numeric identifier.
+     * @param booster   - The keypair of the wallet sending the boost.
+     * @param amount    - Amount of SOL to boost (e.g. `0.5` for 0.5 SOL).
+     * @param message   - Optional memo string attached to the transaction.
+     * @param encoded   - If `true`, return a base64-encoded transaction.
+     */
+    Boost(
+      authority: HasPublicKey,
+      lotteryId: number,
+      booster: Keypair,
+      amount: number,
+      message?: string | false,
+      encoded?: boolean
+    ): Promise<string | TxResult | undefined>;
+
+    /**
+     * Retrieve boost history from on-chain transaction memos.
+     * @param authority - Filter by lottery authority, or `false` for all.
+     * @param lotteryId - Filter by lottery ID, or `false` for all.
+     * @param group     - If `true`, group results by booster wallet address.
+     * @param limit     - Maximum number of recent transactions to scan (max 1000).
+     */
+    GetBoosters(
+      authority?: HasPublicKey | false,
+      lotteryId?: number | false,
+      group?: false,
+      limit?: number
+    ): Promise<BoosterRecord[]>;
+    GetBoosters(
+      authority: HasPublicKey | false,
+      lotteryId: number | false,
+      group: true,
+      limit?: number
+    ): Promise<GroupedBoostersResult>;
+    GetBoosters(
+      authority?: HasPublicKey | false,
+      lotteryId?: number | false,
+      group?: boolean,
+      limit?: number
+    ): Promise<BoosterRecord[] | GroupedBoostersResult>;
   }
 }

package/solotto.js

@@ -1,10 +1,10 @@
-import {Connection, PublicKey, TransactionMessage, TransactionInstruction, VersionedTransaction, ComputeBudgetProgram, SystemProgram, Keypair, SYSVAR_SLOT_HASHES_PUBKEY, SYSVAR_CLOCK_PUBKEY, SYSVAR_RECENT_BLOCKHASHES_PUBKEY} from '@solana/web3.js';
+import {Connection, PublicKey, TransactionMessage, TransactionInstruction, VersionedTransaction, ComputeBudgetProgram, SystemProgram, Keypair, SYSVAR_SLOT_HASHES_PUBKEY, LAMPORTS_PER_SOL} from '@solana/web3.js';
 import bs58 from 'bs58';
 import BN from 'bn.js';
 import {createMemoInstruction} from '@solana/spl-memo';
 import BufferLayout from "buffer-layout";
 const publicKey=(property="publicKey")=>{return BufferLayout.blob(32,property);};const uint64=(property="uint64")=>{return BufferLayout.blob(8,property);}
-import {createSolanaRpcSubscriptions} from "@solana/kit";
+import {createSolanaRpcSubscriptions, SOLANA_ERROR__ADDRESSES__FAILED_TO_FIND_VIABLE_PDA_BUMP_SEED} from "@solana/kit";
 import {EventEmitter} from 'events';
 
 const INSTRUCTIONS = {
@@ -14,6 +14,7 @@ const INSTRUCTIONS = {
     CLAIM_PRIZE: 3,
     LOCK_LOTTERY: 4,
     RELEASE_EXPIRED: 5,
+    BOOST_LOTTERY: 6,
 };
 
 class LotteryNetwork {
@@ -284,6 +285,9 @@ class Lottery extends EventEmitter {
             _tx_.encode = false;  
         }
         const tx = await network.Tx(_tx_);
+        if(tx.logs){
+            return tx.logs;
+        }
         if(winner.secretKey && !encoded){
             tx.transaction.sign([winner]);
             const sig = await network.Send(tx.transaction);
@@ -321,6 +325,9 @@ class Lottery extends EventEmitter {
             _tx_.encode = false;  
         }
         const tx = await network.Tx(_tx_);
+        if(tx.logs && tx.logs.includes("Program log: Lottery is not active, no more tickets can be sold")){
+            return "Lottery is not active, no tickets can be sold";
+        }
         if(buyer.secretKey && !encoded){
             tx.transaction.sign([buyer]);
             const sig = await network.Send(tx.transaction);
@@ -793,7 +800,11 @@ class LotteryManager {
                 _tx_.serialize = false;                        
                 _tx_.encode = false;  
             }
-            const tx = await network.Tx(_tx_);             // build the tx
+            const tx = await network.Tx(_tx_);  
+            // 
+            if(tx.logs && tx.logs.includes("Program log: Prize has already been claimed")){
+                return "Prize has already been claimed";
+            }
             if(tx.status !== "ok"){return tx;}
             if(authority.secretKey && !encoded){
                 tx.transaction.sign([authority]);
@@ -812,6 +823,137 @@ class LotteryManager {
         }
     }
 
+    /**
+     * @param {Keypair} authority - Keypair
+     * @param {String} lotteryId - The lottery id
+     * @param {Keypair} booster - The booster's keypair
+     * @param {Number} amount - The amount of sol to boost
+     * @param {Boolean} encoded - true returns encoded transaction
+    */
+    async Boost(authority, lotteryId, booster, amount, message = false, encoded = false) {
+        try{
+            async function boostData(lotId, amount) {
+                const lamports = parseInt(amount * LAMPORTS_PER_SOL);
+                const buffer = Buffer.alloc(17); // 1 byte discriminator + 1 bytes price + 8 bytes id
+                buffer.writeUInt8(INSTRUCTIONS.BOOST_LOTTERY, 0); // boostLottery discriminator
+                buffer.writeBigUInt64LE(BigInt(lotId), 1);
+                buffer.writeBigUInt64LE(BigInt(lamports), 9);
+                return buffer;
+            }
+            if(message){
+                message = ":booster:"+authority.publicKey.toString()+","+lotteryId+","+booster.publicKey.toString()+","+amount+":booster:"+message;
+            }
+            const lottery = new Lottery(this.connection, false, this.program);
+            const network = new LotteryNetwork(this.connection);
+            const [lotteryPDA] = await lottery.DeriveLotteryPDA(authority.publicKey, lotteryId);
+            const LOTTO = await lottery.GetLottery(authority, lotteryId);
+            const keys = [
+                { pubkey: booster.publicKey, isSigner: true, isWritable: true },
+                { pubkey: lotteryPDA, isSigner: false, isWritable: true },
+                { pubkey: new PublicKey(LOTTO.prizePoolAddress), isSigner: false, isWritable: true },
+                { pubkey: SystemProgram.programId, isSigner: false, isWritable: false },
+            ];
+            const ix = new TransactionInstruction(
+                {programId: this.program, keys, data: await boostData(lotteryId, amount)}
+            );
+            const _tx_ = {};
+            _tx_.account = booster.publicKey.toString();   // string : required
+            _tx_.instructions = [ix];                      // array  : required
+            _tx_.signers = false;                          // array  : default false
+            _tx_.table = false;                            // array  : default false
+            _tx_.tolerance = 1.2;                          // int    : default 1.1    
+            _tx_.compute = true;                           // bool   : default true
+            _tx_.fees = true;                              // bool   : default true
+            _tx_.priority = "Low";                         // string : default Low
+            _tx_.memo = message;
+            if(encoded){
+                _tx_.serialize = true;                        
+                _tx_.encode = true;  
+            }
+            else{
+                _tx_.serialize = false;                        
+                _tx_.encode = false;  
+            }
+            const tx = await network.Tx(_tx_); 
+            if(tx.logs && tx.logs.includes("Program log: Lottery draw has been initiated, cannot boost prize pool")){
+                return "Draw initiated, cannot boost this prize pool";
+            }
+            if(tx.status !== "ok"){return tx;}
+            if(booster.secretKey && !encoded){
+                tx.transaction.sign([booster]);
+                const sig = await network.Send(tx.transaction);
+                console.log("Signature:", sig);
+                const status = await network.Status(sig);
+                if(status == "finalized"){
+                    return "boosted";
+                }
+                else{return status;}
+            }
+            else{return tx;}           
+        }
+        catch (error) {
+            console.log(error);
+        }
+    }
+
+    /**
+     * @param {Keypair} authority - Keypair
+     * @param {String} lotteryId - The lottery id
+     * @param {Boolean} group - if true, groups results by booster wallet address
+     * @param {Number} limit - the results to request (max 1000)
+     * @returns {Array|Object} - Array of booster objects or Object grouped by booster address
+     * Booster objects are returned if the transaction memo includes ":booster:" and matches the authority and lotteryId (if provided)
+     * Booster memo format: ":booster:authorityPublicKey,lotteryId,boosterPublicKey,amount:booster:optionalMessage"
+     * Example return object: { authority: "authorityPublicKey", lotteryId: "1", booster: "boosterPublicKey", amount: 1.5, signature: "transactionSignature" }
+     * If authority is provided, only boosters from that authority are returned
+     * If lotteryId is provided, only boosters for that lotteryId are returned
+     * If both authority and lotteryId are provided, only boosters matching both are returned
+     * If neither is provided, all boosters are returned up to the specified limit
+     * If group is true, returns object with booster addresses as keys, each containing array of boost objects and total amount
+     * Example grouped return: { "boosterPublicKey": { boost: [...], total: 5.5 } }
+    */
+    async GetBoosters(authority=false, lotteryId=false, group=false, limit=1000) {
+        try{
+            const result = [];
+            const signatures = await this.connection.getSignaturesForAddress(this.program, {limit: limit,});
+            for await (const row of signatures) {
+                if(row.memo && row.memo.includes(":booster:")){
+                    const memo = row.memo.split(":booster:")[1];
+                    const [auth, lotId, booster, amount] = memo.split(",");
+                    if((authority ? authority.publicKey.toString() === auth : true) &&
+                    (lotteryId ? lotteryId.toString() === lotId : true)
+                    ){
+                        result.push({
+                            lotteryId: Number(lotId),
+                            authority: auth,
+                            booster: booster,
+                            amount: parseFloat(amount),
+                            signature: row.signature
+                        });
+                    }
+                }
+            }
+            if (group) {
+                const grouped = {};
+                result.forEach(item => {
+                    if (!grouped[item.booster]) {
+                        grouped[item.booster] = {
+                            boost: [],
+                            total: 0
+                        }
+                    }
+                    grouped[item.booster].boost.push(item);
+                    grouped[item.booster].total += item.amount;
+                    grouped[item.booster].count = grouped[item.booster].boost.length;
+                });
+                return grouped;
+            }
+            
+            return result;
+        }
+        catch (error) {return error;}
+    }
+
 }
 
 export {