ethereumjs-account

SYNOPSIS

This library eases the handling of Ethereum accounts, where accounts can be either external accounts or contracts (see Account Types docs).

Note that the library is not meant to be used to handle your wallet accounts, use e.g. the web3-eth-personal package from the web3.js library for that. This is just a semantic wrapper to ease the use of account data and provide functionality for reading and writing accounts from and to the Ethereum state trie.

INSTALL

npm install ethereumjs-account

BROWSER

This module work with browserify.

API

• new Account([data])
• Account Properties
• Account Methods
  • account.isEmpty()
  • account.isContract()
  • account.serialize()
  • account.toJSON()
  • account.getCode(trie, cb)
  • account.setCode(trie, code, cb)
  • account.getStorage(trie, key, cb)
  • account.setStorage(trie, key, val, cb)

new Account([data])

Creates a new account object

• data - an account can be initialized with either a buffer containing the RLP serialized account. Or an Array of buffers relating to each of the account Properties, listed in order below. For example:

var raw = [
  '0x02', //nonce
  '0x0384', //balance
  '0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421', //stateRoot
  '0xc5d2460186f7233c927e7db2dcc703c0e500b653ca82273b7bfad8045d85a470', //codeHash
]

var account = new Account(raw)

Or lastly an Object containing the Properties of the account:

var raw = {
  nonce: '',
  balance: '0x03e7',
  stateRoot: '0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421',
  codeHash: '0xc5d2460186f7233c927e7db2dcc703c0e500b653ca82273b7bfad8045d85a470',
}

var account = new Account(raw)

For Object and Array each of the elements can either be a Buffer, hex String, Number, or an object with a toBuffer method such as Bignum.

Account Properties

• nonce - The account's nonce.
• balance - The account's balance in wei.
• stateRoot - The stateRoot for the storage of the contract.
• codeHash - The hash of the code of the contract.

Account Methods

account.isEmpty()

Returns a Boolean determining if the account is empty.

account.isContract()

Returns a Boolean deteremining if the account is a contract.

account.serialize()

Returns the RLP serialization of the account as a Buffer.

account.toJSON([object])

Returns the account as JSON.

• object - A Boolean that defaults to false. If object is true then this will return an Object, else it will return an Array.

account.getCode(trie, cb)

Fetches the code from the trie.

• trie - The trie storing the accounts.
• cb - The callback.

account.setCode(trie, code, cb)

Stores the code in the trie.

• trie - The trie storing the accounts.
• code - A Buffer.
• cb - The callback.

Example for getCode and setCode:

// Requires manual merkle-patricia-tree install
const SecureTrie = require('merkle-patricia-tree/secure')
const Account = require('./index.js').default

let code = Buffer.from(
  '73095e7baea6a6c7c4c2dfeb977efac326af552d873173095e7baea6a6c7c4c2dfeb977efac326af552d873157',
  'hex',
)

let raw = {
  nonce: '',
  balance: '0x03e7',
  stateRoot: '0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421',
  codeHash: '0xb30fb32201fe0486606ad451e1a61e2ae1748343cd3d411ed992ffcc0774edd4',
}

let account = new Account(raw)
let trie = new SecureTrie()

account.setCode(trie, code, function(err, codeHash) {
  console.log(`Code with hash 0x${codeHash.toString('hex')} set to trie`)
  account.getCode(trie, function(err, code) {
    console.log(`Code ${code.toString('hex')} read from trie`)
  })
})

account.getStorage(trie, key, cb)

Fetches key from the account's storage.

account.setStorage(trie, key, val, cb)

Stores a val at the key in the contract's storage.

Example for getStorage and setStorage:

// Requires manual merkle-patricia-tree install
const SecureTrie = require('merkle-patricia-tree/secure')
const Account = require('./index.js').default

let raw = {
  nonce: '',
  balance: '0x03e7',
  stateRoot: '0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421',
  codeHash: '0xb30fb32201fe0486606ad451e1a61e2ae1748343cd3d411ed992ffcc0774edd4',
}

let account = new Account(raw)
let trie = new SecureTrie()

let key = Buffer.from('0000000000000000000000000000000000000000', 'hex')
let value = Buffer.from('01', 'hex')

account.setStorage(trie, key, value, function(err, value) {
  account.getStorage(trie, key, function(err, value) {
    console.log(`Value ${value.toString('hex')} set and retrieved from trie.`)
  })
})

Changelog

[3.0.0] - 2019-01-14

First TypeScript based release of the library together with a switch to an ES6 class structure of the Account class. TypeScript handles ES6 transpilation a bit differently (at the end: cleaner) than babel so require syntax of the library slightly changes to:

let Account = require('ethereumjs-account').default

The library now also comes with a type declaration file distributed along with the package published.

• Migration of code base and toolchain to TypeScript, PR #27
• Updated ethereumjs-util dependency to v6.0.0