From 226d5b1829a2990b6aee6e8abc43f46dd9b778a2 Mon Sep 17 00:00:00 2001 From: Nana Essilfie-Conduah Date: Mon, 18 Nov 2024 01:37:17 -0500 Subject: [PATCH 1/4] Allow Setting of EVM Address by EOA Signed-off-by: Nana Essilfie-Conduah --- HIP/hip-0000-set-evm-addres-on-eoa.md | 210 ++++++++++++++++++++++++++ 1 file changed, 210 insertions(+) create mode 100644 HIP/hip-0000-set-evm-addres-on-eoa.md diff --git a/HIP/hip-0000-set-evm-addres-on-eoa.md b/HIP/hip-0000-set-evm-addres-on-eoa.md new file mode 100644 index 000000000..6128e69f8 --- /dev/null +++ b/HIP/hip-0000-set-evm-addres-on-eoa.md @@ -0,0 +1,210 @@ +--- +hip: +title: Allow Setting of EVM Address by EOA +author: Nana Essilfie-Conduah <@Nana-EC> +working-group: Richard Bair <@rbair>, Atul Mahamuni <@atul-hedera>, Ty Smith , +Serg Metelin <@sergmetelin>, Ali Nikan <@alinik4n>, Greg Scullard <@gregscullard> +requested-by: Hedera community +type: Standards Track +category: Service +needs-council-approval: Yes +status: Draft +created: 11-18-24 +discussions-to: https://github.com/hashgraph/hedera-improvement-proposal/discussions/1070 +updated: 11-18-24 +replaces: 631 +requires: 583 +--- + +## Abstract + +HIP 583 opened the doors for greater account compatibility with EVM flows by utilizing the account alias to encompass +the EVM address. However, given the static nature of the alias and concerns of complexity, existing accounts were not +allowed to update their alias and set one if it was null. This HIP aims to rectify this by allowing EOAs who have no +alias set to set it to an ECDSA key derived evm address value they own. + +This HIP also replaces the need for [HIP 631: Account Virtual Addresses](https://hips.hedera.com/hip/hip-631) as it +aimed to resolve this issue as well as provide even greater functionality. A form of HIP 631 could be revisited in the +future but not with the goal of providing address equivalence with the EVM. + +## Motivation + +The EVM address alias introduced in HIP 583 allowed for ECDSA based accounts to interact with the EVM in the same way +other EVM chains do. Particularly, functionality like the `ecrecover` that relies on the relationship between key and +address (pivotal to many DEXs) was unblocked and allowed greater EVM equivalence on the Hedera network. +However, HIP 583 intentionally provided no pathway for accounts with no alias regardless of key type (ED, EC or +complex keys). Though these accounts were afforded the hedera num account alias (long zero), this format would not +allow accounts to utilize the `ecrecover` precompile in the expected manner. +This continued incompatibility has remained and inhibited web3 EVM tooling support. + +Providing a solution to this gap is a necessity to make it easy for EVM dApps in the web3 community to come to +Hedera without needing to change their smart contracts. + +## Rationale + +[HIP 631: Account Virtual Addresses](https://hips.hedera.com/hip/hip-631) lays out the challenges faced by accounts +without an ECDSA derived EVM address that want to interact with the EVM in a way that complies with the Hedera native +model and the EVM model. However, HIP 631 offered feature rich complexity that may be difficult for DApps, wallets and +users to follow completely. + +Instead of the full HIP 631, an intermediate approach i.e. a HIP 631 Lite (this HIP) could unblock users without an +EVM address. It would enable accounts to interact with the EVM in a compliant manner regardless of the public key on +its account. + +In a sense the current network already supports the ability to set the evm address, it just requires the logic to be +set on account creation. Thus by lifting the limit of not being able to set the alias after account creation, whiles +still requiring that the current alias be unset this HIP ushers in the ability of those previously blocked accounts to +interact with the EVM as expected. + +### Foundational Concepts + +The following are some clarifying concepts to increase clarity around aliases +- Every account on the network has 1 or 2 evm addresses. Either only the Hedera num alias (long zero) or the Hedera num + alias (long zero) and an EVM address alias (standard ECDSA derived EVM address). +- When a user interacts with the EVM the network will utilize the ECDSA derived EVM address alias on an account if + present. If not it will utilize the long zero. +- Accounts with an ECDSA derived EVM address are fully compatible with expectations of contracts that utilize the + ecrecover precompile. +- Accounts without an ECDSA derived EVM address alias will not match the expectation of the ecrecover precompile + calculations. This has effects on certain DApp behaviour. +- Smart contracts can and do cache the evm address of an account and often use it to assign attributes such as access + and ownership. As a result it was important to maintain a static alias to avoid unintended differences in + expectation +- Account key rotation has no impact on the evm address utilized when an account interacts with the EVM + + + +## User stories + +1. As an existing account with an ED key but no EVM address alias, I would like to set an ECDSA derived EVM address + alias on my account that will identify my account on the EVM and allow for the correct `ecrecover` functionality. +2. As an existing account with an EC key but no EVM address alias, I would like to set an ECDSA derived EVM address + alias on my account that will identify my account on the EVM and allow for the correct `ecrecover` functionality. +3. As an existing account with a complex key but no EVM address alias, I would like to set an ECDSA derived EVM address + alias on my account that will identify my account on the EVM and allow for the correct `ecrecover` functionality. +4. As an account with an EVM address alias set after creation, I would like to set an evm address override to my + previous long zero address for a `ContractCreate` transaction. +5. As an account with an EVM address alias set after creation, I would like to set an evm address override to my + previous long zero address for a `ContractCall` transaction. + +## Specification + +The main change to the network is simple - `CryptoUpdate` transactions will support setting a new ECDSA derived +`evm_address` if the current value is unset. + +### Protobuf +```protobuf +message CryptoUpdateTransactionBody { + ... + + /** + * EOA 20-byte address to create that is derived from the keccak-256 hash of a ECDSA_SECP256K1 primitive key. + */ + bytes evm_address = 19; +} +``` + +Additionally, `ContractCreate` and `ContractCall` EVM transactions will need to support the ability to specify the +a Hedera Num Alias alias EVM address to use on the transaction. This is because on the HAPI side all aliases are +applicable and thus the flexibility of the API is important to maintain. +Also, accounts that previously had no ECDSA derived EVM address were likely created via the HAPI flow and it may +be important for an EOA to utilize the long zero address even after setting a new ECDSA derived EVM address. +For transactions that utilize the `EthereumTransaction` a compliant ECDSA derived EVM address is provided by default +when using EVM tools. + +```protobuf +message ContractCreateTransactionBody { + ... + /** + * The 20-byte EVM address to use for the given transaction. This address must be the Hedera num alias of the account. + */ + bytes evm_address_override = 21; +} + +message ContractCallTransactionBody { + ... + /** + * The 20-byte EVM address to use for the given transaction. This address must be the Hedera num alias of the account. + */ + bytes evm_address_override = 5; +} +``` + +No change is needed to expose the evm address as it is covered by the `evm_address` property on `TransactionRecord` + +### HSCS System Contract API +The HAS system contract will need to be updated to add support for a `setEVmAddressAlias()` function to expose the +`CryptoUpdate` HAPI functionality and allow EOAs to call this logic directly from dApps. + +### SDK + +SDKs will need to update the `AccountUpdateTransaction` to support the `setAlias()` function as it does on +`AccountCreateTransaction`. This will populate the `evm_address` in the `CryptoUpdateTransactionBody`to be submitted. + +`ContractCreateTransaction` and `ContractExecuteTransaction` will need to support a new `setEVmAddressOverride()` +function to set the `evm_address_override` property on the respective `ContractCreate` and `ContractCall` transactions. + +### Mirror Node + +Mirror Nodes should be sure to support the setting of the evm address value on an account when processing a +`CryptoUpdate` transaction. As in the case of a `CryptoCreate` the new value can be retrieved from the `evm_address` +property on `TransactionRecord`. +If no custom logic already exists to ignore this Mirror Nodes will be unimpaired by the change + +### Wallets + +The HIP provides opportunities for increased user functionality. +- Wallets are encouraged to create accounts with an ECDSA derived address alias +- Wallets are encouraged to support the ability for users to set an ECDSA derived alias in the future. This may require +wallets to support multiple keys for users that may decide to interchange between addresses. + +## Backwards Compatibility + +This does not break previous functionality but rather adds new scoped support for a change that is possible at account +creation time. However, it may be said that there is a behaviour change here that is important to note. This change +is accepted as the benefits of unblocking existing accounts outweighs the cons. The ability to override the address +also ensure there's a pathway for EOA to set their long zero address if needed. +Finally, it is appropriate for clients to query mirror node for accurate account details. Clients that do this will +avoid not be impacted by this change. + +## Security Implications + +Smart contracts have their logic self contained in byte code. Therefore, the implications of address changes are +dictated by each smart contract and not the network. A smart contract may cache an EOA address on first interaction and +utilize that to identify them in future. The cached address could dictate balance access or other privileged access. + +As such, an EOA that has interacted with a smart contract using their long zero address and then sets an ECDSA derived +EVM address after will be responsible for any unexpected interactions with the smart contract + +## How to Teach This + +SDK examples, blogs and tutorials on docs.hedera.com + +## Reference Implementation + + +## Rejected Ideas + +### Implement HIP 631 +[HIP 631: Account Virtual Addresses](https://hips.hedera.com/hip/hip-631) would have added the ability add evm address +and specify any one of them as the desired address for use. However, this didn't unblock existing account and offered +likely complex UX that would overcomplicated the issue at this time. Focusing on setting aliases that were already null +and supporting evm address only for accounts that migrated themselves provides a solution that is focused and less +complex. + +## Open Issues + +While a HIP is in draft, ideas can come up which warrant further discussion. Those ideas should be recorded so people +know that they are being thought about but do not have a concrete resolution. This helps make sure all issues required +for the HIP to be ready for consideration are complete and reduces people duplicating prior discussions. + +## References + + + +## Copyright/license + +This document is licensed under the Apache License, Version 2.0 -- see [LICENSE](../LICENSE) or +(https://www.apache.org/licenses/LICENSE-2.0) From fe1a3c1849d310fc3f6a29679ef27e2ffcaf0873 Mon Sep 17 00:00:00 2001 From: Nana Essilfie-Conduah Date: Mon, 18 Nov 2024 01:41:01 -0500 Subject: [PATCH 2/4] Renamed file to HIP 1082 Signed-off-by: Nana Essilfie-Conduah --- HIP/{hip-0000-set-evm-addres-on-eoa.md => hip-1082.md} | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) rename HIP/{hip-0000-set-evm-addres-on-eoa.md => hip-1082.md} (99%) diff --git a/HIP/hip-0000-set-evm-addres-on-eoa.md b/HIP/hip-1082.md similarity index 99% rename from HIP/hip-0000-set-evm-addres-on-eoa.md rename to HIP/hip-1082.md index 6128e69f8..a3494a243 100644 --- a/HIP/hip-0000-set-evm-addres-on-eoa.md +++ b/HIP/hip-1082.md @@ -1,5 +1,5 @@ --- -hip: +hip: 1082 title: Allow Setting of EVM Address by EOA author: Nana Essilfie-Conduah <@Nana-EC> working-group: Richard Bair <@rbair>, Atul Mahamuni <@atul-hedera>, Ty Smith , From ef50d53941fb2a30feecaa36e2eaf2a78ecffdc7 Mon Sep 17 00:00:00 2001 From: Nana Essilfie-Conduah Date: Fri, 6 Dec 2024 22:57:09 -0500 Subject: [PATCH 3/4] Address feedback, thanks Ty and Greg Signed-off-by: Nana Essilfie-Conduah --- HIP/hip-1082.md | 25 +++++++++++++++---------- 1 file changed, 15 insertions(+), 10 deletions(-) diff --git a/HIP/hip-1082.md b/HIP/hip-1082.md index a3494a243..e6c2f10ac 100644 --- a/HIP/hip-1082.md +++ b/HIP/hip-1082.md @@ -11,7 +11,7 @@ needs-council-approval: Yes status: Draft created: 11-18-24 discussions-to: https://github.com/hashgraph/hedera-improvement-proposal/discussions/1070 -updated: 11-18-24 +updated: 12-06-24 replaces: 631 requires: 583 --- @@ -32,7 +32,7 @@ future but not with the goal of providing address equivalence with the EVM. The EVM address alias introduced in HIP 583 allowed for ECDSA based accounts to interact with the EVM in the same way other EVM chains do. Particularly, functionality like the `ecrecover` that relies on the relationship between key and address (pivotal to many DEXs) was unblocked and allowed greater EVM equivalence on the Hedera network. -However, HIP 583 intentionally provided no pathway for accounts with no alias regardless of key type (ED, EC or +However, HIP 583 intentionally provided no solution for accounts with no alias regardless of key type (ED, EC or complex keys). Though these accounts were afforded the hedera num account alias (long zero), this format would not allow accounts to utilize the `ecrecover` precompile in the expected manner. This continued incompatibility has remained and inhibited web3 EVM tooling support. @@ -52,8 +52,8 @@ EVM address. It would enable accounts to interact with the EVM in a compliant ma its account. In a sense the current network already supports the ability to set the evm address, it just requires the logic to be -set on account creation. Thus by lifting the limit of not being able to set the alias after account creation, whiles -still requiring that the current alias be unset this HIP ushers in the ability of those previously blocked accounts to +done on account creation. Thus by lifting the limit of not being able to set the alias after account creation, whiles +still requiring that the current alias be unset this HIP ushers in the ability for those previously blocked accounts to interact with the EVM as expected. ### Foundational Concepts @@ -79,14 +79,17 @@ The following are some clarifying concepts to increase clarity around aliases ## User stories 1. As an existing account with an ED key but no EVM address alias, I would like to set an ECDSA derived EVM address - alias on my account that will identify my account on the EVM and allow for the correct `ecrecover` functionality. + alias on my account that will identify my account on the EVM. 2. As an existing account with an EC key but no EVM address alias, I would like to set an ECDSA derived EVM address - alias on my account that will identify my account on the EVM and allow for the correct `ecrecover` functionality. + alias on my account that will identify my account on the EVM. 3. As an existing account with a complex key but no EVM address alias, I would like to set an ECDSA derived EVM address - alias on my account that will identify my account on the EVM and allow for the correct `ecrecover` functionality. -4. As an account with an EVM address alias set after creation, I would like to set an evm address override to my - previous long zero address for a `ContractCreate` transaction. + alias on my account that will identify my account on the EVM. +5. As an existing account with a newly set ECDSA derived EVM address, I want my account to conform with `ecrecover` + expectations as long as I sign the transaction with the ECDSA key that corresponds to the EVM address alias. + This key may or may not be the key currently on my account. 5. As an account with an EVM address alias set after creation, I would like to set an evm address override to my + previous long zero address for a `ContractCreate` transaction. +6. As an account with an EVM address alias set after creation, I would like to set an evm address override to my previous long zero address for a `ContractCall` transaction. ## Specification @@ -176,7 +179,9 @@ dictated by each smart contract and not the network. A smart contract may cache utilize that to identify them in future. The cached address could dictate balance access or other privileged access. As such, an EOA that has interacted with a smart contract using their long zero address and then sets an ECDSA derived -EVM address after will be responsible for any unexpected interactions with the smart contract +EVM address after will be responsible for any unexpected interactions with the smart contract. +It is advised that an EOA in this case first transfer all in contract storage assets to the EVM address prior to +setting their alias. ## How to Teach This From 6ab73e0d50d56feb919832cbb63876508b3f41f4 Mon Sep 17 00:00:00 2001 From: Nana Essilfie-Conduah Date: Mon, 16 Dec 2024 15:25:29 -0500 Subject: [PATCH 4/4] Adds SDK method suggestions and addresses suggestions from hendrikebbers and IvanKavaldzhiev Signed-off-by: Nana Essilfie-Conduah --- HIP/hip-1082.md | 20 +++++++++++++++----- 1 file changed, 15 insertions(+), 5 deletions(-) diff --git a/HIP/hip-1082.md b/HIP/hip-1082.md index e6c2f10ac..e83dca064 100644 --- a/HIP/hip-1082.md +++ b/HIP/hip-1082.md @@ -11,16 +11,17 @@ needs-council-approval: Yes status: Draft created: 11-18-24 discussions-to: https://github.com/hashgraph/hedera-improvement-proposal/discussions/1070 -updated: 12-06-24 +updated: 12-16-24 replaces: 631 requires: 583 --- ## Abstract -HIP 583 opened the doors for greater account compatibility with EVM flows by utilizing the account alias to encompass +[HIP 583](https://hips.hedera.com/hip/hip-583) opened the doors for greater account compatibility with EVM flows by +utilizing the account alias to encompass the EVM address. However, given the static nature of the alias and concerns of complexity, existing accounts were not -allowed to update their alias and set one if it was null. This HIP aims to rectify this by allowing EOAs who have no +allowed to update their alias and set one if it was `null`. This HIP aims to rectify this by allowing EOAs who have no alias set to set it to an ECDSA key derived evm address value they own. This HIP also replaces the need for [HIP 631: Account Virtual Addresses](https://hips.hedera.com/hip/hip-631) as it @@ -110,8 +111,8 @@ message CryptoUpdateTransactionBody { ``` Additionally, `ContractCreate` and `ContractCall` EVM transactions will need to support the ability to specify the -a Hedera Num Alias alias EVM address to use on the transaction. This is because on the HAPI side all aliases are -applicable and thus the flexibility of the API is important to maintain. +Hedera Num Alias address to use on the transaction. This is because on the HAPI side all aliases are applicable and +thus the flexibility of the API is important to maintain. Also, accounts that previously had no ECDSA derived EVM address were likely created via the HAPI flow and it may be important for an EOA to utilize the long zero address even after setting a new ECDSA derived EVM address. For transactions that utilize the `EthereumTransaction` a compliant ECDSA derived EVM address is provided by default @@ -149,6 +150,15 @@ SDKs will need to update the `AccountUpdateTransaction` to support the `setAlias `ContractCreateTransaction` and `ContractExecuteTransaction` will need to support a new `setEVmAddressOverride()` function to set the `evm_address_override` property on the respective `ContractCreate` and `ContractCall` transactions. +In addition to updated `AccountUpdateTransaction` functionality the SDK will want to add new methods to streamline +account key specifications by developers with considerations for alias + +- `setKeyWithAlias(ECDSAKey)` - Explicitly calls out the alias set and converts public key to address in the background +- `setKeyWithAlias(Key, ECDSAKey)` - Allows for setting the account key and a separate key that the evmAddress should + be derived from. A user must sign the transaction with both keys for this flow to be successful. +- `setKeyWithoutAlias(Key)` - Explicitly calls out that the alias is not set. This is useful for wallets that create + accounts with default keys and rotate keys later. + ### Mirror Node Mirror Nodes should be sure to support the setting of the evm address value on an account when processing a