Add HIP-904: Token Airdrops

[SimiHunjan]

Problem

This HIP enables frictionless airdrops of both fungible and non-fungible tokens by removing the requirement to pre-associate tokens with the receiver’s account, and by allowing the sender to create associations on the receiver’s account automatically at transfer time by paying for any token-associations created as a result of the airdrop. The sovereignty of account holders who do not wish to receive unsolicited tokens is preserved by supporting the concept of pending token transfers to such an account. Potential token receivers may claim their token airdrop while available if desired and airdrop senders may cancel their sent airdrop should they change their mind.

With this HIP, accounts will no longer prepay for unused token association slots. Association fees will be charged for those slots only when a token is actually associated with an account.

This HIP also introduces the concept of token rejection. Here an undesired token class value is returned to the treasury with all custom fees waived.

Hedera Improvement Proposal

• https://hips.hedera.com/hip/hip-904

Hedera Protobufs

• feat: add HIP-904 frictionless airdrops definitions hedera-protobufs#341
• HIP 904 proto updates for token reject hedera-protobufs#367
• feat: Protobuf changes for registering airdrop hedera-protobufs#371

New APIs

• Add HIP-904: PendingAirdrop #370
• Add HIP-904: PendingAirdropRecord #371
• Add HIP-904: TokenAirdropTransaction #372
• Add HIP-904: TokenCancelAirdropTransaction #373
• Add HIP-904: TokenClaimAirdropTransaction #374
• Add HIP-904: TokenRejectTransaction #348
• Add HIP-904: TokenRejectFlow #375

Update APIs

• Update HIP-904: AccountUpdateTransaction to allow maxAutomaticTokenAssociations value to support -1 as a valid value #349
• Update HIP-904: AccountCreateTransaction to allow maxAutomaticTokenAssociations value to support -1 as a valid value #350
• Update HIP-904: TransactionRecord support for pendingAirdropRecords

Test Plan

1. Given a fungible token, a sender account with a balance of the fungible token, and a receiver account with unlimited auto associations, when the token is airdropped from the sender to the receiver account, then the receiver account contains the sent balance of the token
2. Given a fungible token, a sender account with a balance of the fungible token, a receiver account with no auto associations, and the fungible token is manually associated with the receiver account, when the token is airdropped from the sender to the receiver account, then the receiver account contains the sent balance of the token
3. Given a fungible token, a holder account with a balance of the fungible token, a spender account which has an allowance of the fungible token, and a receiver account with unlimited auto associations, when the token is airdropped from the spender to the receiver account, then the receiver account contains the sent balance of the token and the airdropped amount is debited from the holder account
4. Given a fungible token with decimals, a sender account with a balance of the fungible token, and a receiver account with unlimited auto associations, when the token is airdropped from the sender to the receiver account, then the receiver account contains the sent balance of the token
5. Given an NFT, a sender account with 1 minted NFT, and a receiver account with unlimited auto associations, when the NFT is airdropped from the sender to the receiver account, then the receiver account contains the NFT
6. Given an NFT, a sender account with 1 minted NFT, a receiver account with no auto associations, and the NFT is manually associated with the receiver account, when the NFT is airdropped from the sender to the receiver account, then the receiver account contains the NFT
7. Given an NFT, a holder account with 1 minted NFT, a spender account which has an allowance of the NFT, and a receiver account with unlimited auto associations, when the NFT is airdropped from the spender to the receiver account, then the receiver account contains the NFT and the NFT is debited from the holder account
8. Given a fungible token, a sender account with a balance of the fungible token, and a receiver account with no auto associations, when the token is airdropped from the sender to the receiver account, then the receiver account does not contain the sent balance of the token and the TransactionRecord for the transaction contains a pending airdrop.
9. Given an NFT, a sender account with 1 minted NFT, and a receiver account with no auto associations, when the NFT is airdropped from the sender to the receiver account, then the receiver account does not contain the NFT and the TransactionRecord for the transaction contains a pending airdrop
10. Given a fungible token, a sender account with a balance of the fungible token, a receiver account with no auto associations, and the token is airdropped from the sender to the receiver account, when the receiver account goes to claim the airdrop, then the receiver account contains the sent balance of the token
11. Given an NFT, a sender account with 1 minted NFT, a receiver account with no auto associations, and the NFT is airdropped from the sender to the receiver account, when the receiver account goes to claim the airdrop, then the receiver account contains the sent NFT
12. Given a fungible token, a sender account with a balance of the fungible token, a receiver account with no auto associations, and the token is attempted to be airdropped from the sender to the receiver account, when the sender account goes to cancel the airdrop, then the sender account still contains the balance of the token and the receiver account does not contain any balance of the token
13. Given an NFT, a sender account with 1 minted NFT, a receiver account with no auto associations, and the NFT is attempted to be airdropped from the sender to the receiver account, when the sender account goes to cancel the airdrop, then the sender account still contains the NFT and the receiver account does not contain the NFT
14. Given a fungible token, a treasury account for the token, and a holding account with a balance of the fungible token, when the holding account rejects the token, then the treasury account contains the full balance of the token from the holding account, the holding account no longer contains any balance of the token, and no fees were charged
15. Given an NFT, a treasury account for the NFT, and a holding account with 1 minted NFT, when the holding account rejects the NFT, then the treasury account contains the sent NFT, the holding account no longer contains the NFT, and no fees were charged
16. Given a fungible token, a sender account with a balance of the fungible token, a receiver account with no auto associations, and a pending airdrop is created from the sender to the receiver of the fungible token, when the receiver account is updated to have unlimited auto associations and the first airdrop is cancelled, then the sender account can airdrop the token again and the receiver account contains the sent balance of the token
17. Given an NFT, a sender account with 1 minted NFT, a receiver account with no auto associations, and a pending airdrop is created from the sender to the receiver of the NFT, when the receiver account is updated to have unlimited auto associations and the first airdrop is cancelled, then the sender account can airdrop the NFT again and the receiver account contains the NFT

Example

1. Create four accounts
   1. Account 1 has unlimited auto associations
   2. Account 2 has one auto association
   3. Account 3 has no auto associations
   4. Account 4 is the treasury account for the tokens about to be created
2. Create a new fungible token
3. Create a new NFT
4. Mint 3 of the NFTs
5. Associate Account 2 with the fungible token
6. Airdrop the fungible token to all three accounts
7. Get the transaction record and see one pending airdrop (for Account 3)
8. Query to verify Account 1 and Account 2 received the airdrops and Account 3 did not
9. Claim the airdrop for Account 3
10. Query to verify Account 3 received the airdrop
11. Airdrop the NFTs to all three accounts
12. Get the transaction record and verify two pending airdrops (for Account 2 & 3)
13. Query to verify Account 1 received the airdrop and Account 2 and Account 3 did not
14. Claim the airdrop for Account 2
15. Query to verify Account 2 received the airdrop
16. Cancel the airdrop for Account 3
17. Query to verify Account 3 did not receive the airdrop
18. Reject the NFT for Account 2
19. Query to verify Account 2 no longer has the NFT
20. Query to verify the NFT was returned to Account 4
21. Reject the fungible tokens for Account 3
22. Query to verify Account 3 no longer has the fungible tokens
23. Query to verify Account 4 received the rejected fungible tokens

Solution

Add support for each feature according to the Services release plan for this HIP.

Alternatives

No response