solotto 1.0.3 → 1.0.5

package/README.md

@@ -18,6 +18,8 @@ A JavaScript SDK for interacting with the Solotto on-chain lottery program on So
     - [Initialize](#initialize)
     - [RandomDraw](#randomdraw)
     - [LockLottery](#locklottery)
+    - [ClaimExpired](#claimexpired)
+    - [Boost](#boost)
   - [Lottery](#lottery-api)
     - [BuyTickets](#buytickets)
     - [ClaimTicket](#claimticket)
@@ -198,6 +200,49 @@ await manager.LockLottery(authority, lotteryId, 1);
 
 ---
 
+#### ClaimExpired
+
+Reclaims the prize pool funds from an expired lottery where the winner did not claim in time. Only callable by the lottery authority.
+
+```js
+const result = await manager.ClaimExpired(authority, lotteryId, encoded);
+```
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `authority` | `Keypair` | — | The lottery authority keypair. |
+| `lotteryId` | `String` | — | The lottery ID. |
+| `encoded` | `Boolean` | `false` | If `true`, returns encoded transaction. |
+
+**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.
+
+---
+
 ### Lottery API
 
 #### BuyTickets
@@ -218,7 +263,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:**
 
@@ -282,12 +327,14 @@ const state = await lottery.GetLottery(authority, lotteryId, fees);
   ticketPrice: 100000000,        // Ticket price in lamports
   totalTickets: 42,              // Total tickets sold
   winnerTicketNumber: 17,        // Winning ticket number (0/null if not drawn)
-  winnerAddress: "Pubkey...",    // Winner's public key (null if not drawn)
+  winnerAddress: "Pubkey...",    // Winner's public key as string (null if not drawn)
   isActive: true,                // Whether the lottery is active
   prizePoolBalance: 3780000000,  // Prize pool in lamports (after fees if fees=true)
   drawInitiated: false,          // Whether a draw has been initiated
   prizePoolAddress: "Pubkey...", // Prize pool PDA
   lotteryAddress: "Pubkey...",   // Lottery PDA
+  release: "Pubkey...",          // Release address (lottery PDA)
+  releaseTime: null,             // Unix timestamp when unclaimed prizes can be released (null if not set)
 }
 ```
 

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.3",
+  "version": "1.0.5",
   "description": "Solana lottery client",
   "type": "module",
   "types": "./solotto.d.ts",

package/solotto.d.ts

@@ -62,7 +62,7 @@ declare module "solotto" {
     totalTickets: number;
     /** Winning ticket number, or `0`/`null` if not yet drawn. */
     winnerTicketNumber: number | null;
-    /** Winner's public key, or `null` if not yet drawn. */
+    /** Winner's public key as a base-58 string, or `null` if not yet drawn. */
     winnerAddress: string | null;
     /** Whether the lottery is currently active. */
     isActive: boolean;
@@ -74,6 +74,10 @@ declare module "solotto" {
     prizePoolAddress: string;
     /** Lottery PDA as a base-58 string. */
     lotteryAddress: string;
+    /** Release address (lottery PDA) as a base-58 string. */
+    release: string;
+    /** Unix timestamp when unclaimed prizes can be released, or `null` if not set. */
+    releaseTime: number | null;
   }
 
   // ── Ticket State ──────────────────────────────────────────────────────
@@ -321,5 +325,35 @@ declare module "solotto" {
       lockState: 0 | 1,
       encoded?: boolean
     ): Promise<LotteryState | string | TxResult | undefined>;
+
+    /**
+     * Reclaim prize pool funds from an expired lottery where the winner did not claim in time.
+     * @param authority - The lottery authority keypair.
+     * @param lotteryId - Lottery numeric identifier.
+     * @param encoded   - If `true`, return a base64-encoded transaction.
+     */
+    ClaimExpired(
+      authority: Keypair,
+      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>;
   }
-}
+}

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 = {
@@ -13,6 +13,8 @@ const INSTRUCTIONS = {
     DRAW_WINNER: 2,
     CLAIM_PRIZE: 3,
     LOCK_LOTTERY: 4,
+    RELEASE_EXPIRED: 5,
+    BOOST_LOTTERY: 6,
 };
 
 class LotteryNetwork {
@@ -320,6 +322,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);
@@ -496,12 +501,16 @@ class Lottery extends EventEmitter {
             offset += 8;
             return val;
         });
+
         // 6. winner_address: Option<Pubkey> (1 + 32 bytes)
-        const winnerAddress = readOption(() => {
-            const val = buffer.slice(offset, offset + 32);
-            offset += 32;
-            return val;
-        });
+        let winnerAddress = null;
+        try{
+            winnerAddress = readOption(() => {
+                const val = buffer.slice(offset, offset + 32);
+                offset += 32;
+                return new PublicKey(val).toString();
+            });
+        }catch{}
         // 7. is_active: bool (1 byte)
         const isActive = buffer.readUInt8(offset) === 1;
         offset += 1;
@@ -510,6 +519,15 @@ class Lottery extends EventEmitter {
         offset += 8;
         const drawInitiated = buffer.readUInt8(offset) === 1;
         offset += 1;
+        // 9. draw_timestamp: Option<u64> (1 + 8 bytes)
+        let releaseTime = null;
+        try{
+            releaseTime = readOption(() => {
+                const val = buffer.readBigUInt64LE(offset);
+                offset += 8;
+                return Number(releaseTime);
+            });
+        }catch{}
         const prizePoolAddress = await this.DerivePrizePoolPDA();
         const lotteryAddress = await this.DeriveLotteryPDA(new PublicKey(auth), lotteryId);
         let prizePoolBalance = prizePool;
@@ -526,6 +544,8 @@ class Lottery extends EventEmitter {
             drawInitiated,
             prizePoolAddress: prizePoolAddress[0].toString(),
             lotteryAddress: lotteryAddress[0].toString(),
+            release: lotteryAddress[0].toString(),
+            releaseTime,
         };
     };
 
@@ -635,8 +655,7 @@ class LotteryManager {
             const keys = [
                 { pubkey: authority.publicKey, isSigner: true, isWritable: false },
                 { pubkey: lotteryPDA, isSigner: false, isWritable: true },
-                { pubkey: SYSVAR_RECENT_BLOCKHASHES_PUBKEY, isSigner: false, isWritable: false },
-                { pubkey: SYSVAR_CLOCK_PUBKEY, isSigner: false, isWritable: false },
+                { pubkey: SYSVAR_SLOT_HASHES_PUBKEY, isSigner: false, isWritable: false },
                 { pubkey: prizePoolPDA, isSigner: false, isWritable: true },
                 { pubkey: SystemProgram.programId, isSigner: false, isWritable: false },
             ];
@@ -737,6 +756,140 @@ class LotteryManager {
         }
     }
 
+    /**
+     * @param {Keypair} authority - Keypair
+     * @param {String} lotteryId - The lottery id
+     * @param {Boolean} encoded - true returns encoded transaction
+    */
+    async ClaimExpired(authority, lotteryId, encoded = false) {
+        try{
+            async function expiredData() {
+                const buffer = Buffer.alloc(1); // 1 byte discriminator + 1 bytes lock status
+                buffer.writeUInt8(INSTRUCTIONS.RELEASE_EXPIRED, 0); // lock discriminator
+                return buffer;
+            }
+            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: authority.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 expiredData()});
+            const _tx_ = {};
+            _tx_.account = authority.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 = false;
+            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: 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]);
+                const sig = await network.Send(tx.transaction);
+                console.log("Signature:", sig);
+                const status = await network.Status(sig);
+                if(status == "finalized"){
+                    return await lottery.GetLottery({publicKey: authority.publicKey}, lotteryId, false);
+                }
+                else{return status;}
+            }
+            else{return tx;}           
+        }
+        catch (error) {
+            console.log(error);
+        }
+    }
+
+    /**
+     * @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;
+            }
+            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);
+        }
+    }
+
 }
 
 export {