tornado-packages/ethers.js
1
0
Fork 1
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
e1dce87525
ethers.js/docs/v5/api/signer/README.md
Richard Moore 716ec324d0
Check-in old v5 docs changes.
2020-06-09 23:56:58 -04:00

328 lines
11 KiB
Markdown
Raw Blame History

-----
Documentation: [html](https://docs-beta.ethers.io/)
-----
Signers
=======
Signer
------
#### *signer* . **connect**( provider ) => *[Signer](/v5/api/signer/#Signer)*
Sub-classes **must** implement this, however they may simply throw an error if changing providers is not supported.
#### *signer* . **getAddress**( ) => *Promise< string< [Address](/v5/api/utils/address/#address) > >*
Returns a Promise that resolves to the account address.
This is a Promise so that a **Signer** can be designed around an asynchronous source, such as hardware wallets.
Sub-classes **must** implement this.
#### *Signer* . **isSigner**( object ) => *boolean*
Returns true if an only if *object* is a **Signer**.
### Blockchain Methods
#### *signer* . **getBalance**( [ blockTag = "latest" ] ) => *Promise< [BigNumber](/v5/api/utils/bignumber/) >*
Returns the balance of this wallet at *blockTag*.
#### *signer* . **getChainId**( ) => *Promise< number >*
Returns ths chain ID this wallet is connected to.
#### *signer* . **getGasPrice**( ) => *Promise< [BigNumber](/v5/api/utils/bignumber/) >*
Returns the current gas price.
#### *signer* . **getTransactionCount**( [ blockTag = "latest" ] ) => *Promise< number >*
Returns the number of transactions this account has ever sent. This is the value required to be included in transactions as the `nonce`.
#### *signer* . **call**( transactionRequest ) => *Promise< string< [DataHexString](/v5/api/utils/bytes/#DataHexString) > >*
Returns the result of calling using the *transactionRequest*, with this account address being used as the `from` field.
#### *signer* . **estimateGas**( transactionRequest ) => *Promise< [BigNumber](/v5/api/utils/bignumber/) >*
Returns the result of estimating the cost to send the *transactionRequest*, with this account address being used as the `from` field.
#### *signer* . **resolveName**( ensName ) => *Promise< string< [Address](/v5/api/utils/address/#address) > >*
Returns the address associated with the *ensName*.
### Signing
#### *signer* . **signMessage**( message ) => *Promise< string< [RawSignature](/v5/api/utils/bytes/#signature-raw) > >*
This returns a Promise which resolves to the [Raw Signature](/v5/api/utils/bytes/#signature-raw) of *message*.
Sub-classes **must** implement this, however they may throw if signing a message is not supported, such as in a Contract-based Wallet or Meta-Transaction-based Wallet.
#### Note
If *message* is a string, it is **treated as a string** and converted to its representation in UTF8 bytes.
**If and only if** a message is a [Bytes](/v5/api/utils/bytes/#Bytes) will it be treated as binary data.
For example, the string `"0x1234"` is 6 characters long (and in this case 6 bytes long). This is **not** equivalent to the array `[ 0x12, 0x34 ]`, which is 2 bytes long.
A common case is to sign a hash. In this case, if the hash is a string, it **must** be converted to an array first, using the [arrayify](/v5/api/utils/bytes/#utils-arrayify) utility function.
#### *signer* . **signTransaction**( transactionRequest ) => *Promise< string< [DataHexString](/v5/api/utils/bytes/#DataHexString) > >*
Returns a Promise which resolves to the signed transaction of the *transactionRequest*. This method does not populate any missing fields.
Sub-classes **must** implement this, however they may throw if signing a transaction is not supported, which is common for security reasons in many clients.
#### *signer* . **sendTransaction**( transactionRequest ) => *Promise< [TransactionResponse](/v5/api/providers/types/#providers-TransactionResponse) >*
This method populates the transactionRequest with missing fields, using [populateTransaction](/v5/api/signer/#Signer-populateTransaction) and returns a Promise which resolves to the transaction.
Sub-classes **must** implement this, however they may throw if sending a transaction is not supported, such as the [VoidSigner](/v5/api/signer/#VoidSigner) or if the Wallet is offline and not connected to a [Provider](/v5/api/providers/provider/).
### Sub-Classes
#### *signer* . **checkTransaction**( transactionRequest ) => *[TransactionRequest](/v5/api/providers/types/#providers-TransactionRequest)*
This is generally not required to be overridden, but may needed to provide custom behaviour in sub-classes.
This should return a **copy** of the *transactionRequest*, with any properties needed by `call`, `estimateGas` and `populateTransaction` (which is used by sendTransaction). It should also throw an error if any unknown key is specified.
The default implementation checks only valid [TransactionRequest](/v5/api/providers/types/#providers-TransactionRequest) properties exist and adds `from` to the transaction if it does not exist.
If there is a `from` field it **must** be verified to be equal to the Signer's address.
#### *signer* . **populateTransaction**( transactionRequest ) => *Promise< [TransactionRequest](/v5/api/providers/types/#providers-TransactionRequest) >*
This is generally not required to be overridden, but may needed to provide custom behaviour in sub-classes.
This should return a **copy** of *transactionRequest*, follow the same procedure as `checkTransaction` and fill in any properties required for sending a transaction. The result should have all promises resolved; if needed the [resolveProperties](/v5/api/utils/properties/#utils-resolveproperties) utility function can be used for this.
The default implementation calls `checkTransaction` and resolves to if it is an ENS name, adds `gasPrice`, `nonce`, `gasLimit` and `chainId` based on the related operations on Signer.
Wallet
------
#### **new ***ethers* . **Wallet**( privateKey [ , provider ] )
Create a new Wallet instance for *privateKey* and optionally connected to the *provider*.
#### *ethers* . *Wallet* . **createRandom**( [ options = {} ] ) => *[Wallet](/v5/api/signer/#Wallet)*
Returns a new Wallet with a random private key, generated from cryptographically secure entropy sources. If the current environment does not have a secure entropy source, an error is thrown.
Wallets created using this method will have a mnemonic.
#### *ethers* . *Wallet* . **fromEncryptedJson**( json , password [ , progress ] ) => *Promise< [Wallet](/v5/api/signer/#Wallet) >*
Create an instance from an encrypted JSON wallet.
If *progress* is provided it will be called during decryption with a value between 0 and 1 indicating the progress towards completion.
#### *ethers* . *Wallet* . **fromEncryptedJsonSync**( json , password ) => *[Wallet](/v5/api/signer/#Wallet)*
Create an instance from an encrypted JSON wallet.
This operation will operate synchronously which will lock up the user interface, possibly for a non-trivial duration. Most applications should use the asynchronous `fromEncryptedJson` instead.
#### *ethers* . *Wallet* . **fromMnemonic**( mnemonic [ , path , [ wordlist ] ] ) => *[Wallet](/v5/api/signer/#Wallet)*
Create an instance from a mnemonic phrase.
If path is not specified, the Ethereum default path is used (i.e. `m/44'/60'/0'/0/0`).
If wordlist is not specified, the English Wordlist is used.
### Properties
#### *wallet* . **address** => *string< [Address](/v5/api/utils/address/#address) >*
The address for the account this Wallet represents.
#### *wallet* . **provider** => *[Provider](/v5/api/providers/provider/)*
The provider this wallet is connected to, which will ge used for any [Blockchain Methods](/v5/api/signer/#Signer--blockchain-methods) methods. This can be null.
#### Note
A **Wallet** instance is immuatable, so if you wish to change the Provider, you may use the [connect](/v5/api/signer/#Signer-connect) method to create a new instance connected to the desired provider.
#### *wallet* . **publicKey** => *string< [DataHexString](/v5/api/utils/bytes/#DataHexString)< 65 > >*
The uncompressed public key for this Wallet represents.
### Methods
#### *wallet* . **encrypt**( password , [ options = {} , [ progress ] ] ) => *Promise< string >*
Encrypt the wallet using *password* returning a Promise which resolves to a JSON wallet.
If *progress* is provided it will be called during decryption with a value between 0 and 1 indicating the progress towards completion.
```javascript
// Create a wallet instance from a mnemonic...
mnemonic = "announce room limb pattern dry unit scale effort smooth jazz weasel alcohol"
walletMnemonic = Wallet.fromMnemonic(mnemonic)
// ...or from a private key
walletPrivateKey = new Wallet(walletMnemonic.privateKey)
walletMnemonic.address === walletPrivateKey.address
//!
// The address as a Promise per the Signer API
walletMnemonic.getAddress()
//!
// A Wallet address is also available synchronously
walletMnemonic.address
//!
// The internal cryptographic components
walletMnemonic.privateKey
//!
walletMnemonic.publicKey
//!
// The wallet mnemonic
walletMnemonic.mnemonic
//!
// Note: A wallet created with a private key does not
// have a mnemonic (the derivation prevents it)
walletPrivateKey.mnemonic
//!
// Signing a message
walletMnemonic.signMessage("Hello World")
//!
tx = {
to: "0x8ba1f109551bD432803012645Ac136ddd64DBA72",
value: utils.parseEther("1.0")
}
// Signing a transaction
walletMnemonic.signTransaction(tx)
//!
// The connect method returns a new instance of the
// Wallet connected to a provider
wallet = walletMnemonic.connect(provider)
// Querying the network
wallet.getBalance();
//!
wallet.getTransactionCount();
//!
// Sending ether
wallet.sendTransaction(tx)
// <hide>
//! error
// </hide>
```
VoidSigner
----------
#### **new ***ethers* . **VoidSigner**( address [ , provider ] ) => *[VoidSigner](/v5/api/signer/#VoidSigner)*
Create a new instance of a **VoidSigner** for *address*.
#### *voidSigner* . **address** => *string< [Address](/v5/api/utils/address/#address) >*
The address of this **VoidSigner**.
```javascript
address = "0x8ba1f109551bD432803012645Ac136ddd64DBA72"
signer = new ethers.VoidSigner(address, provider)
// The DAI token contract
abi = [
"function balanceOf(address) view returns (uint)",
"function transfer(address, uint) returns (bool)"
]
contract = new ethers.Contract("dai.tokens.ethers.eth", abi, signer)
// <hide>
//!
// </hide>
// Get the number of tokens for this account
tokens = await contract.balanceOf(signer.getAddress())
//! async tokens
//
// Pre-flight (check for revert) on DAI from the signer
//
// Note: We do not have the private key at this point, this
// simply allows us to check what would happen if we
// did. This can be useful to check before prompting
// a request in the UI
//
// This will pass since the token balance is available
contract.callStatic.transfer("donations.ethers.eth", tokens)
//!
// This will fail since it is greater than the token balance
contract.callStatic.transfer("donations.ethers.eth", tokens.add(1))
//! error
```
ExternallyOwnedAccount
----------------------
#### *eoa* . **address** => *string< [Address](/v5/api/utils/address/#address) >*
The [Address](/v5/api/utils/address/#address) of this EOA.
#### *eoa* . **privateKey** => *string< [DataHexString](/v5/api/utils/bytes/#DataHexString)< 32 > >*
The privateKey of this EOA
#### *eoa* . **mnemonic** => *[Mnemonic](/v5/api/utils/hdnode/#Mnemonic)*
*Optional*. The account HD mnemonic, if it has one and can be determined. Some sources do not encode the mnemonic, such as an HD extended keys.
Reference in New Issue View Git Blame Copy Permalink