BSC Giveaway Contract Call Skill

1. Deployment information

• - Network: BSC (Binance Smart Chain mainnet, chainId = 56)
• Contract file: INLINECODE0
• Contract address: INLINECODE1
• Main dependencies: IERC20, Ownable, ReentrancyGuard, internal TransferHelper library

Assumptions when calling:

• - You are already connected to a BSC mainnet RPC (for example https://bsc-dataseed.binance.org)
• Account balance and gas settings are handled by the caller

2. Core enums and structs (pass as uint in calls)

DistributionType

• - 0 = AVERAGE: equal share, each claim gets INLINECODE8
• INLINECODE9 = RANDOM: random share, a single claim is roughly in the range \(0 \sim 2 \times\) the average

ClaimRestriction

• - 0 = PUBLIC: public, no additional restriction
• INLINECODE11 = TOKEN_HOLDER: only addresses holding restrictionToken with balance ≥ INLINECODE13
• INLINECODE14 = WHITELIST: only whitelisted addresses can claim

GiveawayInfo

• - token: token address for the giveaway, address(0) means BNB
• INLINECODE17: creator address
• INLINECODE18: current remaining total giveaway amount in the contract (after creation fee is deducted)
• INLINECODE19: current remaining claimable slots
• INLINECODE20: distribution type (0/1)
• INLINECODE21: claim restriction type (0/1/2)
• INLINECODE22: restriction token address (only meaningful for TOKEN_HOLDER)
• INLINECODE23: minimum token balance required
• INLINECODE24: expiration timestamp (seconds)

3. Write function cheatsheet

3.1 Create giveaway createGiveaway

Signature:

CODEBLOCK0

Key constraints:

• - INLINECODE26
• INLINECODE27
• INLINECODE28
• INLINECODE29 ∈ {0,1}
• INLINECODE30 ∈ {0,1,2}
• If restriction == TOKEN_HOLDER (1):

Fees and transfers:

• - Fee: feeAmount = (amount / 1000) * FEERATE, sent directly to INLINECODE35
• Actual amount entering the contract: INLINECODE36
• If token == address(0) (BNB giveaway):

• - If token != address(0) (ERC20 giveaway):

3.2 Claim giveaway claimGiveaway

CODEBLOCK1

Internal checks:

• - giveawayInfos[id].amount != 0: giveaway exists and has remaining amount
• Caller has not claimed yet: INLINECODE51
• Not expired: INLINECODE52
• TOKEN_HOLDER: check INLINECODE53
• WHITELIST: INLINECODE54

Distribution logic:

• - AVERAGE:

• - RANDOM:

3.3 Withdraw expired giveaway withdrawExpiredGiveaway

CODEBLOCK2

Constraints:

• - INLINECODE61
• INLINECODE62
• INLINECODE63

Withdrawal fee:

• - INLINECODE64
• INLINECODE65
• Transfer logic also distinguishes BNB vs ERC20

3.4 Whitelist management

CODEBLOCK3

Constraints:

• - Only the giveaway creator: INLINECODE66
• And the giveaway must be of WHITELIST type: INLINECODE67

4. Read function cheatsheet

CODEBLOCK4

Key points of canClaim:

• - Returns false if amount is 0, already claimed, or INLINECODE70
• TOKEN_HOLDER: checks token balance
• WHITELIST: checks whitelist
• Otherwise returns true (PUBLIC)

5. Script / frontend usage example (ethers.js)

Assume you already have a provider / signer and have loaded the compiled ABI:

CODEBLOCK5

When integrating in a frontend or script:

• - Read functions (getGiveawayInfo, canClaim, isInWhitelist) can use a provider instance;
• Write functions (createGiveaway, claimGiveaway, withdrawExpiredGiveaway, whitelist add/remove) must use a signer with signing capability;
• For BNB giveaways you must pass BNB equal to amount via value; for ERC20 giveaways you must approve beforehand.

7. ABI information and minimal examples

• - Full ABI source: the JSON generated after compiling contracts/contracts/Giveaway.sol in this repo (for example artifacts/.../Giveaway.json); in scripts/frontends you should generally import the abi field from that file.
• Purpose of this section: provide a minimal ABI fragment for quick debugging or building a minimal frontend/script when you cannot directly access the compiled artifacts. It is not guaranteed to stay perfectly in sync with future contract upgrades.

7.1 Key event fragments

CODEBLOCK6

7.2 Common function fragments

Only the most common read/write function signatures are listed below, to make it easy to construct ethers.Contract / web3.eth.Contract. For the full ABI, always refer to the build artifacts.

CODEBLOCK7

The fragments above can be combined with the TypeScript example earlier, for example:

CODEBLOCK8

6. Relationship with existing giveaway-protocol skill

• - giveaway-protocol focuses more on the protocol-level description (enum semantics, logical constraints, general call conventions);
• INLINECODE92 is specifically about this concrete contract deployed on BSC mainnet (fixed contract address + specific network info + call examples).

When you need “the contract address and direct on-chain interaction”, you should prefer this skill.
If you need more complete error descriptions or protocol details, you can also refer to giveaway-protocol’s reference.md.