Add 24-hour red envelope expiry with automatic refund

[reubenyap]

Summary

• Add expire_envelopes() method that runs every 60s to check for envelopes older than 24 hours
• Expired envelopes have remaining balance automatically refunded to the creator
• Creator receives a DM notification about the refund
• Run expiry cleanup once on startup to handle envelopes that expired while bot was offline

Test plan

• Verify envelopes older than 24 hours are marked as expired
• Verify remaining balance is credited back to the envelope creator
• Verify creator receives a DM notification with refund details
• Verify expired envelopes during bot downtime are cleaned up on startup
• Verify partially claimed envelopes only refund the unclaimed remainder

---

Note

High Risk
Changes core balance-handling logic (deposits, withdrawals, tips, envelopes) and introduces a DB type migration from floats to Decimal128, which could impact monetary correctness if any edge cases or partial migrations occur.

Overview
Implements 24-hour red envelope expiry: envelopes older than ENVELOPE_EXPIRY_SECONDS are marked expired, remaining funds are atomically zeroed and refunded to the creator, the creator is DM’d, and the original group message is deleted; cleanup runs on startup and every 60s.

Migrates monetary handling to precise decimals: adds migrate_to_decimal128.py for one-time conversion of users.Balance/Locked, envelopes.amount/remains, and tip_logs.amount to BSON Decimal128, and updates tipbot.py to use Decimal + a MongoDB codec so reads/writes are quantized to 8dp.

Hardens balance mutations by switching tips, deposits, withdrawals, envelopes, and expiry refunds to $inc/find_one_and_update with $gte guards to reduce race conditions and double-processing; also replaces ad-hoc print/traceback with structured logging.

^{Written by Cursor Bugbot for commit 6f60ea3. This will update automatically on new commits. Configure here.}

[reubenyap]

bugbot run

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

Bugbot Autofix prepared a fix for the issue found in the latest run.

• ✅ Fixed: Stale remains value causes over-refund on expiry
  • Changed to ReturnDocument.BEFORE and read remains from the atomically returned document, ensuring the refund uses the actual value at update time rather than a stale cursor value.

Or push these changes by commenting:

@cursor push 090ad7b211

Preview (090ad7b211)

diff --git a/tipbot.py b/tipbot.py
--- a/tipbot.py
+++ b/tipbot.py
@@ -543,13 +543,8 @@
             })
 
             for envelope in expired:
-                remains = to_decimal(envelope['remains'])
-                if remains <= 0:
-                    continue
-
-                store_remains = decimal_to_store(remains)
-
                 # Atomically zero out the envelope remains and mark as expired
+                # Use BEFORE to get the actual remains at update time (avoids race with catch_envelope)
                 updated = self.col_envelopes.find_one_and_update(
                     {
                         "_id": envelope['_id'],
@@ -563,24 +558,31 @@
                             "expired_at": int(datetime.datetime.now().timestamp())
                         }
                     },
-                    return_document=ReturnDocument.AFTER
+                    return_document=ReturnDocument.BEFORE
                 )
                 if not updated:
                     continue
 
+                # Read the actual remains from the document at update time
+                remains = to_decimal(updated['remains'])
+                if remains <= 0:
+                    continue
+
+                store_remains = decimal_to_store(remains)
+
                 # Credit the creator
                 self.col_users.update_one(
-                    {"_id": envelope['creator_id']},
+                    {"_id": updated['creator_id']},
                     {"$inc": {"Balance": store_remains}}
                 )
 
                 logger.info("Envelope %s expired: refunded %s FIRO to user %s",
-                            envelope['_id'], remains, envelope['creator_id'])
+                            updated['_id'], remains, updated['creator_id'])
 
                 # Notify the creator
                 try:
                     self.bot.send_message(
-                        envelope['creator_id'],
+                        updated['creator_id'],
                         "<b>Your red envelope expired.</b>\n"
                         "<b>%s FIRO</b> unclaimed funds have been returned to your balance." %
                         "{0:.8f}".format(remains),
@@ -588,11 +590,11 @@
                     )
                 except Exception as exc:
                     logger.error("Failed to notify envelope creator %s: %s",
-                                 envelope['creator_id'], exc)
+                                 updated['creator_id'], exc)
 
                 # Clean up the group message button
                 try:
-                    self.bot.delete_message(envelope['group_id'], envelope['msg_id'])
+                    self.bot.delete_message(updated['group_id'], updated['msg_id'])
                 except Exception:
                     pass

_{This Bugbot Autofix run was free. To enable autofix for future PRs, go to the Cursor dashboard.}

[cursor]

Stale remains value causes over-refund on expiry

High Severity

The expire_envelopes method reads remains from the initial find() cursor and uses that value to credit the creator. Since expire_envelopes runs in a background thread while catch_envelope runs in the main thread, a catch can reduce remains between the cursor read and the find_one_and_update. The atomic update zeroes out the current (lower) remains, but the refund uses the stale (higher) value — creating FIRO out of thin air. Using ReturnDocument.BEFORE instead of ReturnDocument.AFTER and reading remains from the returned document would give the actual balance at update time.

Additional Locations (1)

• tipbot.py#L565-L566