Rekeying

Overview

Rekeying is a powerful protocol feature which enables an Algorand account holder to maintain a static public address while dynamically rotating the authoritative private spending key(s). This is accomplished by issuing a "rekey-to transaction" which sets the authorized address field within the account object. Future transaction authorization using the account's public address must be provided by the spending key(s) associated with the authorized address which may be a single key address, MultiSig address or LogicSig program address. Key management is an important concept to understand and Algorand provides tools to accomplish relevant tasks securely.

Info

The term "spending key(s)" is used throughout this document to signify that generally either a single key or a set of keys from a MultiSig account may authorize from a given public address. The address itself cannot distinguish how many spending keys are specifically required.

Account Review

The account overview page introduces keys, addresses and accounts. During initial account generation, a public key and corresponding private spending key are created and used to derive the Algorand address. This public address is commonly displayed within wallet software and remains static for each account. When you receive Algos or other assets, they will be sent to your public Algorand address. When you send from your account, the transaction must be authorized using the appropriate private spending key(s).

Authorized Addresses

The balance record of every account includes the "auth-addr" field which, when populated, defines the required authorized address to be evaluated during transaction validation. Initially, the "auth-addr" field is implicitly set to the account's "address" field and the only valid private spending key is the one created during account generation. To conserve resources, the "auth-addr" field is only stored and displayed after an authorized rekey-to transaction is confirmed by the network.

Conceptually illustrated in the image below, a "standard" account uses its private spending key to authorize from its public address. A "rekeyed" account defines the authorized address which references a distinct "foreign" address and thus requires the private spending key(s) thereof to authorize future transactions.

Accounts

Standard Account

Use the following code sample to view a standard account on BetaNet:

$ goal account dump --address NFFMZJC6H52JLEAITTJ7OIML3XCJFKIRXYRJLO4WLWIJZB7N6CTWESRAZU

Response:

{
  "addr": "NFFMZJC6H52JLEAITTJ7OIML3XCJFKIRXYRJLO4WLWIJZB7N6CTWESRAZU",
  "algo": 100000,
  [...]
}
Notice the response includes the "addr" field which is the public address. Implicitly, only the spending key associated with this address may authorize transactions for this account.

Rekeyed Account

Next, modify your command slightly to display results for this rekeyed account: L42DW7MSHP4PMIAZSDAXYTZVHTE756KGXCJYGFKCET5XHIAWLBYYNSMZQU.

Response:

{
  "addr": "L42DW7MSHP4PMIAZSDAXYTZVHTE756KGXCJYGFKCET5XHIAWLBYYNSMZQU",
  "algo": 100000,
  "spend": "NFFMZJC6H52JLEAITTJ7OIML3XCJFKIRXYRJLO4WLWIJZB7N6CTWESRAZU",
  [...]
}

This response includes the addition of the "spend" field. This is the "auth-addr" within the account object and signifies any transactions from L42DW7MSHP4PMIAZSDAXYTZVHTE756KGXCJYGFKCET5XHIAWLBYYNSMZQU must now be authorized by NFFMZJC6H52JLEAITTJ7OIML3XCJFKIRXYRJLO4WLWIJZB7N6CTWESRAZU to be confirmed by the network.

Rekey-to Transaction

A rekey-to transaction is a payment type transaction which includes the rekey-to parameter set to a well-formed Algorand address. Authorization for this transaction must be provided by the existing authorized address. As shown in the first example account above, the authorized address is implicitly the "addr" field of this account even though the "auth-addr" field is not explicitly defined. Only the private spending key of this "addr" address may be used to authorize a rekey-to transaction.

The rekey-to transaction workflow is as follows:

  • Construct a payment transaction which specifies an address for the rekey-to parameter
  • Add required signature(s) from the current authorized address
  • Send and confirm the transaction on the network
Construct Transaction

The following commands will construct an unsigned transaction file rekey.txn and inspect the contents:

$ goal clerk send --from L42DW7MSHP4PMIAZSDAXYTZVHTE756KGXCJYGFKCET5XHIAWLBYYNSMZQU \
                  --to L42DW7MSHP4PMIAZSDAXYTZVHTE756KGXCJYGFKCET5XHIAWLBYYNSMZQU \
                  --amount 0 \
                  --rekey-to NFFMZJC6H52JLEAITTJ7OIML3XCJFKIRXYRJLO4WLWIJZB7N6CTWESRAZU \
                  --out rekey.txn
