caver.wallet.keyring
Last updated
Last updated
caver.wallet.keyring
is a package that provides functionality related to Keyring which includes address and private key(s).
Keyring
is a structure that contains the address of the account and the private key(s). This is a class in caver-js that allows users to sign on using their own Klaytn's account.
Keyring
can be classified into three types depending on the type of key being stored: SingleKeyring to store one address and one private key, MultipleKeyring to store one address and multiple private keys, and RoleBasedKeyring to store one address and one or more private keys for each role.
SingleKeyring: User signs with a private key
MultipleKeyring: User signs with private keys
RoleBasedKeyring: User signs with the private key(s) by role
SingleKeyring
is a class that stores the address
of the account and a private key
. To create a SingleKeyring instance with a private key string, please refer to caver.wallet.keyring.create.
SingleKeyring
uses a private key with which no roles assigned.
properties
Name | Type | Description |
---|---|---|
MultipleKeyring
is a class that stores the address
of the account and the multiple private keys
. To create a MultipleKeyring instance with private key strings, please refer to caver.wallet.keyring.create.
MultipleKeyring
uses private keys with which no roles assigned.
properties
RoleBasedKeyring
is a class that stores the address
of the account and the private keys
to be used for each role in the form of an array.
RoleBasedKeyring
defines keys
which is implemented as a two-dimensional array (empty keys
looks like [ [], [], [] ]
) that can include multiple keys for each role. The first array element defines the private key(s) for roleTransactionKey
, the second defines private key(s) for roleAccountUpdateKey
, and the third defines the private key(s) for roleFeePayerKey
.
properties
Below is a getter defined in keyring to intuitively use the key defined for each role. The key used for each role can be accessed more easily through the getter below.
PrivateKey
is a class that contains a private key string. The private key to be used for each role in Keyring is defined as this PrivateKey
instance.
properties
SignatureData
is a class that contains signature data inside. The signature which is the result of sign
or signMessage
will be returned as a signatureData. You can see how signatureData contains signature(s) inside like below.
properties
Generates a SingleKeyring instance with a randomly generated private key.
Parameters
Return Value
Example
Generates a private key string.
Parameters
Return Value
Example
Generates private key strings.
Parameters
Return Value
Example
Generates a 2D array of which each array element contains keys defined for each role.
Parameters
Return Value
Example
Creates a Keyring instance with parameters.
If key
is a private key string, a SingleKeyring instance that uses a single private key is created. If key
is an array containing private key strings, a MultipleKeyring instance that use multiple private keys is created. If key
is a 2D array of which each element contains the private key(s) to be used for each role, a RoleBasedKeyring instance is created.
Parameters
Return Value
Example
Creates a SingleKeyring
instance from a private key string or a KlaytnWalletKey.
Parameters
Return Value
Example
Creates a SingleKeyring
instance from a KlaytnWalletKey string.
Parameters
Return Value
Example
Creates a SingleKeyring
instance from an address and a private key string.
Parameters
Return Value
Example
Creates a MultipleKeyring
instance from an address and private key strings.
Parameters
Return Value
Example
Creates a RoleBasedKeyring
instance from an address and a 2D array of which each array element contains keys defined for each role.
Parameters
Return Value
Example
Decrypts a keystore v3 or v4 JSON and returns the decrypted Keyring instance.
Parameters
Return Value
Example
Returns the public key string(s). If keyring
is an instance of SingleKeyring, getPublicKey returns a public key string. If keyring
is an instance of MultipleKeyring, getPublicKey returns an array of public key strings. If keyring
is an instance of RoleBasedKeyring, getPublicKey returns a two-dimensional array in which the public key(s) used for each role is defined as an array.
Parameters
Return Value
Example
Returns a copied keyring instance.
Return Value
Example
Signs with transactionHash with the private key(s) and returns signature(s). If the user has not defined an index parameter, keyring.sign
signs transaction using all the private keys used by the role. If index
is defined, the keyring.sign
signs transaction using only one private key at the index. The role used in caver-js can be checked through caver.wallet.keyring.role
.
When signing transactions, it is recommended to use caver.wallet.sign or transaction.sign.
Parameters
Return Value
Example
Signs with hashed data using the private key and returns a signature where V is 0 or 1 (parity of the y-value of a the secp256k1 curve).
This function is only used for certain transaction types. Therefore, it is recommended to use caver.wallet.sign or transaction.sign when signing a transaction.
Parameters
Return Value
Example
Signs message with Klaytn-specific prefix. This calculates a Klaytn-specific signature with:
If the user has not defined the index parameter, keyring.signMessage
signs message with all the private keys used by the role. If the index parameter is given, keyring.signMessage
signs message using only one private key at the given index. The role used in caver-js can be found through caver.wallet.keyring.role
.
Parameters
Return Value
The returned object contains the following:
Example
Returns the private key(s) used by the role entered as a parameter.
Parameters
Return Value
Example
Returns the KlaytnWalletKey string for the keyring. With MultipleKeyring or RoleBasedKeyring, KlaytnWalletKey cannot be used. In this case, use keyring.encrypt.
Return Value
Example
Returns the Account instance for updating the AccountKey of the Klaytn accounts. The Account instance has an AccountKey instance that can contain public key(s) inside, which will be sent to Klaytn Network and used for validating transactions. For more details about Account, see Account Update.
Note that if you update the AccountKey of the Account stored in the Klaytn, the old private key(s) cannot be used anymore. See Getting started on how to use the returned Account instance to update information in your Klaytn account on Klaytn.
Depending on the type of the private key(s) in the keyring, the returned Account instances can be classified as follows.
When the keyring contains a private key string: Return an Account instance that includes the address in the keyring and an instance of AccountKeyPublic
When the keyring contains private key strings: Return an Account instance that includes the address in the keyring and an instance of AccountKeyWeigthedMultiSig
When the keyring contains the different private key strings by role: Return an Account instance that includes the address in the keyring and an instance of AccountKeyRoleBased
Parameters
Return Value
Example
Encrypts a keyring and returns a keystore v4 standard. For more information, please refer to KIP-3.
Parameters
Return Value
The returned object contains the following:
For more information, please refer to KIP-3.
Example
Encrypts an instance of SingleKeyring and returns a keystore v3 standard.
Note that MultipleKeyring and RoleBasedKeyring cannot use encryptV3. In this case, please use keyring.encrypt with a keystore V4 standard.
Parameters
Return Value
The returned object contains the following:
Example
Returns true
if keyring has decoupled key.
Return Value
Example
Name | Type | Description |
---|---|---|
Name | Type | Description |
---|---|---|
Name | Type | Description |
---|---|---|
Name | Type | Description |
---|---|---|
Name | Type | Description |
---|---|---|
Name | Type | Description |
---|---|---|
Type | Description |
---|---|
Name | Type | Description |
---|---|---|
Type | Description |
---|---|
Name | Type | Description |
---|---|---|
Type | Description |
---|---|
Name | Type | Description |
---|---|---|
Type | Description |
---|---|
Name | Type | Description |
---|---|---|
Type | Description |
---|---|
Name | Type | Description |
---|---|---|
Type | Description |
---|---|
Name | Type | Description |
---|---|---|
Type | Description |
---|---|
Name | Type | Description |
---|---|---|
Type | Description |
---|---|
Name | Type | Description |
---|---|---|
Type | Description |
---|---|
Name | Type | Description |
---|---|---|
Type | Description |
---|---|
Name | Type | Description |
---|---|---|
Type | Description |
---|---|
Name | Type | Description |
---|---|---|
Type | Description |
---|---|
Type | Description |
---|---|
Name | Type | Description |
---|---|---|
Type | Description |
---|---|
Name | Type | Description |
---|---|---|
Type | Description |
---|---|
Name | Type | Description |
---|---|---|
Type | Description |
---|---|
Name | Type | Description |
---|---|---|
Name | Type | Description |
---|---|---|
Type | Description |
---|---|
Type | Description |
---|---|
Name | Type | Description |
---|---|---|
Type | Description |
---|---|
Name | Type | Description |
---|---|---|
Type | Description |
---|---|
Name | Type | Description |
---|---|---|
Name | Type | Description |
---|---|---|
Type | Description |
---|---|
Name | Type | Description |
---|---|---|
Type | Description |
---|---|
address
string
The address of the account.
key
An instance of PrivateKey containing one private key inside.
address
string
The address of the account.
keys
Array
An array of PrivateKey instances containing one private key inside.
address
string
The address of the account.
keys
Array
A two-dimensional array that defines the keys used for each role. Each role includes PrivateKey instance(s). The first element in this is roleTransactionKey
. The second element is roleAccountUpdateKey
. The last element is roleFeePayerKey
.
roleTransactionKey
Array
The roleTransactionKey used to sign transactions (except for transactions for the account update). keyring.roleTransactionkey
will return the first element of keys
property.
roleAccountUpdateKey
Array
The roleAccountUpdateKey used to sign account update transactions. keyring.roleAccountUpdateKey
will return the second element of keys
property.
roleFeePayerKey
Array
The roleFeePayerKey used to sign transactions as a fee payer. keyring.roleFeePayerKey
will return the thrid element of keys
property.
privateKey
string
The private key string.
v
String
ECDSA recovery id.
r
String
ECDSA signature r.
s
String
ECDSA signature s.
entropy
string
(optional) A random string to increase entropy.
A randomly generated single keyring instance is returned.
entropy
string
(optional) A random string to increase entropy.
string
The private key string is returned.
num
number
The number of private key strings.
entropy
string
(optional) A random string to increase entropy.
Array
An array that includes private key strings is returned.
numArray
Array
An array containing the number of keys for each role.
entropy
string
(optional) A random string to increase entropy.
Array
A 2D array of which each array element contains keys defined for each role is returned.
address
string
An address of keyring.
key
string | Array
The private key string, an array of private keys, or a 2D array of which each element contains key(s) to be used for each role.
Keyring
The keyring instance is returned. Depending on the key
parameter, it can be SingleKeyring, MultipleKeyring or RoleBasedKeyring.
key
string
This parameter can be either a private key or KlaytnWalletKey.
The SingleKeyring instance is returned.
klaytnWalletKey
string
The KlaytnWalletKey string.
The SingleKeyring instance is returned.
address
string
An address to be used for creating a keyring.
key
string
A private key string.
The SingleKeyring instance is returned.
address
string
An address of keyring.
keyArray
Array
An array of private key strings.
The MultipleKeyring instance is returned.
address
string
An address of keyring.
roledBasedKeyArray
Array
A two-dimensional array containing arrays of private key strings for each role.
The RoleBasedKeyring instance is returned.
keystore
object
The keystore v3 or v4 to decrypt.
password
string
The password used for encryption.
Keyring
The decrypted keyring instance (SingleKeyring, MultipleKeyring or RoleBasedKeyring).
compressed
boolean
(optional) Whether in compressed format or not (default: false
).
string | Array
The public key of the keyring.
Keyring
A copied keyring instance (SingleKeyring, MultipleKeyring or RoleBasedKeyring).
transactionHash
string
The hash string of a transaction to sign.
chainId
string | number
The chain id of the Klaytn blockchain platform.
role
number
A number indicating the role of the key. You can use caver.wallet.keyring.role
.
index
number
(optional) The index of the private key you want to use. The index must be less than the length of the array of the private keys defined for each role. If an index is not defined, this method will use all the private keys.
Array
An array of SignatureData.
hash
string
The hash string to sign.
role
number
A number indicating the role of the key. You can use caver.wallet.keyring.role
.
index
number
(optional) The index of the private key you want to use. The index must be less than the length of the array of the private keys defined for each role. If an index is not defined, this method will use all the private keys.
Array
An array of SignatureData.
message
string
The message to sign.
role
number
A number indicating the role of the key. You can use caver.wallet.keyring.role
.
index
number
(optional) The index of the private key you want to use. The index must be less than the length of the array of the private keys defined for each role. If an index is not defined, this method will use all the private keys.
object
An object that includes the result of signing.
messageHash
string
The hash of message with Klaytn-specific prefix.
signatures
Array
An array of SignatureData.
message
string
The message to sign.
role
number
A number indicating the role of the key. You can use caver.wallet.keyring.role
.
PrivateKey | Array
An instance of PrivateKey or an array containing the PrivateKey instances used by the role.
string
The KlaytnWalletKey of the keyring.
options
WeightedMultiSigOptions | Array
(optional) WeightedMultiSigOptions instance containing information that should be defined when updating your existing account to the one with a number of private keys. If keyring uses different private keys for each role, a WeightedMultiSigOptions instance must be defined for each role in an array. If keyring uses more than one private key and options parameter is not defined, the default WeightedMultiSigOptions with the threshold of 1 and the weight of 1 for each key will be used.
An Account instance to be used when a user updates AccountKey for their account in the Klaytn. Note that if you want to replace the existing keyring (or the existing private key(s)) with a new keyring (or a new private key(s)) for your account, you must update your AccountKey by sending an Account Update transaction to Klaytn beforehand.
password
string
The password to be used for encryption. The encrypted key store can be decrypted with this password.
options
string
(optional) The options
parameter allows you to specify the values to use when using encrypt.
object
The encrypted keystore v4.
version
number
The version of keystore.
id
string
The id of keystore.
address
string
The address in the encrypted Keyring.
keyring
Array
The encrypted private key(s).
password
string
The password to be used for encryption. The encrypted key store can be decrypted with this password.
options
string
(optional) The password to be used for encryption. The encrypted key store can be decrypted with this password.
object
The encrypted keystore v3.
version
number
The version of keystore.
id
string
The id of keystore.
address
string
The address of encrypted Keyring.
crypto
object
The encrypted private key.
boolean
true
if keyring has decoupled key.