From 8efbfc6afaf447659424960a2971388eeaeea142 Mon Sep 17 00:00:00 2001
From: Richard Moore <github@ricmoo.com>
Date: Tue, 8 Dec 2020 18:29:56 -0500
Subject: [PATCH] docs: Filled in ContractFactory and examples.

---
 docs.wrm/api/contract/contract-factory.wrm | 63 ++++++++++++++++++----
 1 file changed, 53 insertions(+), 10 deletions(-)

diff --git a/docs.wrm/api/contract/contract-factory.wrm b/docs.wrm/api/contract/contract-factory.wrm
index af7ae895b..595e273ed 100644
--- a/docs.wrm/api/contract/contract-factory.wrm
+++ b/docs.wrm/api/contract/contract-factory.wrm
@@ -1,24 +1,49 @@
 _section: ContractFactory @<ContractFactory> @SRC<contracts:class.ContractFactory>
 
-@TODO: Fill this in, including @SRC links
+To deploy a [[Contract]], additional information is needed
+that is not available on a Contract object itself.
+
+Mainly, the bytecode (more specifically the initcode) of a contract is required.
+
+The **Contract Factory** sends a special type of transaction, an initcode
+transaction (i.e. the ``to`` field is null, and the ``data`` field is the
+initcode) where the initcode will be evaluated and the result becomes the
+new code to be deployed as a new contract.
 
 _subsection: Creating Instances  @<ContractFactory--creating>
 
 _property: new ethers.ContractFactory(interface, bytecode [ , signer ]) @SRC<contracts:constructor.ContractFactory>
 
+Creates a new instance of a **ContractFactory** for the contract described
+by the //interface// and //bytecode// initcode.
+
 _property: ContractFactory.fromSolidity(compilerOutput [ , signer ]) => [[ContractFactory]]
 
+Consumes the output of the Solidity compiler, extracting the ABI
+and bytecode from it, allowing for the various formats the solc
+compiler has emitted over its life.
+
 _property: contractFactory.connect(signer) => [[Contract]] @<ContractFactory-connect>
 
+Returns a **new instance** of the ContractFactory with the same //interface//
+and //bytecode//, but with a different //signer//.
 
 _subsection: Properties  @<ContractFactory--properties>
 
 _property: contractFactory.interface => [[Interface]]
 
+The [[Contract]] interface.
+
 _property: contractFactory.bytecode => string<[[DataHexString]]>
 
+The bytecode (i.e. initcode) that this **ContractFactory** will
+use to deploy the Contract.
+
 _property: contractFactory.signer => [[Signer]]
 
+The [[Signer]] (if any) this ContractFactory will use to deploy instances
+of the Contract to the Blockchain.
+
 
 _subsection: Methods  @<ContractFactory--methods>
 
@@ -29,36 +54,52 @@ same as using the [Contract constructor](Contract--creating) with
 //address// and this the //interface// and //signerOrProvider// passed
 in when creating the ContractFactory.
 
-_property: contractFactory.getDeployTransaction(...args) => [[UnsignedTransaction]]
+_property: contractFactory.getDeployTransaction(...args [ , overrides ]) => [[UnsignedTransaction]]
 
 Returns the unsigned transaction which would deploy this Contract with //args// passed
 to the Contract's constructor.
 
-_property: contractFactory.deploy(...args) => Promise<[[Contract]]> @<ContractFactory-deploy>
+If the optional //overrides// is specified, they can be used to
+override the endowment ``value``, transaction ``nonce``, ``gasLimit`` or
+``gasPrice``.
+
+_property: contractFactory.deploy(...args [ , overrides ]) => Promise<[[Contract]]> @<ContractFactory-deploy>
 
 Uses the signer to deploy the Contract with //args// passed into the constructor and
-returns a Contract which is attached to  the address where this contract **will** be
+returns a Contract which is attached to the address where this contract **will** be
 deployed once the transaction is mined.
 
 The transaction can be found at ``contract.deployTransaction``, and no interactions
 should be made until the transaction is mined.
 
-_code: Deploying a Contract
+If the optional //overrides// is specified, they can be used to
+override the endowment ``value``, transaction ``nonce``, ``gasLimit`` or
+``gasPrice``.
+
+_code: Deploying a Contract @lang<javascript>
 
 // <hide>
-const signer = ethers.LocalSigner();
+const signer = localSigner;
 const ContractFactory = ethers.ContractFactory;
+const bytecode = "608060405234801561001057600080fd5b5060405161012e38038061012e8339818101604052604081101561003357600080fd5b81019080805190602001909291908051906020019092919050505081600160006101000a81548173ffffffffffffffffffffffffffffffffffffffff021916908373ffffffffffffffffffffffffffffffffffffffff1602179055508060008190555050506088806100a66000396000f3fe6080604052348015600f57600080fd5b506004361060285760003560e01c80633fa4f24514602d575b600080fd5b60336049565b6040518082815260200191505060405180910390f35b6000805490509056fea2646970667358221220926465385af0e8706644e1ff3db7161af699dc063beaadd55405f2ccd6478d7564736f6c63430007040033";
 // </hide>
 
+
 // If your contract constructor requires parameters, the ABI
 // must include the constructor
 const abi = [
-  "constructor(address owner, uint256 initialValue)"
+  "constructor(address owner, uint256 initialValue)",
+  "function value() view returns (uint)"
 ];
 
-const factory = new ContractFactory(abi, bytecode, signer)
+// The factory we use for deploying contracts
+factory = new ContractFactory(abi, bytecode, signer)
 
-const contract = await factory.deploy("ricmoo.eth", 42);
+// Deploy an instance of the contract
+contract = await factory.deploy("ricmoo.eth", 42);
+//<hide>
+//! async contract
+//</hide>
 
 // The address is available immediately, but the contract
 // is NOT deployed yet
@@ -69,7 +110,9 @@ contract.address
 contract.deployTransaction
 //!
 
-// Wait until the transaction is mined
+// Wait until the transaction is mined (i.e. contract is deployed)
+//  - returns the receipt
+//  - throws on failure (the reciept is on the error)
 contract.deployTransaction.wait()
 //!