solotto 1.0.5 → 1.0.6

package/README.md

@@ -20,6 +20,7 @@ A JavaScript SDK for interacting with the Solotto on-chain lottery program on So
     - [LockLottery](#locklottery)
     - [ClaimExpired](#claimexpired)
     - [Boost](#boost)
+    - [GetBoosters](#getboosters)
   - [Lottery](#lottery-api)
     - [BuyTickets](#buytickets)
     - [ClaimTicket](#claimticket)
@@ -241,6 +242,63 @@ const result = await manager.Boost(authority, lotteryId, booster, 1.0, "Good luc
 
 **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
+  },
+  // ...
+}
+```
+
 ---
 
 ### Lottery API
@@ -300,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.
 
 ---
 
@@ -518,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "solotto",
-  "version": "1.0.5",
+  "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(
@@ -355,5 +383,31 @@ declare module "solotto" {
       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

@@ -285,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);
@@ -837,6 +840,9 @@ class LotteryManager {
                 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);
@@ -890,6 +896,64 @@ class LotteryManager {
         }
     }
 
+    /**
+     * @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 {