feat: Protobuf changes for registering airdrop (#371)

Token Airdrop Proto changes Signed-off-by: ibankov <[email protected]> Signed-off-by: Valentin Tronkov <[email protected]>
hashgraph · Jul 23, 2024 · 0c8252e · 0c8252e
1 parent 375f5be
commit 0c8252e
Show file tree

Hide file tree

Showing 5 changed files with 238 additions and 0 deletions.
diff --git a/services/basic_types.proto b/services/basic_types.proto
@@ -1211,6 +1211,11 @@ enum HederaFunctionality {
      * Transfer one or more token balances held by the requesting account to the treasury for each token type.
      */
     TokenReject = 92;
+
+    /**
+     * Airdrop one or more tokens to one or more accounts.
+     */
+    TokenAirdrop = 93;
 }
 
 /**
@@ -1669,3 +1674,69 @@ message StakingInfo {
         int64 staked_node_id = 6;
     }
 }
+
+/**
+ * A unique, composite, identifier for a pending airdrop.
+ *
+ * Each pending airdrop SHALL be uniquely identified by a PendingAirdropId.
+ * A PendingAirdropId SHALL be recorded when created and MUST be provided in any transaction
+ * that would modify that pending airdrop (such as a `claimAirdrop` or `cancelAirdrop`).
+ */
+message PendingAirdropId {
+    /**
+     * A sending account.<br/>
+     * This is the account that initiated, and SHALL fund, this pending airdrop.<br/>
+     * This field is REQUIRED.
+     */
+    AccountID sender_id = 1;
+
+    /**
+     * A receiving account.<br/>
+     * This is the ID of the account that SHALL receive the airdrop.<br/>
+     * This field is REQUIRED.
+     */
+    AccountID receiver_id = 2;
+
+    oneof token_reference {
+        /**
+         * A token ID.<br/>
+         * This is the type of token for a fungible/common token airdrop.<br/>
+         * This field is REQUIRED for a fungible/common token and MUST NOT be used for a
+         * non-fungible/unique token.
+         */
+        TokenID fungible_token_type = 3;
+
+        /**
+         * The id of a single NFT, consisting of a Token ID and serial number.<br/>
+         * This is the type of token for a non-fungible/unique token airdrop.<br/>
+         * This field is REQUIRED for a non-fungible/unique token and MUST NOT be used for a
+         * fungible/common token.
+         */
+        NftID non_fungible_token = 4;
+    }
+}
+
+/**
+ * A single pending airdrop value.
+ *
+ * This message SHALL record the airdrop amount for a fungible/common token.<br/>
+ * This message SHOULD be null for a non-fungible/unique token.<br/>
+ * If a non-null `PendingAirdropValue` is set for a non-fungible/unique token, the amount
+ * field MUST be `0`.
+ *
+ * It is RECOMMENDED that implementations store pending airdrop information as a key-value map
+ * from `PendingAirdropId` to `PendingAirdropValue`, with a `null` value used for non-fungible
+ * pending airdrops.
+ */
+message PendingAirdropValue {
+    /**
+     * An amount to transfer for fungible/common tokens.<br/>
+     * This is expressed in the smallest available units for that token
+     * (i.e. 10<sup>-`decimals`</sup> whole tokens).<br/>
+     * This amount SHALL be transferred from the sender to the receiver, if claimed.<br/>
+     * If the token is a fungible/common token, this value MUST be strictly greater than `0`.
+     * If the token is a non-fungible/unique token, this message SHOULD NOT be set, and if
+     * set, this field MUST be `0`.
+     */
+    uint64 amount = 1;
+}
diff --git a/services/token_airdrop.proto b/services/token_airdrop.proto
@@ -0,0 +1,104 @@
+/**
+ * # Token Airdrop
+ * Messages used to implement a transaction to "airdrop" tokens.<br/>
+ * An "airdrop" is a distribution of tokens from a funding account
+ * to one or more recipient accounts, ideally with no action required
+ * by the recipient account(s).
+ *
+ * ### Keywords
+ * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
+ * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
+ * document are to be interpreted as described in [RFC2119](https://www.ietf.org/rfc/rfc2119).
+ */
+syntax = "proto3";
+
+package proto;
+
+/*-
+ * ‌
+ * Hedera Network Services Protobuf
+ * 
+ * Copyright (C) 2024 Hedera Hashgraph, LLC
+ * 
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * ‍
+ */
+
+option java_package = "com.hederahashgraph.api.proto.java";
+// <<<pbj.java_package = "com.hedera.hapi.node.token">>> This comment is special code for setting PBJ Compiler java package
+option java_multiple_files = true;
+
+import "basic_types.proto";
+
+/**
+ * Airdrop one or more tokens to one or more accounts.
+ *
+ * ### Effects
+ * This distributes tokens from the balance of one or more sending account(s) to the balance
+ * of one or more recipient accounts. Accounts MAY receive the tokens in one of four ways.
+ *
+ *  - An account already associated to the token to be distributed SHALL receive the
+ *    airdropped tokens immediately to the recipient account balance.<br/>
+ *    The fee for this transfer SHALL include the transfer, the airdrop fee, and any custom fees.
+ *  - An account with available automatic association slots SHALL be automatically
+ *    associated to the token, and SHALL immediately receive the airdropped tokens to the
+ *    recipient account balance.<br/>
+ *    The fee for this transfer SHALL include the transfer, the association, the cost to renew
+ *    that association once, the airdrop fee, and any custom fees.
+ *  - An account with "receiver signature required" set SHALL have a "Pending Airdrop" created
+ *    and must claim that airdrop with a `claimAirdrop` transaction.<br/>
+ *    The fee for this transfer SHALL include the transfer, the association, the cost to renew
+ *    that association once, the airdrop fee, and any custom fees. If the pending airdrop is not
+ *    claimed immediately, the `sender` SHALL pay the cost to renew the token association, and
+ *    the cost to maintain the pending airdrop, until the pending airdrop is claimed or cancelled.
+ *  - An account with no available automatic association slots SHALL have a "Pending Airdrop"
+ *    created and must claim that airdrop with a `claimAirdrop` transaction.<br/>
+ *    The fee for this transfer SHALL include the transfer, the association, the cost to renew
+ *    that association once, the airdrop fee, and any custom fees. If the pending airdrop is not
+ *    claimed immediately, the `sender` SHALL pay the cost to renew the token association, and
+ *    the cost to maintain the pending airdrop, until the pending airdrop is claimed or cancelled.
+ *
+ * If an airdrop would create a pending airdrop for a fungible/common token, and a pending airdrop
+ * for the same sender, receiver, and token already exists, the existing pending airdrop
+ * SHALL be updated to add the new amount to the existing airdrop, rather than creating a new
+ * pending airdrop.
+ *
+ * Any airdrop that completes immediately SHALL be irreversible. Any airdrop that results in a
+ * "Pending Airdrop" MAY be canceled via a `cancelAirdrop` transaction.
+ *
+ * All transfer fees (including custom fees and royalties), as well as the rent cost for the
+ * first auto-renewal period for any automatic-association slot occupied by the airdropped
+ * tokens, SHALL be charged to the account paying for this transaction.
+ *
+ * ### Record Stream Effects
+ * - Each successful transfer SHALL be recorded in `token_transfer_list` for the transaction record.
+ * - Each successful transfer that consumes an automatic association slot SHALL populate the
+ *   `automatic_association` field for the record.
+ * - Each pending transfer _created_ SHALL be added to the `pending_airdrops` field for the record.
+ * - Each pending transfer _updated_ SHALL be added to the `pending_airdrops` field for the record.
+ */
+message TokenAirdropTransactionBody {
+  /**
+   * A list of token transfers representing one or more airdrops.
+   * The sender for each transfer MUST have sufficient balance to complete the transfers.
+   *
+   * All token transfers MUST successfully transfer tokens or create a pending airdrop
+   * for this transaction to succeed.
+   * This list MUST contain between 1 and 10 transfers, inclusive.
+   *
+   * Note that each transfer of fungible/common tokens requires both a debit and
+   * a credit, so each _fungible_ token transfer MUST have _balanced_ entries in the
+   * TokenTransferList for that transfer.
+   */
+  repeated TokenTransferList token_transfers = 1;
+}
diff --git a/services/token_service.proto b/services/token_service.proto
@@ -150,4 +150,28 @@ service TokenService {
      * </li>
      */
     rpc rejectToken (Transaction) returns (TransactionResponse);
+
+    /**
+     * Airdrop one or more tokens to one or more accounts.<br/>
+     * This distributes tokens from the balance of one or more sending account(s) to the balance
+     * of one or more recipient accounts. Accounts will receive the tokens in one of four ways.
+     * <ul>
+     *   <li>An account already associated to the token to be distributed SHALL receive the
+     *       airdropped tokens immediately to the recipient account balance.</li>
+     *   <li>An account with available automatic association slots SHALL be automatically
+     *       associated to the token, and SHALL immediately receive the airdropped tokens to the
+     *       recipient account balance.</li>
+     *   <li>An account with "receiver signature required" set SHALL have a "Pending Airdrop"
+     *       created and MUST claim that airdrop with a `claimAirdrop` transaction.</li>
+     *   <li>An account with no available automatic association slots SHALL have a
+     *       "Pending Airdrop" created and MUST claim that airdrop with a `claimAirdrop`
+     *       transaction. </li>
+     * </ul>
+     * Any airdrop that completes immediately SHALL be irreversible. Any airdrop that results in a
+     * "Pending Airdrop" MAY be canceled via a `cancelAirdrop` transaction.<br/>
+     * All transfer fees (including custom fees and royalties), as well as the rent cost for the
+     * first auto-renewal period for any automatic-association slot occupied by the airdropped
+     * tokens, SHALL be charged to the account submitting this transaction.
+     */
+    rpc airdropTokens (Transaction) returns (TransactionResponse);
 }
diff --git a/services/transaction_body.proto b/services/transaction_body.proto
@@ -74,6 +74,7 @@ import "token_pause.proto";
 import "token_unpause.proto";
 import "token_update_nfts.proto";
 import "token_reject.proto";
+import "token_airdrop.proto";
 
 import "schedule_create.proto";
 import "schedule_delete.proto";
@@ -400,5 +401,10 @@ message TransactionBody {
          * SHALL NOT be charged for this transaction.
          */
         TokenRejectTransactionBody tokenReject = 57;
+
+        /**
+         * A transaction body for a `tokenAirdrop` request.
+         */
+        TokenAirdropTransactionBody tokenAirdrop = 58;
     }
 }