$ goal clerk inspect rekey.txn

Response:

rekey.txn[0]
{
  "txn": {
    "fee": 1000,
    "fv": 4921687,
    "gen": "betanet-v1.0",
    "gh": "mFgazF+2uRS1tMiL9dsj01hJGySEmPN28B/TjjvpVW0=",
    "lv": 4922687,
    "note": "bbD6hjNZNdg=",
    "rcv": "L42DW7MSHP4PMIAZSDAXYTZVHTE756KGXCJYGFKCET5XHIAWLBYYNSMZQU",
    "rekey": "NFFMZJC6H52JLEAITTJ7OIML3XCJFKIRXYRJLO4WLWIJZB7N6CTWESRAZU",
    "snd": "L42DW7MSHP4PMIAZSDAXYTZVHTE756KGXCJYGFKCET5XHIAWLBYYNSMZQU",
    "type": "pay"
  }
}

Construction of the rekey-to transaction includes the rekey-to parameter and the value "NFFMZJC6H52JLEAITTJ7OIML3XCJFKIRXYRJLO4WLWIJZB7N6CTWESRAZU". Notice the resulting unsigned transaction output includes the "rekey" field and this value.

Add Authorized Signature(s)

Adding the current authorized signature(s) to a rekey-to transaction is required prior to sending to the network for confirmation. The "snd" field provides the address to the account object where the "auth-addr" field is defined.

Info

Examples provided below demonstrate the commands in detail and allow you to rekey accounts in various scenarios.

Send and Confirm

Once all of the required signatures are gathered into a single signed transaction, it may be sent to the network for confirmation. The result for the sample account is:

{
  "addr": "L42DW7MSHP4PMIAZSDAXYTZVHTE756KGXCJYGFKCET5XHIAWLBYYNSMZQU",
  "algo": 100000,
  "spend": "NFFMZJC6H52JLEAITTJ7OIML3XCJFKIRXYRJLO4WLWIJZB7N6CTWESRAZU",
  [...]
}

Conclusion

The result of a confirmed rekey-to transaction will be the "auth-addr" field of the account object is defined, modified or removed. Defining or modifying means only the private spending key(s) of the corresponding authorized address may authorize future transactions for this public address. Removing the "auth-addr" field is really an explicit assignment of the authorized address back to the "addr" field of the account object (observed implicitly because the field is not displayed).

The "auth-addr" may be specified within a rekey-to transaction as a distinct foreign address representing a single key address, MultiSig address or LogicSig program address to provide maximum flexibility in key management options.

Warning

The protocol does not validate control of the required spending key(s) associated with the authorized address defined by --rekey-to parameter when the rekey-to transaction is sent. This is by design and affords additional privacy features to the new authorized address. It is incumbent upon the user to ensure proper key management practices and --rekey-to assignments.

Use Case Scenarios

Info

Below are a series of potential use cases for rekeying various accounts.

1 - Rekey to Single Address

The first scenario rekeys a single key account with address "A" to a distinct single key account with address "B". This requires two single key accounts at time t0. The result from time t1 is transactions for address "A" must be authorized by address "B".

Rekey-to Single Key Address

Generate and Fund Accounts

Refer to the Getting Started guide to learn how to generate two accounts and fund their respective address from the Faucet. This example uses the following public addresses:

ADDR_A="UGAGADYHIUGFGRBEPHXRFI6Z73HUFZ25QP32P5FV4H6B3H3DS2JII5ZF3Q"
ADDR_B="LOWE5DE25WOXZB643JSNWPE6MGIJNBLRPU2RBAVUNI4ZU22E3N7PHYYHSY"

View the initial authorized address for Account A using goal:

$ goal account dump --address $ADDR_A

Response:

{
  "addr": "UGAGADYHIUGFGRBEPHXRFI6Z73HUFZ25QP32P5FV4H6B3H3DS2JII5ZF3Q",
  "algo": 100000,
  [...]
}

Implicitly, the authorized address is the defined as the "addr" field displayed here.

Rekey to Single Address

Account A intends to rekey its authorized address to $ADDR_B which is the public address of Account "B". This can be accomplished in a single goal command:

$ goal clerk send --from $ADDR_A --to $ADDR_A --amount 0 --rekey-to $ADDR_B

Results of goal account dump --address $ADDR_A will now display:

