Wen Zhang
5 years ago
committed by
Ganesha Upadhyaya
parent
a9e825f0e3
commit
47672bcd68
@ -0,0 +1,265 @@ |
||||
/** |
||||
* @packageDocumentation |
||||
* @module harmony-account |
||||
* |
||||
*/ |
||||
|
||||
/** |
||||
1. [About This Package](#about-this-package) |
||||
2. [Usage of Account](#usage-of-account) |
||||
1. [Dependencies](#dependencies) |
||||
2. [Examples](#examples) |
||||
1. [Create a random account](#create-a-random-account) |
||||
2. [Import an existing privateKey to create Account](#import-an-existing-privatekey-to-create-account) |
||||
3. [Encrypt/Export keyStore file, Decrypt/Import keyStore file](#encryptexport-keystore-file-decryptimport-keystore-file) |
||||
4. [Address format getter](#address-format-getter) |
||||
5. [Sign a transaction](#sign-a-transaction) |
||||
3. [Usage of Wallet](#usage-of-wallet) |
||||
1. [Dependencies](#dependencies-1) |
||||
|
||||
# About This Package |
||||
|
||||
`@harmony-js/account` is dealing with account related features. |
||||
|
||||
Developers can use this packages to: |
||||
* create `Account` instance |
||||
* create `Wallet` instance |
||||
* sign `Transaction` |
||||
* convert address format |
||||
* manage `privateKey` or `mnemonic phrases` and do the `encrypt` and `decrypt` job |
||||
|
||||
There are 2 main classes in this package, `Account` and `Wallet`. |
||||
|
||||
The `Account` class is basic instance that contains most features mentioned above. |
||||
The `Wallet` class is class that stores all `Account` instance, you can do CRUD on it. |
||||
|
||||
|
||||
# Usage of Account |
||||
|
||||
## Dependencies |
||||
* "@harmony-js/network", |
||||
* "@harmony-js/staking", |
||||
* "@harmony-js/transaction", |
||||
* "@harmony-js/utils" |
||||
|
||||
|
||||
## Examples |
||||
|
||||
### Create a random account |
||||
```typescript
|
||||
|
||||
// import the Account class
|
||||
import {Account} from '@harmony-js/account' |
||||
|
||||
// Messenger is optional, by default, we have a defaultMessenger
|
||||
// If you like to change, you will import related package here.
|
||||
import { HttpProvider, Messenger } from '@harmony-js/network'; |
||||
import { ChainType, ChainID } from '@harmony-js/utils'; |
||||
|
||||
// create a custom messenger
|
||||
const customMessenger = new Messenger( |
||||
new HttpProvider('http://localhost:9500'), |
||||
ChainType.Harmony, // if you are connected to Harmony's blockchain
|
||||
ChainID.HmyLocal, // check if the chainId is correct
|
||||
) |
||||
|
||||
// to create an Account with random privateKey
|
||||
// and you can setMessenger later
|
||||
const randomAccount = new Account() |
||||
randomAccount.setMessenger(customMessenger) |
||||
|
||||
// or you can set messenger on `new`
|
||||
const randomAccountWithCustomMessenger = new Account(undefined, customMessenger) |
||||
|
||||
// you can display the account
|
||||
console.log({randomAccount,randomAccountWithCustomMessenger}) |
||||
|
||||
// or you can use static method to create an Account
|
||||
const staticCreatedAccount = Account.new() |
||||
// but you have to set messenger manually after
|
||||
staticCreatedAccount.setMessenger(customMessenger) |
||||
|
||||
console.log({staticCreatedAccount}) |
||||
|
||||
``` |
||||
|
||||
### Import an existing privateKey to create Account |
||||
|
||||
```typescript
|
||||
|
||||
// import the Account class
|
||||
import {Account} from '@harmony-js/account' |
||||
|
||||
// NOTED: Key with or without `0x` are accepted, makes no different
|
||||
// NOTED: DO NOT import `mnemonic phrase` using `Account` class, use `Wallet` instead
|
||||
const myPrivateKey = '0xe19d05c5452598e24caad4a0d85a49146f7be089515c905ae6a19e8a578a6930' |
||||
|
||||
const myAccountWithMyPrivateKey = new Account(myPrivateKey) |
||||
|
||||
// you can also import privateKey use static method
|
||||
const myAccountWithMyPrivateKeyUsingStatic = Account.add(myPrivateKey) |
||||
|
||||
console.log({ myAccountWithMyPrivateKey, myAccountWithMyPrivateKeyUsingStatic }) |
||||
|
||||
``` |
||||
|
||||
### Encrypt/Export keyStore file, Decrypt/Import keyStore file
|
||||
|
||||
```typescript
|
||||
|
||||
// import the Account class
|
||||
import {Account} from '@harmony-js/account' |
||||
|
||||
// suppose we have an account
|
||||
const myPrivateKey = '0xe19d05c5452598e24caad4a0d85a49146f7be089515c905ae6a19e8a578a6930' |
||||
const myAccountWithMyPrivateKey = new Account(myPrivateKey) |
||||
|
||||
// suppose we have a password, and we want to encrypt the account above
|
||||
const myStrongPassword = '123' |
||||
|
||||
async function encryptAndDecrypt(password) { |
||||
// we get the privateKey before encrypted as comparison
|
||||
const unencryptedPrivateKey = myAccountWithMyPrivateKey.privateKey |
||||
|
||||
// export the account to keyStore string, which will make the privateKey encrpyted
|
||||
const keyStoreFile = await myAccountWithMyPrivateKey.toFile(password) |
||||
// exported keyStoreFile
|
||||
console.log({ keyStoreFile }) |
||||
// see if the account is encrypted
|
||||
console.log(`Is this account encrypted? \n ${myAccountWithMyPrivateKey.encrypted}`) |
||||
// keystore file should be equal to encrypted privateKey
|
||||
console.log( |
||||
`Is privateKey equal to keyStore string? \n ${keyStoreFile === |
||||
myAccountWithMyPrivateKey.privateKey}`,
|
||||
) |
||||
} |
||||
|
||||
encryptAndDecrypt(myStrongPassword) |
||||
|
||||
|
||||
// suppose we have keyStorefile, in this example, we just use same password and keystore string encrypted above
|
||||
const someKeyStoreFile = |
||||
'{"version":3,"id":"62326332-3139-4839-b534-656134623066","address":"1fe3da351d9fc0c4f02de5412ad7def8aee956c5","Crypto":{"ciphertext":"b86ab81682c9f5a35738ad9bd38cd9b46c1b852ef33f16dd83068f79e20d5531","cipherparams":{"iv":"44efb5a514f34968e92cafad80566487"},"cipher":"aes-128-ctr","kdf":"scrypt","kdfparams":{"salt":"d70ae1f311601562113f98c8ebe382f52a332dca1588886e5ea91e2f8a647134","n":8192,"r":8,"p":1,"dklen":32},"mac":"7b63e4e31a75a22b7091291bb58302655b738539ef3e30b30a7a7f170f6163ef"}}' |
||||
|
||||
async function importKeyStoreFileAndDecrypt(keyStoreFile, password) { |
||||
// import keyStore string and provide the password, remember to make a new Account first
|
||||
const importedAccount = await Account.new().fromFile(keyStoreFile, password) |
||||
// the account should decypted which `Account.encrypted` is false
|
||||
console.log(`Is this account encrypted? \n ${importedAccount.encrypted}`) |
||||
// see if the privatekey is equal to unencrypted one?
|
||||
console.log( |
||||
`Is the account recovered from keystore? \n ${importedAccount.privateKey === myPrivateKey}`, |
||||
) |
||||
} |
||||
|
||||
importKeyStoreFileAndDecrypt(someKeyStoreFile, myStrongPassword) |
||||
|
||||
|
||||
``` |
||||
|
||||
|
||||
### Address format getter |
||||
|
||||
```typescript
|
||||
|
||||
// import the Account class
|
||||
import {Account} from '@harmony-js/account' |
||||
|
||||
// suppose we have an account
|
||||
const myPrivateKey = '0xe19d05c5452598e24caad4a0d85a49146f7be089515c905ae6a19e8a578a6930' |
||||
const myAccountWithMyPrivateKey = new Account(myPrivateKey) |
||||
|
||||
// Account.address is bytes20/base16 address
|
||||
console.log(myAccountWithMyPrivateKey.address) |
||||
// Account.bech32Address is bech32 format address, in Harmony, it's `one1` prefixed
|
||||
console.log(myAccountWithMyPrivateKey.bech32Address) |
||||
// Account.bech32TestNetAddress is bech32 format address, in Harmony, it's `tone1` prefixed, used in testnet
|
||||
console.log(myAccountWithMyPrivateKey.bech32TestNetAddress) |
||||
// Account.checksumAddress is checksumed address from base16
|
||||
console.log(myAccountWithMyPrivateKey.checksumAddress) |
||||
|
||||
``` |
||||
|
||||
|
||||
### Sign a transaction |
||||
|
||||
```typescript
|
||||
|
||||
// import the Account class
|
||||
import {Account} from '@harmony-js/account' |
||||
|
||||
// import Transaction class from '@harmony-js/transaction'
|
||||
import {Transaction} from '@harmony-js/transaction' |
||||
|
||||
// Messenger is optional, by default, we have a defaultMessenger
|
||||
// If you like to change, you will import related package here.
|
||||
import { HttpProvider, Messenger } from '@harmony-js/network'; |
||||
import { ChainType, ChainID, Unit } from '@harmony-js/utils'; |
||||
|
||||
// create a custom messenger
|
||||
const customMessenger = new Messenger( |
||||
new HttpProvider('http://localhost:9500'), |
||||
ChainType.Harmony, // if you are connected to Harmony's blockchain
|
||||
ChainID.HmyLocal, // check if the chainId is correct
|
||||
) |
||||
// suppose we have an account
|
||||
const myPrivateKey = '0xe19d05c5452598e24caad4a0d85a49146f7be089515c905ae6a19e8a578a6930' |
||||
const myAccountWithMyPrivateKey = new Account(myPrivateKey) |
||||
|
||||
|
||||
const txnObject = { |
||||
// token send to
|
||||
to: 'one166axnkjmghkf3df7xfvd0hn4dft8kemrza4cd2', |
||||
// amount to send
|
||||
value: '1000000000000000000000', |
||||
// gas limit, you can use string or use BN value
|
||||
gasLimit: '210000', |
||||
// send token from shardID
|
||||
shardID: 0, |
||||
// send token to toShardID
|
||||
toShardID: 0, |
||||
// gas Price, you can use Unit class, and use Gwei, then remember to use toWei(), which will be transformed to BN
|
||||
gasPrice: new Unit('100').asGwei().toWei(), |
||||
// if you set nonce manually here, and remember, the `updateNonce` of `Account.signTransaction` should be set to false
|
||||
nonce: 0, |
||||
}; |
||||
|
||||
const txn = new Transaction(txnObject, customMessenger); |
||||
|
||||
async function signTheTxn() { |
||||
// Account.signTransaction(transaction: Transaction, updateNonce?: boolean, encodeMode?: string, blockNumber?: string): Promise<Transaction>
|
||||
// If the 2nd parameter `updateNonce` is set to true, it will query and update account's nonce before it signs
|
||||
const signedTxn = await myAccountWithMyPrivateKey.signTransaction(txn, false, 'rlp', 'latest'); |
||||
|
||||
// see if the transaction is signed
|
||||
console.log(`\n see if transaction is signed: \n ${signedTxn.isSigned()} \n`); |
||||
|
||||
// get the tranaction bytes
|
||||
console.log(`\n the signed bytes is: \n ${signedTxn.getRawTransaction()} \n`); |
||||
|
||||
return signTheTxn; |
||||
} |
||||
|
||||
signTheTxn(); |
||||
``` |
||||
|
||||
|
||||
# Usage of Wallet |
||||
|
||||
## Dependencies |
||||
* "@harmony-js/crypto", |
||||
* "@harmony-js/network", |
||||
* "@harmony-js/staking", |
||||
* "@harmony-js/transaction", |
||||
* "@harmony-js/utils" |
||||
|
||||
```typescript
|
||||
|
||||
import {Wallet} from '@harmony-js/account' |
||||
|
||||
const wallet=new Wallet() |
||||
|
||||
``` |
||||
*
|
||||
*/ |
||||
export class INSTRUCTION {} |
||||
Loading…
Reference in new issue