From 2dbceb2c90add7a75ed5ab0f4cfa16aada29e544 Mon Sep 17 00:00:00 2001 From: krlosMata Date: Fri, 27 Aug 2021 13:19:09 +0200 Subject: [PATCH 1/2] add spec derivation private bjj from ethereum account --- docs/developers/sdk.md | 40 ++++++++++++++++++++++++++++------------ 1 file changed, 28 insertions(+), 12 deletions(-) diff --git a/docs/developers/sdk.md b/docs/developers/sdk.md index f045b6e..5593931 100644 --- a/docs/developers/sdk.md +++ b/docs/developers/sdk.md @@ -16,17 +16,27 @@ There is an additional [Golang SDK](https://github.com/hermeznetwork/hermez-go-s ## SDK How-To (Javascript) In this tutorial we will walk through the process of using the SDK to: -1. [Installing Hermezjs](#install-hermezjs) -2. [Initializing Hermezjs](#initialization) -3. [Check registered tokens](#check-token-exists-in-hermez-network) -4. [Creating a wallet](#create-a-wallet) -5. [Making a deposit from Ethereum into the Hermez Network](#deposit-tokens-from-ethereum-into-hermez-network) -6. [Verifying the balance in a Hermez account](#verify-balance) -7. [Withdrawing funds back to Ethereum network](#withdrawing) -8. [Making transfers](#transfers) -9. [Verifying transaction status](#verifying-transaction-status) -10. [Authorizing the creation of Hermez accounts](#create-account-authorization) -11. [Internal accounts](#create-internal-accounts) +- [Examples](#examples) +- [SDK](#sdk) + - [SDK How-To (Javascript)](#sdk-how-to-javascript) + - [Install Hermezjs](#install-hermezjs) + - [Import modules](#import-modules) + - [Initialization](#initialization) + - [Create Transaction Pool](#create-transaction-pool) + - [Configure Hermez Environment](#configure-hermez-environment) + - [Check token exists in Hermez Network](#check-token-exists-in-hermez-network) + - [Create a Wallet](#create-a-wallet) + - [Derive private babyjubjub from ethereum account](#derive-private-babyjubjub-from-ethereum-account) + - [Deposit Tokens from Ethereum into Hermez Network](#deposit-tokens-from-ethereum-into-hermez-network) + - [Verify Balance](#verify-balance) + - [Withdrawing](#withdrawing) + - [Exit](#exit) + - [Withdrawing Funds from Hermez](#withdrawing-funds-from-hermez) + - [Force Exit](#force-exit) + - [Transfers](#transfers) + - [Verifying Transaction Status](#verifying-transaction-status) + - [Create Account Authorization](#create-account-authorization) + - [Create Internal Accounts](#create-internal-accounts) ## Install Hermezjs @@ -137,7 +147,13 @@ We can create a new Hermez wallet by providing the Ethereum private key of an Et const hermezEthereumAddress2 = wallet2.hermezEthereumAddress ``` - +### Derive private babyjubjub from ethereum account +The specification to derive private babyjubjub from ethereum account is the following: +- Message to be signed: `Hermez Network account access.\n\nSign this message if you are in a trusted application only.` +- Sign message with your ethereum private key: `signature = eth_sign(MESSAGE)` + - message string is parsed to bytes using utf8 conversion. Further details can be found [here](http://stackoverflow.com/questions/18729405/how-to-convert-utf8-string-to-byte-array) and [here](https://github.com/ethers-io/ethers.js/blob/ce8f1e4015c0f27bf178238770b1325136e3351a/packages/strings/src.ts/utf8.ts#L202) + - please note that the json RPC method used is `eth_sign`. Further details can be found [here](`https://eth.wiki/json-rpc/API#eth_sign`) +- The computed `signature` is then hashed using keccak256 hash to finally derive the babyjubjub private key: `privateKeyBabyjubjub = keccak256(signature)` ## Deposit Tokens from Ethereum into Hermez Network Creating a Hermez account and depositing tokens is done simultaneously as an L1 transaction. In this example we are going to deposit 1 `ETH` tokens into the newly created Hermez accounts. From 7c154b4fd693f385e9da161230ad90e704ab3bb3 Mon Sep 17 00:00:00 2001 From: krlosMata Date: Fri, 3 Sep 2021 16:11:51 +0200 Subject: [PATCH 2/2] add review comments --- docs/developers/sdk.md | 22 ++++++++++++++++------ 1 file changed, 16 insertions(+), 6 deletions(-) diff --git a/docs/developers/sdk.md b/docs/developers/sdk.md index 5593931..d680aa2 100644 --- a/docs/developers/sdk.md +++ b/docs/developers/sdk.md @@ -26,7 +26,7 @@ In this tutorial we will walk through the process of using the SDK to: - [Configure Hermez Environment](#configure-hermez-environment) - [Check token exists in Hermez Network](#check-token-exists-in-hermez-network) - [Create a Wallet](#create-a-wallet) - - [Derive private babyjubjub from ethereum account](#derive-private-babyjubjub-from-ethereum-account) + - [Derive private Babyjubjub from Ethereum account](#derive-private-babyjubjub-from-ethereum-account) - [Deposit Tokens from Ethereum into Hermez Network](#deposit-tokens-from-ethereum-into-hermez-network) - [Verify Balance](#verify-balance) - [Withdrawing](#withdrawing) @@ -147,16 +147,26 @@ We can create a new Hermez wallet by providing the Ethereum private key of an Et const hermezEthereumAddress2 = wallet2.hermezEthereumAddress ``` -### Derive private babyjubjub from ethereum account -The specification to derive private babyjubjub from ethereum account is the following: +### Derive private Babyjubjub from Ethereum account +The specification to derive private Babyjubjub from Ethereum account is the following: - Message to be signed: `Hermez Network account access.\n\nSign this message if you are in a trusted application only.` -- Sign message with your ethereum private key: `signature = eth_sign(MESSAGE)` +- Sign message with your Ethereum private key: `signature = eth_sign(MESSAGE)` - message string is parsed to bytes using utf8 conversion. Further details can be found [here](http://stackoverflow.com/questions/18729405/how-to-convert-utf8-string-to-byte-array) and [here](https://github.com/ethers-io/ethers.js/blob/ce8f1e4015c0f27bf178238770b1325136e3351a/packages/strings/src.ts/utf8.ts#L202) - please note that the json RPC method used is `eth_sign`. Further details can be found [here](`https://eth.wiki/json-rpc/API#eth_sign`) -- The computed `signature` is then hashed using keccak256 hash to finally derive the babyjubjub private key: `privateKeyBabyjubjub = keccak256(signature)` +- The computed `signature` is then hashed using keccak256 hash to finally derive the Babyjubjub private key: `privateKeyBabyjubjub = keccak256(signature)` + +> notes: +> - if ecdsa standard libraries are used instead of Ethereum specific ones, remember to add 27 to `v` signature value +> - The public Babyjubjub key is derived from the private Babyjubjub key. Hermez Network uses the public Babyjubjub key compressed form (uint256) +> - There are two representations of public Babyjubjub key: hexadecimal and base64 +> - Hexadecimal is done by converting the public Babyjubjub key compressed form (uint256) into big-endian hexadecimal string +> - Base64 is done by converting the public Babyjubjub key compressed form (uint256) into its little-endian base64 string +> - it also adds an additional checksum byte computed as the sum of all its bytes (mod $2^{8}$) which is concatenated at the end of the public Babyjubjub key compressed form + +> implementations examples can be found [here](https://github.com/hermeznetwork/hermezjs/blob/main/src/hermez-wallet.js#L33), [here](https://github.com/hermeznetwork/hermezjs/blob/main/src/addresses.js#L109) and [here](https://github.com/hermeznetwork/hermez-go-sdk/blob/main/account/creation.go#L115) ## Deposit Tokens from Ethereum into Hermez Network -Creating a Hermez account and depositing tokens is done simultaneously as an L1 transaction. In this example we are going to deposit 1 `ETH` tokens into the newly created Hermez accounts. +Creating a Hermez account and depositing tokens is done simultaneously as an L1 transaction. In this example, we are going to deposit 1 `ETH` token into the newly created Hermez accounts. ```js // set amount to deposit