{
  "addr": "UGAGADYHIUGFGRBEPHXRFI6Z73HUFZ25QP32P5FV4H6B3H3DS2JII5ZF3Q",
  "algo": 199000,
  [...]
  "spend": "LOWE5DE25WOXZB643JSNWPE6MGIJNBLRPU2RBAVUNI4ZU22E3N7PHYYHSY"
}

The populated "spend" field instructs the validation protocol to only approve transactions for this account object when authorized by the spending key(s) of that address. Validators will ignore all other attempted authorizations, including those from the public address defined in the "addr" field.

TEST: Send with Auth A

The following transaction will fail because, by default, goal attempts to add the authorization using the --from parameter. However, the protocol will reject this because it is expecting the authorization from $ADDR_B due to the confirmed rekeying transaction above.

$ goal clerk send --from $ADDR_A --to $ADDR_B --amount 1000

Send from Authorized Address

Sending from the authorized address of Account "A" requires:

  • Construct an unsigned transaction from $ADDR_A
  • Sign using authorized address $ADDR_B
  • Send authorized transaction
Construct Unsigned Transaction

First, construct an unsigned transaction using goal with the --outfile flag to write the unsigned transction to a file:

$ goal clerk send --from $ADDR_A --to $ADDR_B --amount 1000 --out send-single.txn
Sign Using Authorized Address

Next, locate the wallet containing the private spending key for Account "B". The goal clerk sign command provides the flag --signer which allows specifying the proper required authorized address $ADDR_B. Notice the infile flag reads in the unsigned transaction file from above and the --outfile flag writes the signed transaction to a separate file.

$ goal clerk sign --signer $ADDR_B --infile send-single.txn --outfile send-single.stxn
TEST: Send with Auth B

Finally, send the the signed transaction file using goal:

$ goal clerk rawsend --filename send-single.stxn

This will succeed, sending the 1000 microAlgos from $ADDR_A to $ADDR_B using the private spending key of Account "B".

2 - Rekey to MultiSig Address

The second scenario rekeys a single key account with public address "A" to a MultiSig address "BC_T1". This scenario reuses both Accounts "A" and "B", adds a third Account "C" and creates a MultiSig Account "BC_T1" comprised of addresses "B" and "C" with a threshold of 1. The result will be the private spending key for $ADDR_B or $ADDR_C may authorize transaction from $ADDR_A.

Rekey-to MultiSig Address

Generate Additional Account

Follow the same procedure as above to generate a third account for use as "C".

Generate New MultiSig Account

Reference the documentation to generate MultiSig account. Ensure it uses both $ADDR_B and the new $ADDR_C with a threshold of 1 (so either "B" or "C" may authorize). Set the resulting account address to the $ADDR_BC_T1 environment variable for use below.

Rekey to MultiSig Address

Recall from scenario 1 that Account "A" has already rekeyed to $ADDR_B.

Construct Unsigned Transaction

The rekey transaction constructed for this scenario requires authorize from $ADDR_B.

$ goal clerk send --from $ADDR_A --to $ADDR_A --amount 0 --rekey-to $ADDR_BC_T1

Sign Rekey Transaction

$ goal clerk sign --signer $ADDR_B --infile rekey-multisig.txn --outfile rekey-multisig.stxn

Send and Confirm Rekey to MultiSig

$ goal clerk rawsend --filename rekey-multisig.stxn
$ goal account dump --address $ADDR_A

The rekey transaction will confirm, resulting in the "spend" field update within the account object:

{
  "addr": "UGAGADYHIUGFGRBEPHXRFI6Z73HUFZ25QP32P5FV4H6B3H3DS2JII5ZF3Q",
  "algo": 199000,
  [...]
  "spend": "NEWMULTISIGADDRESSBCT1..."
}
TEST: Send with Auth BC_T1

Use the established pattern:

  • Construct unsigned transaction
  • Sign transaction
  • Confirm transaction
$ goal clerk send --from $ADDR_A --to $ADDR_B --amount 1000 --out send-multisig-bct1.txn
$ goal clerk sign --signer $ADDR_C --infile send-multisig-bct1.txn --outfile send-multisig-bct1.stxn
$ goal clerk rawsend --filename send-multisig-bct1.stxn

This transaction will succeed as private spending key for $ADDR_C provided the authorization and meets the threshold requirement for the MultiSig account.