token_service.proto

syntax = "proto3";

package proto;

/*-
 * ‌
 * Hedera Network Services Protobuf
 * ​
 * Copyright (C) 2018 - 2021 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.service.proto.java";
// <<<pbj.java_package = "com.hedera.hapi.node.token">>> This comment is special code for setting PBJ Compiler java package

import "query.proto";
import "response.proto";
import "transaction_response.proto";
import "transaction.proto";

/**
 * Transactions and queries for the Token Service
 */
service TokenService {
    /**
     * Creates a new Token by submitting the transaction
     */
    rpc createToken (Transaction) returns (TransactionResponse);

    /**
     * Updates the account by submitting the transaction
     */
    rpc updateToken (Transaction) returns (TransactionResponse);

    /**
     * Mints an amount of the token to the defined treasury account
     */
    rpc mintToken (Transaction) returns (TransactionResponse);

    /**
     * Burns an amount of the token from the defined treasury account
     */
    rpc burnToken (Transaction) returns (TransactionResponse);

    /**
     * Deletes a Token
     */
    rpc deleteToken (Transaction) returns (TransactionResponse);

    /**
     * Wipes the provided amount of tokens from the specified Account ID
     */
    rpc wipeTokenAccount (Transaction) returns (TransactionResponse);

    /**
     * Freezes the transfer of tokens to or from the specified Account ID
     */
    rpc freezeTokenAccount (Transaction) returns (TransactionResponse);

    /**
     * Unfreezes the transfer of tokens to or from the specified Account ID
     */
    rpc unfreezeTokenAccount (Transaction) returns (TransactionResponse);

    /**
     * Flags the provided Account ID as having gone through KYC
     */
    rpc grantKycToTokenAccount (Transaction) returns (TransactionResponse);

    /**
     * Removes the KYC flag of the provided Account ID
     */
    rpc revokeKycFromTokenAccount (Transaction) returns (TransactionResponse);

    /**
     * Associates tokens to an account
     */
    rpc associateTokens (Transaction) returns (TransactionResponse);

    /**
     * Dissociates tokens from an account
     */
    rpc dissociateTokens (Transaction) returns (TransactionResponse);

    /**
     * Updates the custom fee schedule on a token
     */
    rpc updateTokenFeeSchedule (Transaction) returns (TransactionResponse);

    /**
     * Retrieves the metadata of a token
     */
    rpc getTokenInfo (Query) returns (Response);

    /**
     * (DEPRECATED) Gets info on NFTs N through M on the list of NFTs associated with a given account
     */
    rpc getAccountNftInfos (Query) returns (Response) {
         option deprecated = true;
    };

    /**
     * Retrieves the metadata of an NFT by TokenID and serial number
     */
    rpc getTokenNftInfo (Query) returns (Response);

    /**
     * (DEPRECATED) Gets info on NFTs N through M on the list of NFTs associated with a given Token of type NON_FUNGIBLE
     */
    rpc getTokenNftInfos (Query) returns (Response) {
         option deprecated = true;
    };

    // Pause the token
    rpc pauseToken (Transaction) returns (TransactionResponse);

    //  Unpause the token
    rpc unpauseToken (Transaction) returns (TransactionResponse);

    /**
     * Updates the NFTs in a collection by TokenID and serial number
     */
    rpc updateNfts (Transaction) returns (TransactionResponse);

    /**
     * Reject one or more tokens.<br/>
     * This transaction SHALL transfer the full balance of one or more tokens from the requesting
     * account to the treasury for each token. This transfer SHALL NOT charge any custom fee or
     * royalty defined for the token(s) to be rejected.<br/>
     * <h3>Effects on success</h3>
     * <ul>
     *   <li>If the rejected token is fungible/common, the requesting account SHALL have a balance
     *       of 0 for the rejected token. The treasury balance SHALL increase by the amount that
     *       the requesting account decreased.</li>
     *   <li>If the rejected token is non-fungible/unique the requesting account SHALL NOT hold
     *       the specific serialized token that is rejected. The treasury account SHALL hold each
     *       specific serialized token that was rejected.</li>
     * </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);

    /**
     * Cancel one or more pending airdrops.
     * <p>
     * This transaction MUST be signed by _each_ account *sending* an airdrop to be canceled.
     */
    rpc cancelAirdrop (Transaction) returns (TransactionResponse);

    /**
     * Claim one or more pending airdrops.
     * <p>
     * This transaction MUST be signed by _each_ account **receiving** an
     * airdrop to be claimed.<br>
     * If a "Sender" lacks sufficient balance to fulfill the airdrop at the
     * time the claim is made, that claim SHALL fail.
     */
    rpc claimAirdrop (Transaction) returns (TransactionResponse);

}