GitHub Logo HIP-906: Proxy Redirect Contract for Hbar Allowance and Approval

Author Luke Lee, Michael Kantor
Working Group Nana Essilfie-Conduah
Requested By Michael Kantor <@kantorcodes>, Ariane Labs <@ArianeLabs>
Discussions-To https://github.com/hashgraph/hedera-improvement-proposal/discussions/906
Status Accepted
Needs Council Approval Yes
Review period ends Wed, 01 May 2024 07:00:00 +0000
Type Standards Track
Category Service
Created 2024-02-23
Updated 2024-05-08
Requires 632

Abstract

The Smart Contract service currently provides functionality to grant allowance and approval for tokens from an owner account to a spender account. However, there is currently no way to grant allowance and approval for hbars from an owner account using the Smart Contract service. This HIP proposes to remedy this omission.

Motivation

Smart Contracts developers face an obstacle when implementing certain use cases for transferring hbars between accounts and contracts. The lack of a mechanism to grant allowance and approval for hbars without using HAPI hinders developers’ workflow. Providing this functionality will enhance the developer experience and remove this limitation.

Rationale

HIP-632 proposed to introduce a new system contract for accessing Hedera account functionality (Hedera Account Service - HAS).
This HIP proposes adding missing functionality via a new interface called IHRC632, which will act on an account address, in addition to the IHederaAccountService interface which acts on a contract address.

User stories

  1. As a smart contract developer, I want to be able to grant an allowance for hbars from an EOA to a spender account or contract.
  2. As a smart contract developer, I want to be able to grant an allowance for hbars from a contract to a spender account or contract.
  3. As a smart contract developer, I want to be able to get the current allowance of hbars from an owner account to a spender account or contract.

Specification

Smart Contracts

This HIP extends the functionality of the Hedera Account Service system contract by adding another related interface, IHRC632, to support the hbarAllowance and hbarApprove function calls to EOAs. In addition, new functions will be added to the IHederaAccountService interface to support similar calls to contracts. The hbarAllowance function will be used to retrieve information about allowance granted to a spender and the hbarApprove function will allow the sender to grant to the spender an allowance of hbars.

Acting on an EOA

Similar to the way redirection to a proxy contract during EVM execution for tokens works see HIP-719, this HIP proposes to introduce a new proxy contract for accounts. During EVM execution, if the target of the current frame is an account, a call to the new proxy contract will be created and the current calldata will be injected into the proxy contract for processing by the Hedera Account Service system contract.

The bytecode for the proxy contract can be created by compiling the following contract:

// SPDX-License-Identifier: Apache-2.0
pragma solidity ^0.8.0;
contract Assembly {

    fallback() external {

        address precompileAddress = address(0x16a);
        assembly {
            mstore(0, 0xFEFEFEFEFEFEFEFEFEFEFEFEFEFEFEFEFEFEFEFEFEFEFEFE)
            calldatacopy(32, 0, calldatasize())

            let result := delegatecall(gas(), precompileAddress, 8, add(24, calldatasize()), 0, 0)
            let size := returndatasize()
            returndatacopy(0, 0, size)

            switch result
            case 0 { revert(0, size) }
            default { return(0, size) }
        }
    }
}

Note: Just as with the Hedera Token Service system contract, the Hedara Account Service system contract will not be callable using delegatecall from a contract.

The following table describes the function selector for the new hbarAllowance and hbarApprove functions and the associated function signatures and responses in IHRC632.

Function Selector Hash Function Signature Response Comments
0xbbee989e hbarAllowance(address spender) (ResponseCode, int256) The response code from the call and the amount of hbar allowances currently available to the spender
0x86aff07c hbarApprove(address spender, int256 amount) (ResponseCode) The response code from the call

The solidity interface for IHRC632 will be the following

interface IHRC632 {
    function hbarAllowance(address spender) external returns (responseCode, int256);
    function hbarApprove(address spender, int256 amount) external returns (responseCode);
}

