Usage
Generate the Mnemonic and Create a New Wallet
Via the console
- Click the dropdown menu next to your HD Wallet and click View Dashboard.
- Create a new set of application credentials for the wallet and store them somewhere safe. You will need for subsequent interactions with the service.
- Click GENERATE NEW WALLET
- Now you can increment through your account indices to retrieve unique accounts and signing keys as you need them.
Via the API
Similar to node connections, the HD Wallet ingress is secured via application credentials. Generate a
set of credentials against the same membership ID used to provision the wallet and construct your
fully qualified HD Wallet URL with the following syntax – https://{username}:{password}@{wallet_url}/api/v1
.
Using the fully qualified HD Wallet URL, send a POST
to the /wallets
endpoint to generate the wallet ID and seed phrase. An example call using the HD Wallet Service URL from the previous page might resemble
the following:
curl -X POST -H "$HDR_CT" https://{username}:{password}@u0n9z64z07-u0cyjmmgwt-hdwallet.us0-aws.kaleido.io/api/v1/wallets | jq
Alternatively, you can use one of the readily available API tools such as Postman to send your REST calls.
A successful wallet creation will return the wallet ID and 12 word mnemonic serving as the root seed for the wallet. For example:
{
"id": "no0008g9",
"secret": "image antique paper bonus vehicle menu budget wild tilt pitch equal lift"
}
The mnemonic should be stored safely in the same manner as you would secure a private key. This phrase is the root seed for the wallet and the only way it can be restored. The id
field is the specific path to the wallet and is used on the HTTP calls to target accounts and retrieve signing keys.
Retrieve an account and its private signing key
Once the wallet has been successfully initialized, you can enumerate an account index to retrieve an Ethereum address and its corresponding private key. This allows for the client side application to locally sign an Ethereum transaction object prior to submission. To retrieve an account and key, follow the same baseline URL:
https://{username}:{password}@{wallet_url}/api/v1
And then append /wallets/{wallet_id}/accounts/{index}
to the path. For example, using our previously created HD Wallet instance, a call to retrieve the initial account would resemble the following:
curl -X GET -H "$HDR_CT" https://{username}:{password}@u0n9z64z07-u0cyjmmgwt-hdwallet.us0-aws.kaleido.io/api/v1/wallets/no0008g9/accounts/0 | jq
This will return an Ethereum account address and its associated secp256k1 private signing key. For example:
{
"address": "0xA9337C15af4Fa03D0411fd4d1dFc7dA753A87D89",
"privateKey": "e4bffefd3dd3f9fbec0f264d6326e7cc139ac34531ededf950c5dd114ea327f6"
}
Specify an account and sign a transaction
Additionally, you can use the HD Wallet service as a signing utility by specifying an account and passing an unsigned Ethereum transaction object in the body of the call. To sign a transaction, follow the same base URL and append /wallets/{wallet_id}/accounts/{account_number}/sign
to the path. The body of the call is the standard Ethereum transaction object, with hex-encoded values for all fields except for chainID
. If desired, nonce
, gasPrice
and gasLimit
can be expressed as plaintext integers; this is up to the developer. The transaction body might resemble the following:
{
nonce: '0x1',
gasPrice: '0',
gasLimit: '10000',
to: '0xd0a6E6C54DbC68Db5db3A091B171A77407Ff7ccf',
value: '0x00',
data: '0x1',
// chainId of the Kaleido environment, displayed in the environment view in the Kaleido console UI
chainId: 1213888410
}
For example, using the wallet ID returned above, the first account in the wallet, a hex-encoded nonce of “0”, a hex-encoded data field of “1”, and a gasLimit
of 10000:
curl -X POST -H "$HDR_CT" https://{username}:{password}@u0n9z64z07-u0cyjmmgwt-hdwallet.us0-aws.kaleido.io/api/v1/wallets/no0008g9/accounts/0/sign -d '{"nonce":"0x00", "gasPrice":"0", "gasLimit":"10000", "to":"0xd0a6E6C54DbC68Db5db3A091B171A77407Ff7ccf", "value":"0x00", "data":"0x1", "chainID":"1213888410"}'
This will return the transaction signed with the private key of account 0. For example:
0xf84b02808227108080011ca0a4b459168b0d9ddf74a5723e4b6ad9d5ba6d62e5b8a72edc7222694730dc6943a03afe606962f0fe16565a8029f2a7f6c6a3adcc222ae7fe0d885942c310d3b1d6`
This is the hex string that an application would submit to the network via one of the Ethereum-compatible APIs. For example, using the sendSignedTransaction
method via the well known Web3.js library:
web3.eth.sendSignedTransaction('0xf84b02808227108080011ca0a4b459168b0d9ddf74a5723e4b6ad9d5ba6d62e5b8a72edc7222694730dc6943a03afe606962f0fe16565a8029f2a7f6c6a3adcc222ae7fe0d885942c310d3b1d6')
.on('receipt', console.log);
Transaction Management and Account Iteration
Hex-encoding, nonce management and gasLimit
values are the responsibilities of the wallet user. Once you are comfortable with your transaction modeling, you can sequentially iterate through the wallet accounts and obtain a different signing key for every transaction entering the network. This will effectively anonymize your identity for any transaction that is appended to the chain.
If complete anonymity is your desired result, then you should never use a signing key more than once. The wallet is capable of generating an infinite number of accounts and signing keys, so per-transaction incrementation is the recommended best practice.
Using with the REST API Gateway
Use the kld-from
parameter against the REST API Gateway to specify your HD Wallet service ID, wallet ID and account index for transaction signing. The full syntax is as follows:
HD-serviceID-walletID-index
The Wallet ID is a required string because you have the option to deploy multiple wallets within a single service instance, and the index enumerates the specific Ethereum account you wish to sign the transaction with. Kaleido will handle the internal API calls to retrieve the corresponding private key, and then sign, assemble and deliver the raw transaction payload to your node.
Take the following service instance and HD Wallet:
- The HD Wallet endpoint is:
https://u0b04xftrx-u0rjdo3hnw-hdwallet.us0-aws.kaleido.io
- The service ID is the second 10 character string in the URL -
u0rjdo3hnw
(the first string is the environment ID) - The wallet ID in the above example is -
soqyx9sf
Therefore, if we wanted to sign the transaction with the first account in the wallet (index 0), we would pass the following argument to kld-from
:
HD-u0rjdo3hnw-soqyx9sf-0
Inside of your REST API Gateway Swagger interface, the header would look as such:
`