smart_contract_service.proto

/**
 * # Smart Contract Service
 * gRPC service definitions for calls to the Hedera EVM-compatible
 * Smart Contract service.
 *
 * ### 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 proto;

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

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

/**
 * The Hedera Smart Contract Service (HSCS) provides an interface to an EVM
 * compatible environment to create, store, manage, and execute smart contract
 * calls. Smart Contracts implement useful and often highly complex
 * interactions between individuals, systems, and the distributed ledger.
 */
service SmartContractService {
    /**
     * Create a new smart contract.
     * <p>
     * If this transaction succeeds, the `ContractID` for the new smart
     * contract SHALL be set in the transaction receipt.<br/>
     * The contract is defined by the initial bytecode (or `initcode`).
     * The `initcode` SHALL be provided either in a previously created file,
     * or in the transaction body itself for very small contracts.<br/>
     * As part of contract creation, the constructor defined for the new
     * smart contract SHALL run with the parameters provided in
     * the `constructorParameters` field.<br/>
     * The gas to "power" that constructor MUST be provided via the `gas`
     * field, and SHALL be charged to the payer for this transaction.<br/>
     * If the contract _constructor_ stores information, it is charged gas for
     * that storage. There is a separate fee in HBAR to maintain that storage
     * until the expiration, and that fee SHALL be added to this transaction
     * as part of the _transaction fee_, rather than gas.
     */
    rpc createContract (Transaction) returns (TransactionResponse);

    /**
     * Modify a smart contract.<br/>
     * Any change other than updating the expiration time requires that the
     * contract be modifiable (has a valid `adminKey`) and that the
     * transaction be signed by the `adminKey`
     * <p>
     * Fields _not set_ on the request SHALL NOT be modified.
     */
    rpc updateContract (Transaction) returns (TransactionResponse);

    /**
     * Call a function of a given smart contract, providing function parameter
     * inputs as needed.
     * <p>
     * Resource ("gas") charges SHALL include all relevant fees incurred by
     * the contract execution, including any storage required.<br/>
     * The total transaction fee SHALL incorporate all of the "gas" actually
     * consumed as well as the standard fees for transaction handling,
     * data transfers, signature verification, etc...
     */
    rpc contractCallMethod (Transaction) returns (TransactionResponse);

    /**
     * Call a query function of a given smart contract, providing
     * function parameter inputs as needed.<br/>
     * This is performed locally on the particular node that the client is
     * communicating with. Executing the call locally is faster and less
     * costly, but imposes certain restrictions.
     * <p>
     * The call MUST NOT change the state of the contract instance. This also
     * precludes any expenditure or transfer of HBAR or other tokens.<br/>
     * The call SHALL NOT have a separate consensus timestamp.<br/>
     * The call SHALL NOT generate a record nor a receipt.<br/>
     * The response SHALL contain the output returned by the function call.<br/>
     * <p>
     * This is generally useful for calling accessor functions which read
     * (query) state without changes or side effects. Any contract call that
     * would use the `STATICCALL` opcode MAY be called via contract call local
     * with performance and cost benefits.
     * <p>
     * Unlike a ContractCall transaction, the node SHALL always consume the
     * _entire_ amount of offered "gas" in determining the fee for this query,
     * so accurate gas estimation is important.
     */
    rpc contractCallLocalMethod (Query) returns (Response);

    /**
     * A standard query to obtain detailed information for a smart contract.
     */
    rpc getContractInfo (Query) returns (Response);

    /**
     * A standard query to read the current bytecode for a smart contract.
     */
    rpc ContractGetBytecode (Query) returns (Response);

    /**
     * A standard query to obtain account and contract identifiers for a smart
     * contract, given the Solidity identifier for that contract.
     */
    rpc getBySolidityID (Query) returns (Response) {option deprecated = true;};

    /**
     * <blockquote>This query is no longer supported.</blockquote>
     * This query always returned an empty record list.
     */
    rpc getTxRecordByContractID (Query) returns (Response) {option deprecated = true;};

    /**
     * Delete a smart contract, and transfer any remaining HBAR balance
     * to a designated account.
     * <p>
     * If this call succeeds then all subsequent calls to that smart
     * contract SHALL fail.<br/>
     */
    rpc deleteContract (Transaction) returns (TransactionResponse);

    /**
     * Delete a smart contract, as a system-initiated deletion, this
     * SHALL NOT transfer balances.
     * <blockquote>
     * This call is an administrative function of the Hedera network, and
     * SHALL require network administration authorization.<br/>
     * This transaction MUST be signed by one of the network administration
     * accounts (typically `0.0.2` through `0.0.59`, as defined in the
     * `api-permission.properties` file).
     * </blockquote>
     * If this call succeeds then all subsequent calls to that smart
     * contract SHALL fail.<br/>
     */
    rpc systemDelete (Transaction) returns (TransactionResponse) {option deprecated = true;};

    /**
     * Un-Delete a smart contract, returning it (mostly) to its state
     * prior to deletion.
     * <p>
     * The contract to be restored MUST have been deleted via `systemDelete`.
     * If the contract was deleted via `deleteContract`, it
     * SHALL NOT be recoverable.
     * <blockquote>
     * This call is an administrative function of the Hedera network, and
     * SHALL require network administration authorization.<br/>
     * This transaction MUST be signed by one of the network administration
     * accounts (typically `0.0.2` through `0.0.59`, as defined in the
     * `api-permission.properties` file).
     * </blockquote>
     * If this call succeeds then subsequent calls to that smart
     * contract MAY succeed.<br/>
     */
    rpc systemUndelete (Transaction) returns (TransactionResponse) {option deprecated = true;};

    /**
     * Make an Ethereum transaction "call" with all data in Ethereum formats,
     * including the contract alias.
     * <p>
     * Call data MAY be in the transaction, or stored within a "File".<br/>
     * The caller MAY offer additional gas above what is offered in the call
     * data, but MAY be charged up to 80% of that value if the amount required
     * is less than this "floor" amount.
     */
    rpc callEthereum (Transaction) returns (TransactionResponse);
}