diff --git a/docs.wrm/.gitignore b/docs.wrm/.gitignore new file mode 100644 index 000000000..8bb0324ba --- /dev/null +++ b/docs.wrm/.gitignore @@ -0,0 +1 @@ +**.bak diff --git a/docs.wrm/api/contract/contract-factory.wrm b/docs.wrm/api/contract/contract-factory.wrm new file mode 100644 index 000000000..14d3814db --- /dev/null +++ b/docs.wrm/api/contract/contract-factory.wrm @@ -0,0 +1,77 @@ +_section: ContractFactory @ @SRC + + +_subsection: Creating Instances @ + +_property: new ethers.ContractFactory(interface, bydecode [ , signer ]) @SRC + +_property: ContractFactory.fromSolidity(compilerOutput [ , signer ]) => [[ContractFactory]] + +_property: contractFactory.connect(signer) => [[Contract]] + + +_subsection: Properties @ + +_property: contractFactory.interface => [[Interface]] + +_property: contractFactory.bytecode => string<[[DataHexString]]> + +_property: contractFactory.signer => [[Signer]] + + +_subsection: Methods @ + +_property: contractFactory.attach(address) => [[Contract]] + +Return an instance of a [[Contract]] attched to //address//. This is the +same as using the [Contract constructor](contract--creating) with +//address// and this the the //interface// and //signerOrProvider// passed +in when creating the ContractFactory. + +_property: contractFactory.getDeployTransaction(...args) => [[UnsignedTransaction]] + +Returns the unsigned transaction which would deploy this Contract with //args// passed +to the Contract's constructor. + +_property: contractFactory.deploy(...args) => Promise<[[Contract]]> + +Uses the signer to deploy the Contract with //args// passed into tgee constructor and +retruns a Contract which is attached to the address where this contract **will** be +deployed once the transction is mined. + +The transction can be found at ``contract.deployTransaction``, and no interactions +should be made until the transaction is mined. + +_code: Deploying a Contract + +// +const signer = ethers.LocalSigner(); +const ContractFactory = ethers.ContractFactory; +// + +// If your contract constructor requires parameters, the ABI +// must include the constructor +const abi = [ + "constructor(address owner, uint256 initialValue)" +]; + +const factory = new ContractFactory(abi, bytecode, signer) + +const contract = await factory.deploy("ricmoo.eth", 42); + +// The address is available immediately, but the contract +// is NOT deployed yet +contract.address +//! + +// The transaction that the signer sent to deploy +contract.deployTransaction +//! + +// Wait until the transaction is mined +contract.deployTransaction.wait() +//! + +// Now the contract is safe to ineract with +contract.value() +//! diff --git a/docs.wrm/api/contract/contract.wrm b/docs.wrm/api/contract/contract.wrm index 02aeccd2c..6605d968a 100644 --- a/docs.wrm/api/contract/contract.wrm +++ b/docs.wrm/api/contract/contract.wrm @@ -1,57 +1,64 @@ -_section: Contract @ @SRC +_section: Contract @ @SRC -_subsection: Properties +Explain contract here... -_property: contract.address => string<[[address]]> -This is the address (or ENS name) the contract was constructed with. +_subsection: Creating Instances @ -_property: contract.addressPromise => string<[[address]]> -This is a promise that will resolve to the address the **Contract** -object is attached to. If an [[address]] was provided to the constructor, -it will be equal to this; if an ENS name was provided, this will be the -resolved address. +_property: new ethers.Contract(address, abi, signerOrProvider) @src -_property: contract.deployTransaction => [[provider-transactionresponse]] -If the **Contract** object is the result of a ContractFactory deployment, -this is the transaction which was used to deploy the contract. - -_property: contract.interface => [[abi-interface]] -This is the ABI as an [[abi-interface]]. - -_property: contract.provider => [[provider]] -If a provider was provided to the constructor, this is that provider. If -a signer was provided that had a [[provider]], this is that provider. - -_property: contract.signer => [[signer]] -If a signer was provided to the constructor, this is that signer. - - -_subsection: Methods - -_property: contract.attach(addressOrName) => [[contract]] @ @SRC +_property: contract.attach(addressOrName) => [[Contract]] @ @SRC Returns a new instance of the **Contract** attached to a new address. This is useful if there are multiple similar or identical copies of a Contract on the network and you wish to interact with each of them. -_property: contract.connect(providerOrSigner) => [[contract]] @ @SRC +_property: contract.connect(providerOrSigner) => [[Contract]] @ @SRC Returns a new instance of the Contract, but connected to //providerOrSigner//. -By passing in a [[provider]], this will return a downgraded +By passing in a [[Provider]], this will return a downgraded **Contract** which only has read-only access (i.e. constant calls). -By passing in a [[signer]]. the will return a **Contract** which +By passing in a [[Signer]]. the will return a **Contract** which will act on behalf of that signer. -_property: contract.deployed() => Promise<[[contract]]> @ @SRC + +_subsection: Properties @ + +_property: contract.address => string<[[address]]> +This is the address (or ENS name) the contract was constructed with. + +_property: contract.resolvedAddress => string<[[address]]> +This is a promise that will resolve to the address the **Contract** +object is attached to. If an [[address]] was provided to the constructor, +it will be equal to this; if an ENS name was provided, this will be the +resolved address. + +_property: contract.deployTransaction => [[providers-TransactionResponse]] +If the **Contract** object is the result of a ContractFactory deployment, +this is the transaction which was used to deploy the contract. + +_property: contract.interface => [[Interface]] +This is the ABI as an [[Interface]]. + +_property: contract.provider => [[Provider]] +If a provider was provided to the constructor, this is that provider. If +a signer was provided that had a [[Provider]], this is that provider. + +_property: contract.signer => [[Signer]] +If a signer was provided to the constructor, this is that signer. + + +_subsection: Methods + +_property: contract.deployed() => Promise<[[Contract]]> @ @SRC _property: Contract.isIndexed(value) => boolean @ @SRC _subsection: Events -_property: contract.queryFilter(event [ , fromBlockOrBlockHash [ , toBlock ]) => Promise> @ @SRC +_property: contract.queryFilter(event [ , fromBlockOrBlockHash [ , toBlock ]) => Promise> @ @SRC Return Events that match the //event//. _property: contract.listenerCount([ event ]) => number @ @SRC @@ -76,7 +83,7 @@ Unsubscribe all listeners for //event//. If no event is provided, all events are unsubscribed. -_subsection: Meta-Class @ +_subsection: Meta-Class @ A Meta-Class is a Class which has any of its properties determined at run-time. The **Contract** object uses a Contract's ABI to @@ -85,7 +92,7 @@ describe the generic ways to interact with the properties added at run-time during the **Contract** constructor. -_heading: Read-Only Methods (constant) @ +_heading: Read-Only Methods (constant) @ A constant method is read-only and evaluates a small amount of EVM code against the current blockchain state and can be computed by @@ -93,7 +100,7 @@ asking a single node, which can return a result. It is therefore free and does not require any ether, but **cannot make changes** to the blockchain state.. -_property: contract.METHOD_NAME(...args [ overrides ]) => Promise @ +_property: contract.METHOD_NAME(...args [ overrides ]) => Promise @ The type of the result depends on the ABI. For values that have a simple meaning in JavaScript, the types are fairly @@ -102,12 +109,12 @@ and booleans. For numbers, if the **type** is in the JavaSsript safe range (i.e. less than 53 bits, such as an ``int24`` or ``uint48``) a normal JavaScript -number is used. Otherwise a [[bignumber]] is returned. +number is used. Otherwise a [[BigNumber]] is returned. -For bytes (both fixed length and dynamic), a [[datahexstring]] is returned. +For bytes (both fixed length and dynamic), a [[DataHexString]] is returned. -_heading: Write Methods (non-constant) @ +_heading: Write Methods (non-constant) @ A non-constant method requires a transaction to be signed and requires payment in the form of a fee to be paid to a miner. This transaction @@ -119,23 +126,23 @@ It cannot return a result. If a result is required, it should be logged using a Solidity event (or EVM log), which can then be queried from the transaction receipt. -_property: contract.METHOD_NAME(...args [ , overrides ]) => Promise<[[provider-transactionresponse]]> @ -Returns a [[provider-transactionresponse]] for the transaction after +_property: contract.METHOD_NAME(...args [ , overrides ]) => Promise<[[providers-TransactionResponse]]> @ +Returns a [[providers-TransactionResponse]] for the transaction after it is sent to the network. This requires the **Contract** has a signer. -_heading: Write Methods Analysis @ +_heading: Write Methods Analysis @ There are secveral options to analyze properties and results of a write method without actually executing it. -_property: contract.estimateGas.METHOD_NAME(...args [ , overrides ]) => Promise<[[bignumber]]> @ +_property: contract.estimateGas.METHOD_NAME(...args [ , overrides ]) => Promise<[[BigNumber]]> @ Returns the estimate units of gas that would be required to execute the //METHOD_NAME// with //args// and //overrides//. -_property: contract.populateTransaction.METHOD_NAME(...args [ , overrides ]) => Promise<[UnsignedTx](types-unsignedtransaction)> @ -Returns an [[types-unsignedtransaction]] which represents the transaction +_property: contract.populateTransaction.METHOD_NAME(...args [ , overrides ]) => Promise<[UnsignedTx](UnsignedTransaction)> @ +Returns an [[UnsignedTransaction]] which represents the transaction that would need to be signed and submitted to the network to execute //METHOD_NAME// with //args// and //overrides//. @@ -147,9 +154,9 @@ return the result. This does not actually chagne any state, but is free. This in some cases can be used to determine if a transaction will fail or succeed. -This otherwise functions the same as a [Read-Only Method](contract-readonly). +This otherwise functions the same as a [Read-Only Method](contract--readonly). -_heading: Event Filters @ +_heading: Event Filters @ An event filter is made up of topics, which are values logged in a [[link-wiki-bloomfilter]], allowing efficient searching for entries which match a filter. diff --git a/docs.wrm/api/contract/example.wrm b/docs.wrm/api/contract/example.wrm index 32cf2c4ca..065ee4994 100644 --- a/docs.wrm/api/contract/example.wrm +++ b/docs.wrm/api/contract/example.wrm @@ -41,7 +41,7 @@ const erc20 = new ethers.Contract(address, abi, provider); const erc20_rw = new ethers.Contract(address, abi, signer) -_heading: ERC20Contract @INHERIT<[[contract]]> +_heading: ERC20Contract @INHERIT<[[Contract]]> _property: new ethers.Contract(address, abi, providerOrSigner) See the above code example for creating an Instance which will @@ -50,48 +50,48 @@ add the additional properties defined in //abi// to a **Contract** connected to //address// using the //providerOrSigner//. -_subsection: Properties @NOTE<(inheritted from [[contract]])> +_subsection: Properties @NOTE<(inheritted from [[Contract]])> _property: erc20.address => string<[[address]]> This is the address (or ENS name) the contract was constructed with. -_property: erc20.addressPromise => string<[[address]]> +_property: erc20.resolvedAddress => string<[[address]]> This is a promise that will resolve to the address the **Contract** object is attached to. If an [[address]] was provided to the constructor, it will be equal to this; if an ENS name was provided, this will be the resolved address. -_property: erc20.deployTransaction => [[provider-transactionresponse]] +_property: erc20.deployTransaction => [[providers-TransactionResponse]] If the **Contract** object is the result of a ContractFactory deployment, this is the transaction which was used to deploy the contract. -_property: erc20.interface => [[abi-interface]] -This is the ABI as an [[abi-interface]]. +_property: erc20.interface => [[Interface]] +This is the ABI as an [[Interface]]. -_property: erc20.provider => [[provider]] +_property: erc20.provider => [[Provider]] If a provider was provided to the constructor, this is that provider. If -a signer was provided that had a [[provider]], this is that provider. +a signer was provided that had a [[Provider]], this is that provider. -_property: erc20.signer => [[signer]] +_property: erc20.signer => [[Signer]] If a signer was provided to the constructor, this is that signer. -_subsection: Methods @NOTE<(inheritted from [[contract]])> +_subsection: Methods @NOTE<(inheritted from [[Contract]])> -_property: erc20.attach(addressOrName) => [[contract]] +_property: erc20.attach(addressOrName) => [[Contract]] Returns a new instance of the **Contract** attached to a new address. This is useful if there are multiple similar or identical copies of a Contract on the network and you wish to interact with each of them. -_property: erc20.connect(providerOrSigner) => [[contract]] +_property: erc20.connect(providerOrSigner) => [[Contract]] Returns a new instance of the Contract, but connected to //providerOrSigner//. -By passing in a [[provider]], this will return a downgraded +By passing in a [[Provider]], this will return a downgraded **Contract** which only has read-only access (i.e. constant calls). -By passing in a [[signer]]. the will return a **Contract** which +By passing in a [[Signer]]. the will return a **Contract** which will act on behalf of that signer. _property: erc20.deployed() => Promise @@ -99,7 +99,7 @@ _property: erc20.deployed() => Promise _property: Contract.isIndexed(value) => boolean -_subsection: Events @NOTE<(inheritted from [[contract]])> @ +_subsection: Events @NOTE<(inheritted from [[Contract]])> @ _property: erc20.queryFilter(event [ , fromBlockOrBlockHash [ , toBlock ]) => Promise> @ Return Events that match the //event//. @@ -133,16 +133,16 @@ on the ABI which was passed into the **Contract**. _property: erc20.decimals([ overrides ]) => Promise Returns the number of decimal places used by this ERC-20 token. This can be -used with [parseUnits](utils-parseunits) when taking input from the user or +used with [parseUnits](utils-parseUnits) when taking input from the user or [formatUnits](utils-formatunits] when displaying the token amounts in the UI. -_property: erc20.getBalance(owner [, overrides ]) => Promise<[[bignumber]]> +_property: erc20.getBalance(owner [, overrides ]) => Promise<[[BigNumber]]> Returns the balance of //owner// for this ERC-20 token. _property: erc20.symbol([ overrides ]) => Promise Returns the symbol of the token. -_property: erc20_rw.transfer(target, amount [, overrides ]) => Promise<[[provider-transactionresponse]]> +_property: erc20_rw.transfer(target, amount [, overrides ]) => Promise<[[providers-TransactionResponse]]> Transfers //amount// tokens to //target// from the current signer. The return value (a boolean) is inaccessible during a write operation using a transaction. Other techniques (such as events) are required @@ -155,12 +155,12 @@ the current signer, without actually signing or sending a transaction. This can be used to preflight check that a transaction will be successful. -_property: erc20.estimate.transfer(target, amount [, overrides ]) => Promise<[[bignumber]]> +_property: erc20.estimateGas.transfer(target, amount [, overrides ]) => Promise<[[BigNumber]]> Returns an estimate for how many units of gas would be required to transfer //amount// tokens to //target//. -_property: erc20.populateTransaction.transfer(target, amount [, overrides ]) => Promise<[UnsignedTx](types-unsignedtransaction)> -Returns an [[types-unsignedtransaction]] which could be signed and submitted +_property: erc20.populateTransaction.transfer(target, amount [, overrides ]) => Promise<[UnsignedTx](UnsignedTransaction)> +Returns an [[UnsignedTransaction]] which could be signed and submitted to the network to transaction //amount// tokens to //target//. diff --git a/docs.wrm/api/contract/index.wrm b/docs.wrm/api/contract/index.wrm index 8dd31ca8c..d9420c5ef 100644 --- a/docs.wrm/api/contract/index.wrm +++ b/docs.wrm/api/contract/index.wrm @@ -1,8 +1,14 @@ _section: Contract Interaction @ -Explain what contracts are... +A **Contract** object is an abstraction of a contract (EVM bytecode) +deployed on the Ethereum network. It allows for a simple way to +serialize calls and transaxtions to an on-chain contract and +deserialize their results and emitted logs. +A **ContractFactory** is an abstraction a contract's //bytecode// +and facilitates deploying a contract. _toc: contract + contract-factory example diff --git a/docs.wrm/api/experimental.wrm b/docs.wrm/api/experimental.wrm index 42f81964b..08c5d0062 100644 --- a/docs.wrm/api/experimental.wrm +++ b/docs.wrm/api/experimental.wrm @@ -5,7 +5,7 @@ to be included in the base library. The API should not be considered stable and does not follow [[link-semver]] versioning, so applications requiring it should specify the //exact version// needed. -_subsection: BrainWallet @ @INHERIT<[[wallet]]> +_subsection: BrainWallet @ @INHERIT<[[Wallet]]> Ethers removed support for BrainWallets in v4, since they are unsafe and many can be easily guessed, allowing attackers to steal the funds. This @@ -22,12 +22,12 @@ Generate a brain wallet which is compatibile with the ethers v3 and earlier. _subsection: EIP1193Bridge @ @INHERIT<[[link-npm-events]]> -The **EIP1193Bridge** allows a normal Ethers [[signer]] and [[provider]] to be +The **EIP1193Bridge** allows a normal Ethers [[Signer]] and [[Provider]] to be exposed in as a standard [EIP-1193 Provider](link-eip-1193), which may be useful when interacting with other libraries. -_subsection: NonceManager @ @INHERIT<[[signer]]> +_subsection: NonceManager @ @INHERIT<[[Signer]]> The **NonceManager** is designed to manage the nonce for a Signer, automatically increasing it as it sends transactions. @@ -46,10 +46,10 @@ a transaction is dependent on another transaction being mined first. _property: new NonceManager(signer) Create a new NonceManager. -_property: nonceManager.signer => [[signer]] +_property: nonceManager.signer => [[Signer]] The signer whose nonce is being managed. -_property: nonceManager.provider => [[provider]] +_property: nonceManager.provider => [[Provider]] The provider associated with the signer. _property: nonceManager.setTransactionCount(count) => void diff --git a/docs.wrm/api/other/assembly/api.wrm b/docs.wrm/api/other/assembly/api.wrm index 84674c375..4b37e7ade 100644 --- a/docs.wrm/api/other/assembly/api.wrm +++ b/docs.wrm/api/other/assembly/api.wrm @@ -8,7 +8,7 @@ The assembler utilities allow parsing and assembling an _property: asm.parse(code) => [[asm-node]] @ @SRC Parse an ethers-format assembly file and return the [[asm-ast]]. -_property: asm.assemble(node) => string<[[datahexstring]]> @SRC +_property: asm.assemble(node) => string<[[DataHexString]]> @SRC Performs assembly of the [[asm-ast]] //node// and return the resulting bytecode representation. @@ -45,7 +45,7 @@ The opcode for this Operation. _property: operation.offset => number The offset into the bytecode for this Operation. -_property: operation.pushValue => string<[[datahexstring]]> +_property: operation.pushValue => string<[[DataHexString]]> If the opcode is a ``PUSH``, this is the value of that push diff --git a/docs.wrm/api/other/assembly/ast.wrm b/docs.wrm/api/other/assembly/ast.wrm index 978ff5349..57ce3530b 100644 --- a/docs.wrm/api/other/assembly/ast.wrm +++ b/docs.wrm/api/other/assembly/ast.wrm @@ -44,7 +44,7 @@ A **ValueNode** is a node which may manipulate the stack. _heading: LiteralNode @ @INHERIT<[[asm-valuenode]]> @SRC _property: literalNode.value => string -The literal value of this node, which may be a [[datahexstring]] or +The literal value of this node, which may be a [[DataHexString]] or string of a decimal number. _property: literalNode.verbatim => boolean diff --git a/docs.wrm/api/other/assembly/dialect.wrm b/docs.wrm/api/other/assembly/dialect.wrm index be2b85fb0..ab8d6a934 100644 --- a/docs.wrm/api/other/assembly/dialect.wrm +++ b/docs.wrm/api/other/assembly/dialect.wrm @@ -42,7 +42,7 @@ _subsection: Literals @ A **Literal** puts data on the stack when executed using a ``PUSH`` operation. -A **Literal** can be provided using a [[datahexstring]] or a decimal +A **Literal** can be provided using a [[DataHexString]] or a decimal byte value. @TODO: exmples diff --git a/docs.wrm/api/other/hardware/index.wrm b/docs.wrm/api/other/hardware/index.wrm index 7f1dd1577..de1beed75 100644 --- a/docs.wrm/api/other/hardware/index.wrm +++ b/docs.wrm/api/other/hardware/index.wrm @@ -1,11 +1,16 @@ _section: Hardware Wallets -_subsection: LedgerSigner @ @INHERIT<[[signer]]> @SRC + +_subsection: LedgerSigner @ @INHERIT<[[Signer]]> @SRC The [Ledger Hardware Wallets](link-ledger) are a fairly popular brand. -TODO: importing + +_code: Importing in ES6 or TypeScript @lang + + +_code: ES3 (UMD) in the Browser @lang + + diff --git a/docs.wrm/migration/ethers-v4.wrm b/docs.wrm/migration/ethers-v4.wrm index faaa84dd6..85bafe483 100644 --- a/docs.wrm/migration/ethers-v4.wrm +++ b/docs.wrm/migration/ethers-v4.wrm @@ -3,7 +3,7 @@ _section: Migration: From Ethers v4 @ _subsection: BigNumber _heading: Namespace -Since [[bignumber]] is used quite frequently, it has been moved to +Since [[BigNumber]] is used quite frequently, it has been moved to the top level of the umbrella package. _code: @lang