Red Packet
The Red Packet Module enables users to create and distribute token-based rewards through password-protected red packets with optional on-chain eligibility conditions.
This module is designed to support viral distribution, community incentives, and gated rewards while maintaining clear and auditable rules.
1. Overview
A Red Packet is a reward pool denominated in TBC, created by a user and claimable by other users who:
Enter the correct password, and
Satisfy all predefined eligibility conditions at claim time.
Each red packet can be claimed by multiple recipients until either the maximum number of claims is reached or the total amount is fully distributed.
2. Core Parameters
Asset
Distribution asset
TBC only
Total Amount
Total TBC in a red packet
0.01 – 100 TBC
Max Claims
Maximum number of recipients
≤ 500
Distribution Mode
Allocation method
Equal
Password
Claim access key
Required
Expiration
Optional expiry time
Optional
3. Red Packet Creation
When creating a red packet, the creator specifies the following parameters:
Total Amount (TBC)
Minimum: 0.01 TBC
Maximum: 100 TBC
Maximum Number of Claims
Up to 500 recipients per red packet
Password
Required to claim the red packet
Case-sensitive
Distribution Method
Equal: each eligible user receives the same amount
Eligibility Conditions (optional)
See Section 4
Once created, the total amount is escrowed by the protocol and cannot be modified or withdrawn.
4. Eligibility Conditions
Creators may optionally restrict who can claim a red packet by setting one or more on-chain balance requirements.
4.1 Supported Conditions
The following eligibility conditions are supported:
TBC Balance Requirement
Claimant must hold at least a specified amount of TBC at claim time
Specific Token Holding Requirement
Claimant must hold a minimum balance of a specified token contract
Multiple conditions may be combined and are evaluated using logical AND semantics.
4.2 Condition Evaluation
Eligibility is evaluated at the time of claim, based on the claimant’s current on-chain balances.
Balances are read directly from the blockchain
Off-chain or historical balances are not considered
If any condition is not met, the claim is rejected
5. Claim Process
To successfully claim a red packet, a user must:
Submit the correct password
Satisfy all eligibility conditions
Be within the maximum claim limit
Claim before expiration (if set)
Upon a successful claim:
The user receives a portion of the TBC
The remaining balance and claim count are updated
The claim is recorded on-chain or in a verifiable event log
6. Distribution Rules
Each address may claim at most once per red packet
Once the maximum number of claims is reached, the red packet is closed
If the total amount is exhausted earlier, the red packet is closed automatically
Unclaimed funds (if any) after expiration follow platform-defined handling rules
7. Security and Anti-Abuse Measures
The Red Packet Module enforces the following protections:
One-claim-per-address enforcement
On-chain balance verification at claim time
Password validation prior to eligibility checks
Protection against reentrancy and double-claim attempts
8. Use Cases
Typical use cases include:
Community giveaways and engagement campaigns
Token-gated rewards for holders
Viral growth via password sharing
Event-based or promotional incentives
9. Risk Disclosure
Eligibility conditions depend on real-time on-chain state and may change rapidly
Network congestion or delayed confirmations may affect claim success
The platform does not guarantee equal claim outcomes in random distribution mode
10. Summary
The Red Packet Module provides a flexible and composable reward distribution mechanism with:
Clear monetary limits
Explicit eligibility constraints
Deterministic enforcement rules
Transparent and auditable behavior
This module is intended to serve as a foundational primitive for community-driven incentives on the OneShot platform.
Last updated