diff --git a/services/transaction_record.proto b/services/transaction_record.proto
@@ -152,4 +152,37 @@ message TransactionRecord {
      * This field is populated only when the EVM address is not specified in the related transaction body.
      */
     bytes evm_address = 21;
+
+    /**
+     * A list of pending token airdrops.
+     * Each pending airdrop represents a single requested transfer from a
+     * sending account to a recipient account. These pending transfers are
+     * issued unilaterally by the sending account, and MUST be claimed by the
+     * recipient account before the transfer MAY complete.
+     * A sender MAY cancel a pending airdrop before it is claimed.
+     * An airdrop transaction SHALL emit a pending airdrop when the recipient has no
+     * available automatic association slots available or when the recipient
+     * has set `receiver_sig_required`.
+     */
+    repeated PendingAirdropRecord new_pending_airdrops = 22;
+}
+
+/**
+ * A record of a new pending airdrop.
+ */
+message PendingAirdropRecord {
+    /**
+     * A unique, composite, identifier for a pending airdrop.
+     * This field is REQUIRED.
+     */
+    PendingAirdropId pending_airdrop_id = 1;
+
+    /**
+     * A single pending airdrop amount.
+     * If the pending airdrop is for a fungible/common token this field is REQUIRED
+     * and SHALL be the current amount of tokens offered.
+     * If the pending airdrop is for a non-fungible/unique token, this field SHALL NOT
+     * be set.
+     */
+    PendingAirdropValue pending_airdrop_value = 2;
 }