RFC: Private Key & HD Accounts

[jxom]

Summary

We have the concept of an Account in viem, that have the ability to sign messages, transactions, typed data, etc.

An account can come in two formats:

• A JSON-RPC Account: an account that does not hold a private key & performs signing over JSON-RPC.
• A Local Account: an account that holds a private key & performs signing locally before it is sent over JSON-RPC.

Right now, viem does not have first-class support for "Local Accounts", in order to use a Local Account in viem, you need to either: provide an interface or use the Ethers.js Wallet adapter.

Ideally, we should have our own implementation built-in so folks don't have to go to the extra work to build their own signer interface, or import an Ethers.js Wallet.

Examples

Local Accounts

You will be able to define either a Private Key or HD Account via the viem/account entrypoint. This entrypoint will include all the utilities needed to create a Local Account.

The viem/account entrypoint will give you the utilities to:

• Generate a Private Key
• Generate a Mnemonic Phrase
• Import a Private Key Account
• Import a HD Account (from mnemonic, master seed, extended key, or json)

import { createWalletClient, http } from 'viem'
import * as Account from 'viem/account'

const client = createWalletClient({
  transport: http()
})

// Private Key
const privateKey = Account.generatePrivateKey()
const account = Account.fromPrivateKey(privateKey)

// HD (Mnemonic)
const mnemonic = Account.generateMnemonic()
const account = Account.fromMnemonic(mnemonic, { index, path })

// HD (Others)
const account = Account.fromMasterSeed(seed, { index, path })
const account = Account.fromExtendedKey(extendedKey, { index, path }) 
const account = Account.fromJson(xpriv, { index, path })

const hash = await client.sendTransaction({ 
  account,
  to: '0xa5cc3c03994DB5b0d9A5eEdD10CabaB0813678AC',
  value: parseEther('0.001')
})

If your Account is static, it will also be possible to define an account on the Wallet Client, so you don't have to pass it to every Action that requires an account. If an Account is provided on a Client, the Account can still be overridden with the account argument on the Action level:

import { createWalletClient, http } from 'viem'
import * as Account from 'viem/account'

// Private Key
const privateKey = Account.generatePrivateKey()
const account = Account.fromPrivateKey(privateKey)

// HD (Mnemonic)
const mnemonic = Account.generateMnemonic()
const account = Account.fromMnemonic(mnemonic, { index, path })

// HD (Others)
const account = Account.fromMasterSeed(seed, { index, path })
const account = Account.fromExtendedKey(extendedKey, { index, path }) 
const account = Account.fromJson(xpriv, { index, path })

const client = createWalletClient({
+ account,
  transport: http()
})

const hash = await client.sendTransaction({ 
  // account becomes optional here, but you can still override it.
- account,
  to: '0xa5cc3c03994DB5b0d9A5eEdD10CabaB0813678AC',
  value: parseEther('0.001')
})

Detailed Design

Removal of the getAccount function

To avoid extraneous imports, I think it makes sense to remove the getAccount function we currently have, and either retrieve an account from the viem/accounts entrypoint for Local Accounts, or just specify an Address string for JSON-RPC Accounts:

Local Accounts

Taking from the example on the docs, we can replace getAccount with utilities on the viem/accounts entrypoint:

import { 
  createWalletClient, 
  http, 
- getAccount 
} from 'viem'
+ import * as Account from 'viem/account'

const client = createWalletClient({
  transport: http()
})

const privateKey = '0x...'
-const account = getAccount(...)
+const account = Account.fromPrivateKey(privateKey)

const hash = await client.sendTransaction({ 
  account,
  to: '0xa5cc3c03994DB5b0d9A5eEdD10CabaB0813678AC',
  value: parseEther('0.001')
})

JSON-RPC Accounts

Taking from the example on the docs, we can replace getAccount with just an Address string (this is all it needs to be 😄):

import { createWalletClient, custom } from 'viem'

const client = createWalletClient({
  transport: custom(window.ethereum)
})

const [address] = await client.getAddresses()
-const account = getAccount(address)

const hash = await client.sendTransaction({ 
-  account,
+ account: address,
  to: '0xa5cc3c03994DB5b0d9A5eEdD10CabaB0813678AC',
  value: parseEther('0.001')
})

Dependants

The Local Account implementation will depend on the following audited libraries:

• @noble/curves/secp256k1: secp256k1 utils (random private keys, sig utils, etc)
• @scure/bip32: HD wallet utils
• @scure/bip39: bip39 phrase utils (mnemonic phrases, phrase -> seed, etc)

