HIP-632: Hedera Account Service (HAS) System Contract

Abstract

Hedera accounts have the capability to have a linked EVM address alias, an EVM address. In this way smart contracts can deal interact with Hedera accounts.

Accounts now have an organized presentation of different address formats that support historical formats and EVM equivalent formats. These addresses may be stored within smart contract state but their usefulness is limited without the ability to differentiate addresses.

These methods will be placed in the system contract for the Hedera Account Service (HAS).

Motivation

Since the same account may be referred to with two different 20-byte identifiers (EVM address alias or Hedera account num alias), to avoid issues of loss of balance and permissions it is important that developers can distinguish between Hedera Account IDs and EVM addresses and translate easily between them.

Many smart contracts utilize ECRECOVER as part of their authorization process in smart contracts. However, this is limited to ECDSA based signatures, which leaves accounts that have ED25519 and complex key types, supported by Hedera, unable to do similar authorization.

To provide good user experience and to allow Hedera users to enjoy additional feature benefits over EVM equivalanece, it is important to provide authorization options within smart contract for non-ECDSA keys.

Definitions

An account-num alias is the encoded form of a Hedera account ID’s num field - an 8-byte number padded to an EVM 20-byte address by adding 12 bytes of 0 to the front of it.

An EVM address alias is an EVM address associated with a Hedera account ID.

• The Hedera account may be a “hollow” account.

Both aliases thus present as 20-byte Ethereum addresses.

See HIP-583 for a full description of account-num aliases and EVM address aliases.

• This HIP does not address HIP-583 key aliases.

Rationale

In smart contract executions the EVM will provide msg.sender values as either an account-num alias or EVM address alias. To support authorization flows that check addresses explicitly in smart contract code, the network should support smart contract distinguishing operations that allow smart contract to distinguish between the two forms. Additionally, to support standard implicit checks the network should support system contract checks in a manner similar ECRECOVER for easy developer support.

User stories

1. As a developer I want to be able to distinguish between Hedera Account ID and aliases within a smart contract so I can resolve address mappings in balance, permission or similar scenarios.
2. As a developer I want to be able to confirm account authorization within a contract using simple ECDSA/ED2519 key raw signatures as I would on Ethereum using ECRECOVER.
3. As a developer I want to be able to confirm account authorization for ECDSA accounts within a contract without being limited to ECRECOVER.
4. As a developer I want to be able to confirm account authorization for accounts within a contract using protobuf signature maps in a similar fashion as I would on Ethereum using ECRECOVER.

Specification

A new system contract with functions to support address (Hedera Account ID and EVM address alias) mapping and authorization is proposed.

This will aid developers to support smart contract migration logic for cases where aliases are encountered. Additionally, EVM developers, who were limited to ECRECOVER authorization flows, will be able to expand authorization checks to other key types.

HAS methods here can use EVM-styled 20-byte addresses which are either Hedera account num aliases or EVM address aliases.

• In this document the word alias, by itself, means either kind of alias.

  (n.b.: See HIP-583 for definitions of Hedera account num alias and EVM address alias. Hedera key aliases, defined there, are not supported by these methods.)

isAuthorizedRaw(address, messageHash, signatureBlob) Function Usage

This function is similar to using the ECRECOVER precompile function. Ethereum uses the secp256k1 curve to produce signatures which are 65 bytes in length (length of v = 1 byte and length of r and s = 32 bytes each). ED25519 signatures are 64 bytes in length. The address given is an alias. The appropriate message hash for the key type is given.

The isAuthorizedRaw function call will perform the following steps to determine its result:

1. If not a Hedera account-num alias then return the result of isValidAlias. Otherwise (an EVM address alias):
2. If the length of the signatureBlob is 65 bytes in length (EC signature):
   • Extract v, r and s and run ECRECOVER(messageHash, v, r, s). If the alias is an EVM address alias: Return true iff the recovered address is the alias. If the alias is a Hedera account-num id: Return true if the result matches the alias on the account or if the account has a single primitive EC key then true if the result matches the address derived from that public key.
3. Otherwise, if length of signatureBlob is 64 bytes in length (ED signature):
   • Retrieve the Hedera address from the EVM address alias; if there is none return false. Determine if there is a single primitive ED key associated with the Hedera Account ID. If not return false.
   • If there is a single key, verify that the signature (the signatureBlob) signs the message hash and is attested by the account.

Calls to this method incur additional gas charges corresponding to the resource cost of validating a signature.

isAuthorized(address, message, signatureBlob) Function Usage

This function is used for Hedera account (non Ethereum) signature validation. It handles the more complex signature types which are available with Hedera accounts. One or more signatures will be encoded in protobuf format into the signatureBlob.
The message that the signatures are for is given.

The precompile function will look up the keys for the account and determine if the signatures passed in via the signatureBlob satisfy the signing requirements for the account. For example, if the account has a threshold key of needing 3 out of 4 signatures, the precompile function will validate signature against the message with each key on the account and determine if at least 3 signatures in the signatureBlob matches.

Calls to this method incur additional gas charges corresponding to the resource cost of validating a signature, plus the (variable) cost of doing a cryptographic hash on the message.

The signatureBlob could be limited to encoding the following protobuf schema definitions:

message SignatureMap {
    /**
     * Each signature pair corresponds to a unique Key required to sign the transaction.
     */
    repeated SignaturePair sigPair = 1;
}


message SignaturePair {
    /**
     * First few bytes of the public key
     */
    bytes pubKeyPrefix = 1;

    oneof signature {
        /**
         * smart contract virtual signature (always length zero)
         */
        bytes contract = 2;

        /**
         * ed25519 signature
         */
        bytes ed25519 = 3;

        /**
         * RSA-3072 signature
         */
        bytes RSA_3072 = 4;

        /**
         * ECDSA p-384 signature
         */
        bytes ECDSA_384 = 5;

        /**
         * ECDSA(secp256k1) signature
         */
        bytes ECDSA_secp256k1 = 6;
    }
}

(This method does not support ECDSA p-384 signatures or RSA signatures).

Notes

• isAuthorized takes a message, not a message hash: This is because a complex key might include both EC and ED keys, and EC and ED signatures use different cryptographic hashes.

Backwards Compatibility

This functionality is newly proposed and thus does not overwrite or alter existing functionality.

Security Implications

The ledger and the EVM maintain their authorization capabilities. In fact, it may be argued security is enhanced by the precompile support for contracts to verify both raw and protocol formatted signatures.

As always users and developers are responsible for key hygiene and proper storage of keys.

How to Teach This

Give example of using each function in context to show how they can be used to duplicate and enhance existing functionality available in Ethereum.

Reference Implementation

(New) Response Codes That Can Be Returned

• INVALID_ARGUMENT_TO_SYSTEM_CONTRACT_METHOD - an argument to a system contract method is invalid (e.g., byte array of wrong length)
• ACCOUNT_MUST_HAVE_KEY - account specified must have a key
• ACCOUNT_MUST_HAVE_PRIMITIVE_KEY - account specified must have a primitive key, i.e., not a threshold key or keylist

Rejected Ideas

• There’s no way to have an EDRECOVER similar to ECRECOVER in returning an address rather than a bool because you can’t actually get back the address from an ED25519 signature, the way ECRECOVER can.

Open Issues

References

• HIP-583 “Expand alias support in CryptoCreate & CryptoTransfer Transactions”
• ECRECOVER Precompiled Contract
• Ethereum Yellow Paper
• Protobuf restrictions for Hedera Precompile methods

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: