コンテンツへスキップ
ドキュメント/
/
/
Assign a Regular Key Pair
最終更新:
編集

Assign a Regular Key Pair

This tutorial shows how to authorize a secondary key pair, called a regular key pair, to sign future transactions. Unlike the master key pair, which is mathematically linked to the account's address, you can remove or replace the regular key pair, which is better for security.

You can use these steps to assign a regular key pair for the first time or to replace an existing regular key pair with a new one. You can use this same process for key rotation as a proactive security measure.

Goals

By following this tutorial, you should learn how to:

  • Securely generate a regular key pair and attach it to your account.
  • Submit transactions using a regular key pair.
  • Check a transaction to see if the key that was used to sign it matches a known key pair.

Prerequisites

To complete this tutorial, you should:

Source Code

You can find the complete source code for this tutorial's examples in the code samples section of this website's repository.

Steps

1. Install dependencies

From the code sample folder, use npm to install dependencies:

npm i

2. Connect and get account(s)

To get started, import the client library and instantiate an API client. For this tutorial, you need one account, which the sample code funds using the Testnet faucet; you could also use an existing account.

import xrpl from 'xrpl'

const client = new xrpl.Client('wss://s.altnet.rippletest.net:51233')
await client.connect()

console.log('Funding new wallet from faucet...')
const { wallet } = await client.fundWallet()
console.log(`Funded. Master key pair:
  Address: ${wallet.address}
  Seed: ${wallet.seed}
`)

3. Generate a key pair

Next, generate a key pair to use as the regular key pair. This is the same data type as a master key pair, so you can generate it the same way.

Warning

It's important to generate and store the key pair securely; otherwise, it may be possible for malicious actors to gain access to your account and take your money. Common errors include:

  • Getting your secret key from a remote machine, or otherwise sending your secret key in plain text over the internet.
  • Generating a key pair using a compromised software library.
  • Generating a key pair from a passphrase or other secret value that does not have enough entropy.

Use the Wallet.generate() class method to generate a key pair locally on your machine.

// Generate a new key pair to use as the regular key ---------------------------
const algorithm = 'ed25519'
const regularKeyPair = xrpl.Wallet.generate(algorithm)
console.log(`Generated regular key pair:
  Address: ${regularKeyPair.address}
  Seed: ${regularKeyPair.seed}
  Algorithm: ${algorithm}
`)

4. Send a SetRegularKey transaction

Use a SetRegularKey transaction to assign the new key pair to your account as a regular key pair.

Tip: Rotating a Regular Key
This example signs the transaction using the master key pair, but you could also use an existing regular key pair, or a multi-signing list if your account has multi-signing set up.

// Send SetRegularKey transaction ----------------------------------------------
const regularKeyTx = {
  TransactionType: 'SetRegularKey',
  Account: wallet.address,
  RegularKey: regularKeyPair.address
}
xrpl.validate(regularKeyTx)

console.log('Signing and submitting the SetRegularKey transaction:',
  JSON.stringify(regularKeyTx, null, 2))
const response = await client.submitAndWait(regularKeyTx, { wallet, autofill: true })

// Check result of the SetRegularKey transaction -------------------------------
console.log(JSON.stringify(response.result, null, 2))
const setRegularKeyResultCode = response.result.meta.TransactionResult
if (setRegularKeyResultCode === 'tesSUCCESS') {
  console.log('Regular Key set successfully.')
} else {
  console.error(`SetRegularKey failed with code ${setRegularKeyResultCode}.`)
  client.disconnect()
  process.exit(1)
}

5. Send a test transaction using the regular key

After the SetRegularKey transaction succeeds, the regular key pair is assigned to your account and you should be able to send transactions using the regular key pair. To avoid losing control of your account, it is important that you test your regular key before you take any additional steps such as disabling the master key pair. If you make a mistake and lose access to your account, no one can restore it for you.

To test the key, send any type of transaction, signing it using the regular key pair. The sample code sends an AccountSet transaction with no parameters, which is a "no-op" that does nothing besides use a sequence number and burn the transaction cost.

// Send a test transaction using the regular key -------------------------------
const testTx = {
  TransactionType: 'AccountSet',
  Account: wallet.address
}
xrpl.validate(testTx)

console.log('Signing and submitting the test transaction using the regular key')
const testResponse = await client.submitAndWait(testTx, {
  wallet: regularKeyPair, // IMPORTANT: use the regular key pair here
  autofill: true
})

6. Confirm that the test transaction succeeded as expected

If the test transaction succeeds, your regular key pair works as expected. For further confirmation, you can look at the SigningPubKey field which is automatically added to a transaction during signing; this field contains the public key of the key pair that was used to sign the transaction, and is what the network uses to validate the transaction signature. When you use your regular key pair to sign a transaction, the SigningPubKey field contains the public key from your regular key pair.

// Check result of the test transaction ----------------------------------------
console.log(JSON.stringify(testResponse.result, null, 2))
const testResultCode = testResponse.result.meta.TransactionResult
const testSigningPubKey = testResponse.result.tx_json.SigningPubKey
if (testResultCode === 'tesSUCCESS') {
  console.log('Test transaction was successful.')
} else {
  console.log(`Test transaction failed with code ${testResultCode}`)
}
if (testSigningPubKey === regularKeyPair.publicKey) {
  console.log('This transaction was signed with the regular key pair.')
} else if (testSigningPubKey === wallet.publicKey) {
  console.warn('This transaction was signed with the master key pair.')
} else {
  console.warn(`Unexpected signing key mismatch.
    Regular key: ${regularKeyPair.publicKey}
    Key used: ${testSigningPubKey}`)
}

client.disconnect()

If the transaction fails with the following result codes, here are some things to check:

  • tefBAD_AUTH: The regular key you signed your test transaction with doesn't match the regular key you set in the previous step. Check that the secret and address for your regular key pair match and double-check which values you used in each step.
  • tefBAD_AUTH_MASTER or temBAD_AUTH_MASTER: Your account doesn't have a regular key assigned. Check that the SetRegularKey transaction executed successfully. You can also use the account_info method to confirm that your regular key is set in the RegularKey field as expected.

For possible causes of other result codes, see Transaction Results.

See Also

Now that you're familiar with the benefits of assigning a regular key pair to an account, consider taking a look at these related topics and tutorials:

前のページ
次のページ