Types

As mentioned earlier, there are two main types of Accounts in viem: a JSON-RPC Account, and a Local Account. The types for these will be roughly as follows:

import { Address } from 'abitype'
import { HDKey } from '@scure/bip32'

export type Account = JsonRpcAccount | LocalAccount

export type JsonRpcAccount = {
  address: Address
}

export type LocalAccount<TSource = 'custom'> = {
  address: Address
  signMessage(message: string): Promise<Hex>
  signTransaction(transaction: TransactionRequest): Promise<Hex>
  signTypedData(typedData: TypedData): Promise<Hex>
  source: TSource
}

export type PrivateKeyAccount = LocalAccount<'privateKey'> & {
  publicKey(): Hex
  privateKey(): Hex
}

export type HDAccount = LocalAccount<'hd'> & {
  hdKey(): HDKey
  publicKey(): Hex
  privateKey(): Hex
}

Utilities

On the viem/accounts entrypoint, we will expose utilities to:

• Generate a random Private Key
• Generate a random Mnemonic
• Import a Private Key Account
• Import a HD Account (from mnemonic, master seed, json or extended key)

Generating Private Keys

A user can generate a random private key using generatePrivateKey:

import { generatePrivateKey } from 'viem/account'

const privateKey = generatePrivateKey()

Generating Mnemonics

A user can generate a random English mnemonic using generateMnemonic:

import { generateMnemonic } from 'viem/account'

const mnemonic = generateMnemonic()

If a user wants to use a different language, they can also insert a wordlist from @scure/bip39:

import { generateMnemonic } from 'viem/account'
import { wordlist } from '@scure/bip39/wordlists/french';

const mnemonic = generateMnemonic({ wordlist })

Importing Private Key Accounts

A user can import a Private Key Account with their private key:

import * as Account from 'viem/account' 

const account = Account.fromPrivateKey('0x...')

// The above account will provide all the attributes on the PrivateKeyAccount type.
account.address
account.signMessage(message)
account.signTransaction(transaction)
account.signTypedData(typedData)
account.publicKey()
account.privateKey()
... etc

Importing HD Accounts

A user can import a HD Account with their mnemonic phrase, master seed, extended key or JSON. They can also derive a HD Account from an optional index or path:

import * as Account from 'viem/account' 

const account = Account.fromMnemonic('junk junk junk', { index, path })
const account = Account.fromMasterSeed(seed, { index, path })
const account = Account.fromExtendedKey(extendedKey, { index, path })
const account = Account.fromJson(xpriv, { index, path })

// The above accounts will provide all the attributes on the HDAccount type.
account.address
account.signMessage(message)
account.signTransaction(transaction)
account.signTypedData(typedData)
account.publicKey()
account.privateKey()
account.hdKey()
... etc

Importing Custom Local Accounts

Theoretically, you can also derive your own implementation of a Local Account (like the example in the docs currently). This is just a plain object following the LocalAccount type.

import type { LocalAccount } from 'viem/account'
import { getAddress, signMessage, signTransaction, signTypedData } from './sign-utils' 

const privateKey = '0x...'
const account: LocalAccount = {
  address: getAddress(privateKey),
  signMessage(message) {
    return signMessage(message, privateKey)
  },
  signTransaction(transaction) {
    return signTransaction(transaction, privateKey)
  },
  signTypedData(typedData) {
    return signTypedData(typedData, privateKey)
  }
}

// The above account will provide all the attributes on the LocalAccount type.
account.address
account.signMessage(message)
account.signTransaction(transaction)
account.signTypedData(typedData)

[tmm]

Really solid! Curious about tweaking the examples and/or names for the utilities.

If the examples/docs, use a namespace import (e.g. import * as Account), then folks will likely use that - since it's just a copy & paste away. We might want to discourage this since folks will lose access to tree-shaking, etc. Account.fromPrivateKey is nice though because it is very readable.

Instead, we could use a similar naming pattern to shortcut functions that already exist in viem:

const account = privateKeyToAccount(privateKey)
const account = mnemonicToAccount(mnemonic, { index, path })
const account = masterSeedToAccount(seed, { index, path })
const account = extendedKeyToAccount(extendedKey, { index, path }) 
const account = jsonToAccount(xpriv, { index, path })

[jxom]

yeah good point, i like this ^

[tmm]

Local accounts are now out as part of viem@0.2!