sample.proto

/**
 * # Sample proto file
 * This file is a sample, based on the Token Airdrop from HIP-904 as
 * a reasonably complex, real-world, example.
 *
 * 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) and clarified in
 * [RFC8174](https://www.ietf.org/rfc/rfc8174).
 */
syntax = "proto3";

package com.hedera.hapi.node.token;

/*
 * 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.<br/>
 *    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.<br/>
 *    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.<br/>
 * 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
 * paying for this transaction.<br/>
 *
 * ### Block 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.
     * <p>
     * The sender for each transfer MUST have sufficient balance to complete
     * the transfers.<br/>
     * All token transfers MUST successfully transfer tokens or create a
     * pending airdrop for this transaction to succeed.<br/>
     * This list MUST contain between 1 and 10 transfers, inclusive.
     * <p>
     * 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 proto.TokenTransferList token_transfers = 1;
}