225 lines
9.5 KiB
Plaintext
225 lines
9.5 KiB
Plaintext
_section: Signers @<signers>
|
|
|
|
A Signer represents...
|
|
|
|
_subsection: Signer @<Signer> @SRC<abstract-signer:class.Signer>
|
|
|
|
The **Signer** class is abstract and cannot be directly instaniated. Instead
|
|
use one of the concreate sub-classes, such as the [[Wallet]], [[VoidSigner]]
|
|
or [[JsonRpcSigner]].
|
|
|
|
_property: signer.connect(provider) => [[Signer]] @<Signer-connect>
|
|
|
|
Sub-classes **must** implement this, however they may simply throw an error
|
|
if changing providers is not supported.
|
|
|
|
_property: signer.getAddress() => Promise<string<[Address](address)>> @<Signer-getaddress> @SRC<abstract-signer:Signer.connect>
|
|
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.
|
|
|
|
_property: Signer.isSigner(object) => boolean @<Signer-isSigner> @SRC<abstract-signer>
|
|
Returns true if an only if //object// is a **Signer**.
|
|
|
|
_heading: Blockchain Methods @<Signer--blockchain-methods>
|
|
|
|
_property: signer.getBalance([ blockTag = "latest" ]) => Promise<[[BigNumber]]> @<Signer-getBalance> @SRC<abstract-signer>
|
|
Returns the balance of this wallet at //blockTag//.
|
|
|
|
_property: signer.getChainId() => Promise<number> @<Signer-getChainId> @SRC<abstract-signer>
|
|
Returns ths chain ID this wallet is connected to.
|
|
|
|
_property: signer.getGasPrice() => Promise<[[BigNumber]]> @<Signer-getGasPrice> @SRC<abstract-signer>
|
|
Returns the current gas price.
|
|
|
|
_property: signer.getTransactionCount([ blockTag = "latest" ]) => Promise<number> @<Signer-getTransactionCount> @SRC<abstract-signer>
|
|
Returns the number of transactions this account has ever sent. This
|
|
is the value required to be included in transactions as the ``nonce``.
|
|
|
|
_property: signer.call(transactionRequest) => Promise<string<[[DataHexString]]>> @<Signer-call> @SRC<abstract-signer>
|
|
Returns the result of calling using the //transactionRequest//, with this
|
|
account address being used as the ``from`` field.
|
|
|
|
_property: signer.estimateGas(transactionRequest) => Promise<[[BigNumber]]> @<Signer-estimateGas> @SRC<abstract-signer>
|
|
Returns the result of estimating the cost to send the //transactionRequest//,
|
|
with this account address being used as the ``from`` field.
|
|
|
|
_property: signer.resolveName(ensName) => Promise<string<[Address](address)>> @<Signer-resolveName> @SRC<abstract-signer>
|
|
Returns the address associated with the //ensName//.
|
|
|
|
|
|
_heading: Signing
|
|
|
|
_property: signer.signMessage(message) => Promise<string<[RawSignature](signature-raw)>> @<Signer-signMessage>
|
|
This returns a Promise which resolves to the [[signature-raw]]
|
|
of //message//.
|
|
|
|
Sub-classes **must** implement this, however they may throw if signing a
|
|
message is not supported.
|
|
|
|
_note: 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]] 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](utils-arrayify) utility function.
|
|
|
|
_null:
|
|
|
|
_property: signer.signTransaction(transactionRequest) => Promise<string<[[DataHexString]]>> @<Signer-signTransaction>
|
|
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.
|
|
|
|
_property: signer.sendTransaction(transactionRequest) => Promise<[[providers-TransactionResponse]]> @<Signer-sendTransaction>
|
|
This method populates the transactionRequest with missing fields, using
|
|
[populateTransaction](Signer-populateTransaction) and returns a Promise which resolves to the transaction.
|
|
|
|
Sub-classes **must** implement this, however they may throw if signing a
|
|
transaction is not supported.
|
|
|
|
_heading: Sub-Classes @<Signer--subclassing>
|
|
|
|
It is very important that all important properties of a **Signer** are
|
|
**immutable**. Since Ethereum is very asynchronous and deals with critical
|
|
data (such as ether and other potentially valuable crypto assets), keeping
|
|
properties such as the //provider// and //address// static helps prevent
|
|
serious issues.
|
|
|
|
A sub-class **must** call ``super()``.
|
|
|
|
_property: signer.checkTransaction(transactionRequest) => [[providers-TransactionRequest]] @<Signer-checkTransaction> @SRC<abstract-signer>
|
|
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 [[providers-TransactionRequest]] properties
|
|
exist and adds ``from`` to the transaction if it does not exist, or verifies it is equal
|
|
to the Signer's address if it does exist.
|
|
|
|
_property: signer.populateTransaction(transactionRequest) => Promise<[[providers-TransactionRequest]]> @<Signer-populateTransaction> @SRC<abstract-signer>
|
|
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](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.
|
|
|
|
_subsection: Wallet @<Wallet> @INHERIT<[[ExternallyOwnedAccount]] and [[Signer]]> @SRC<wallet:class.Wallet>
|
|
|
|
The Wallet class inherits [[Signer]] and can sign transactions and messages
|
|
using a private key as a standard Externally Owned Account (EOA).
|
|
|
|
_property: new ethers.Wallet(privateKey [ , provider ]) @<Wallet-constructor> @SRC<wallet:constructor.Wallet>
|
|
Create a new Wallet instance for //privateKey// and optionally
|
|
connected to the //provider//.
|
|
|
|
_property: ethers.Wallet.createRandom( [ options = { } ]) => [[Wallet]] @<Wallet-createRandom> @SRC<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.
|
|
|
|
_property: ethers.Wallet.fromEncryptedJson(json, password [ , progress ]) => Promise<[[Wallet]]> @<Wallet-fromEncryptedJson> @SRC<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.
|
|
|
|
_property: ethers.Wallet.fromEncryptedJsonSync(json, password) => [[Wallet]] @<Wallet-fromEncryptedJsonSync> @SRC<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.
|
|
|
|
_property: ethers.Wallet.fromMnemonic(mnemonic [ , path, [ wordlist ] ]) => [[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.
|
|
|
|
_heading: Properties
|
|
|
|
_property: wallet.address => string<[Address](address)>
|
|
The address for the account this Wallet represents.
|
|
|
|
_property: wallet.provider => [[Provider]]
|
|
The provider this wallet is connected to, which will ge used for any [[Signer--blockchain-methods]]
|
|
methods. This can be null.
|
|
|
|
_note: Note
|
|
A **Wallet** instance is immuatable, so if you wish to change the Provider, you
|
|
may use the [connect](Signer-connect) method to create a new instance connected
|
|
to the desired provider.
|
|
|
|
_property: wallet.publicKey => string<[[DataHexString]]<65>>
|
|
The uncompressed public key for this Wallet represents.
|
|
|
|
_heading: Methods
|
|
|
|
_property: wallet.encrypt(password, [ options = { }, [ progress ] ]) => Promise<string>
|
|
|
|
Encrypt the wallet using //password// returning a Promise which resolves
|
|
to a JSON wallet.
|
|
|
|
|
|
_subsection: VoidSigner @<VoidSigner> @INHERIT<[[Signer]]> @SRC<abstract-signer:class.VoidSigner>
|
|
|
|
A **VoidSigner** is a simple Signer which cannot sign.
|
|
|
|
It is useful as a read-only signer, when an API requires a
|
|
Signer as a parameter, but it is known only read-only operations
|
|
will be carried.
|
|
|
|
For example, the ``call`` operation will automatically have the
|
|
provided address passed along during the execution.
|
|
|
|
_property: new ethers.VoidSigner(address) => [[VoidSigner]]
|
|
Create a new instance of a **VoidSigner** for //address//.
|
|
|
|
_property: voidSigner.address => string<[Address](address)>
|
|
The address of this **VoidSigner**.
|
|
|
|
|
|
_subsection: ExternallyOwnedAccount @<ExternallyOwnedAccount>
|
|
|
|
This is an interface which contains a minimal set of properties
|
|
required for Externally Owned Accounts which can have certain
|
|
operations performed, such as encoding as a JSON wallet.
|
|
|
|
_property: eoa.address => string<[Address](address)>
|
|
|
|
The [[address]] of this EOA.
|
|
|
|
_property: eoa.privateKey => string<[[DataHexString]]<32>>
|
|
|
|
The privateKey of this EOA
|
|
|
|
_property: eoa.mnemonic => [[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.
|