solotto 1.0.2 → 1.0.4

package/README.md

@@ -18,6 +18,7 @@ A JavaScript SDK for interacting with the Solotto on-chain lottery program on So
     - [Initialize](#initialize)
     - [RandomDraw](#randomdraw)
     - [LockLottery](#locklottery)
+    - [ClaimExpired](#claimexpired)
   - [Lottery](#lottery-api)
     - [BuyTickets](#buytickets)
     - [ClaimTicket](#claimticket)
@@ -198,6 +199,24 @@ 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, or the transaction object when encoded.
+
+---
+
 ### Lottery API
 
 #### BuyTickets
@@ -282,12 +301,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "solotto",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "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,17 @@ 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>;
   }
-}
+}

package/solotto.js

@@ -10,9 +10,10 @@ import {EventEmitter} from 'events';
 const INSTRUCTIONS = {
     INITIALIZE_LOTTERY: 0,
     BUY_TICKET: 1,
-    ENTROPY: 2,
+    DRAW_WINNER: 2,
     CLAIM_PRIZE: 3,
     LOCK_LOTTERY: 4,
+    RELEASE_EXPIRED: 5,
 };
 
 class LotteryNetwork {
@@ -496,12 +497,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 +515,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 +540,8 @@ class Lottery extends EventEmitter {
             drawInitiated,
             prizePoolAddress: prizePoolAddress[0].toString(),
             lotteryAddress: lotteryAddress[0].toString(),
+            release: lotteryAddress[0].toString(),
+            releaseTime,
         };
     };
 
@@ -625,7 +641,7 @@ class LotteryManager {
         try{
             async function randomnessData() {
                 const buffer = Buffer.alloc(1);
-                buffer.writeUInt8(INSTRUCTIONS.ENTROPY, 0);
+                buffer.writeUInt8(INSTRUCTIONS.DRAW_WINNER, 0);
                 return buffer;
             }
             const lottery = new Lottery(this.connection, false, this.program);
@@ -635,8 +651,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 +752,66 @@ 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_);             // build the tx
+            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);
+        }
+    }
+
 }
 
 export {