Once the above functionality has been implemented in services, an EOA with hbars will be able to call the hbarAllowance and hbarApprove functions as follows:

IHRC632(accountAddress).hbarAllowance(spender)
IHRC632(accountAddress).hbarApprove(spender, amount)

The hbarApprove function will be callable by an EOA as long as the signatures required by the security model are met.

Acting on a Contract

The IHederaAccountService system contract will be updated to add the hbarAllowance and hbarApprove functions.
The signature of these calls will be similar to the EOA calls except that they will include the contract address as the first argument.

The following table describes the function selectors for the new hbarAllowance and hbarApprove functions and the associated function signatures and responses in IHederaAccountService.

Function Selector Hash Function Signature Response  
0xfec46666 hbarAllowance(address owner, address spender) (ResponseCode, int256) The response code from the call and the amount of hbar allowances currently available to the spender
0xa0918464 hbarApprove(address owner, address spender, int256 amount) ResponseCode The response code from the call

The solidity interface for IHederaAccountService will be the following after this HIP is implemented:

interface IHederaAccountService {
    ...
    function hbarAllowance(address owner, address spender) external returns (responseCode, int256);
    function hbarApprove(address owner, address spender, int256 amount) external returns (responseCode);
    ...
}

Once the above functionality has been implemented in services, a contract with hbars will be able to call the hbarAllowance and hbarApprove functions as follows:

``` SampleContract is HederaAccountService { function someFunction() { …
this.hbarAllowance(owner, spender) this.hbarApprove(owner, spender, amount) … } }

The hbarApprove function will be callable by a contract as long as the signatures required by the security model are met.

Key Benefits and Possible Use Cases

Key benefits include:

  1. Better developer experience. Developers will not have to use the SDK to perform tasks that will be available via this HIP.
  2. Support for potentially new flows for DAPs such as DEFI and token marketplaces.
  3. Differentiates Hedera from other chains that do not allow an allowance/approval mechanism for their native tokens.

Potential use cases that have been communicated by the community include uses for NFT marketplaces to overcome signing requirements that can cause friction. For example in a marketplace application, a contract can act as an agent for an EOA to hold balances of hbar, fungible tokens and non-fungible tokens. This HIP enables this contract to grant an allowance to another contract who can act as a broker by gathering all the necessary allowances to enable an exchange. Using the allowance mechanism can alleviate the need for an EOA to sign transactions for such use cases as royalty fallback fees.

Updates via HAPI

It is possible that the approved allowances for a spender can be spent or increased by submitting a separate approval transaction via HAPI. In this case, the smart contract would not be aware of these changes in state and it could possibly hold stale state. While it would be possible for EVM transactions to emit an event to communicate such updates to interested parties, such a facility for HAPI transaction updates are not considered at this time.

Mirror Node Explorer

It is recommended that the Mirror Node Explorer be updated to reflect allowance details that pertain to contracts as well as account.

Backwards Compatibility

As this is new functionality there is no concern for backwards compatibility. The new proposed functionality provides an avenue for accessing existing allowance and approval functionality available via HAPI to smart contracts and thus conform to existing rules and limitations.

Security Implications

Granting an allowance to a spender account or contract opens up the owner to possible unwanted loss of hbars and thus security considerations must be paramount when implementing this functionality. Thorough testing will be required to ensure that only the intended spender account or contract can spend the owners hbars.

How to Teach This

The hbarAllowance and hbarApprove functions can be accessed by an EOA by calling the IHRC632 interface as described above. In addition, these calls will be accessible to contracts by the additions to the IHederaAccountService interface. This enhances the functionality and use cases available to the smart contract developer.

Open Issues

References

HIP-632 HIP-719

Copyright/license

This document is licensed under the Apache License, Version 2.0 – see LICENSE or (https://www.apache.org/licenses/LICENSE-2.0)

Citation

Please cite this document as: