Checking in initial Eip1193Bridge (experimental).

Ethers v5 beta

.circleci/config.yml

@@ -35,51 +35,50 @@ commands:
                   google-chrome --version
 
       - run:
-          name: Update gcc version
+          name: Update C build environment
           command: |
             sudo add-apt-repository ppa:ubuntu-toolchain-r/test
             sudo apt update
-            sudo apt install gcc-6
-            sudo apt install g++-6
+            sudo apt install gcc-6 g++-6 libusb-1.0-0-dev libudev-dev
             sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-6 60 --slave /usr/bin/g++ g++ /usr/bin/g++-6
 
-      - run:
-          name: Prepare to run parity
-          command: |
-            mkdir -p /tmp/parity/keys
-            cp -r admin/test-parity/parity-keys /tmp/parity/keys/DevelopmentChain
-            cp admin/test-parity/parity-dev.* /tmp/parity
-            chmod -R 777 /tmp/parity
-            ls -la /tmp/parity
+#      - run:
+#          name: Prepare to run parity
+#          command: |
+#            mkdir -p /tmp/parity/keys
+#            cp -r admin/test-parity/parity-keys /tmp/parity/keys/DevelopmentChain
+#            cp admin/test-parity/parity-dev.* /tmp/parity
+#            chmod -R 777 /tmp/parity
+#            ls -la /tmp/parity
 
-      - run:
-          name: Starting Parity
-          command: |
-            docker run -d \
-            -p 8545:8545 \
-            -p 8546:8546 \
-            -p 30303:30303 \
-            -p 30303:30303/udp \
-            --name parity \
-            -v /tmp/parity:/home/parity/.local/share/io.parity.ethereum parity/parity:v2.4.8-stable \
-            --chain /home/parity/.local/share/io.parity.ethereum/parity-dev.json \
-            --unlock=0x7454a8F5a7c7555d79B172C89D20E1f4e4CC226C \
-            --password /home/parity/.local/share/io.parity.ethereum/parity-dev.pwds \
-            --min-gas-price 1000000000 \
-            --jsonrpc-interface all
+#      - run:
+#          name: Starting Parity
+#          command: |
+#           docker run -d \
+#            -p 8545:8545 \
+#            -p 8546:8546 \
+#            -p 30303:30303 \
+#            -p 30303:30303/udp \
+#            --name parity \
+#            -v /tmp/parity:/home/parity/.local/share/io.parity.ethereum parity/parity:v2.4.8-stable \
+#            --chain /home/parity/.local/share/io.parity.ethereum/parity-dev.json \
+#            --unlock=0x7454a8F5a7c7555d79B172C89D20E1f4e4CC226C \
+#            --password /home/parity/.local/share/io.parity.ethereum/parity-dev.pwds \
+#            --min-gas-price 1000000000 \
+#            --jsonrpc-interface all
 
-      - run:
-          name: Waiting for Parity to be ready
-          command: |
-            for i in `seq 1 20`;
-            do
-              nc -z localhost 8545 && echo Success && exit 0
-              echo -n .
-              sleep 2
-            done
-            docker ps -a
-            docker logs parity 
-            echo Failed waiting for Parity && exit 1
+#      - run:
+#          name: Waiting for Parity to be ready
+#          command: |
+#            for i in `seq 1 20`;
+#            do
+#              nc -z localhost 8545 && echo Success && exit 0
+#              echo -n .
+#              sleep 2
+#            done
+#            docker ps -a
+#            docker logs parity 
+#            echo Failed waiting for Parity && exit 1
 
       - run:
           name: Run << parameters.test-script >> with node version << parameters.node-version >>

CHANGELOG.md

@@ -3,6 +3,39 @@ Changelog
 
 This change log is managed by `scripts/cmds/update-versions` but may be manually updated.
 
+ethers/v5.0.0-beta.175 (2020-02-27 19:53)
+-----------------------------------------
+
+  - Fix address-less filter listening in Provider. ([#741](https://github.com/ethers-io/ethers.js/issues/741); [64dccb2](https://github.com/ethers-io/ethers.js/commit/64dccb275c68ebb40328350d4ab5be0f29b8a02e))
+  - Added sync version of wallet decryption. ([0ad94cd](https://github.com/ethers-io/ethers.js/commit/0ad94cdf8137259bedb38c0dc949b61570bcdac0), [6809c37](https://github.com/ethers-io/ethers.js/commit/6809c370c027aea148466c00d3ce09c6d0ee6ddc))
+
+ethers/v5.0.0-beta.175 (2020-02-27 19:38)
+-----------------------------------------
+
+  - Fix address-less filter listening in Provider. ([#741](https://github.com/ethers-io/ethers.js/issues/741); [64dccb2](https://github.com/ethers-io/ethers.js/commit/64dccb275c68ebb40328350d4ab5be0f29b8a02e))
+  - Added sync version of wallet decryption. ([0ad94cd](https://github.com/ethers-io/ethers.js/commit/0ad94cdf8137259bedb38c0dc949b61570bcdac0))
+
+ethers/v5.0.0-beta.174 (2020-02-25 14:57)
+-----------------------------------------
+
+  - Reduced default Provider quorum for testnets. ([1cfab31](https://github.com/ethers-io/ethers.js/commit/1cfab3173c3d0519beffc054efe73f70b7d28501))
+  - Added JSON-RPC debugging on error responses. ([ad27600](https://github.com/ethers-io/ethers.js/commit/ad27600c699827858e7343adff2d4fa622248e42))
+  - Fixed setLogLevel to affect global logging. ([ac51a88](https://github.com/ethers-io/ethers.js/commit/ac51a88c2913d7055e050c91d7d96bb42abf6656))
+  - Renamed interface getTopic to getEventTopic. ([f61f34b](https://github.com/ethers-io/ethers.js/commit/f61f34bfb295bafee3b7ee426efa696aaa9bbafe))
+  - Fix log parsing when no matching topic hash is found. ([#733](https://github.com/ethers-io/ethers.js/issues/733); [a5d2ec5](https://github.com/ethers-io/ethers.js/commit/a5d2ec534f75b21eebe69a789a3c43c33014a825), [4b8e198](https://github.com/ethers-io/ethers.js/commit/4b8e198bf209fcf0aea55018d8940355ea4345de), [89ac9f4](https://github.com/ethers-io/ethers.js/commit/89ac9f4f298ac340c4429e8ebdacd29962eba7f4))
+
+ethers/v5.0.0-beta.173 (2020-02-12 17:09)
+-----------------------------------------
+
+  - Added experimental EipWrappedProvider. ([944600d](https://github.com/ethers-io/ethers.js/commit/944600d779564c500ab98d3265286a0717642614))
+  - Updated signature for JsonRpcProvider.send to match EIP-1193. ([b962b59](https://github.com/ethers-io/ethers.js/commit/b962b59ab72e67bc4566a361964e42cf1b791025))
+  - Added binary literal support to ASM grammar. ([375bd15](https://github.com/ethers-io/ethers.js/commit/375bd15594a3179432e8452d819d91ea72b4bdd8))
+  - Added explicit pop placeholders to ASM dialect. ([a6b696d](https://github.com/ethers-io/ethers.js/commit/a6b696d8bd03c4027b52fe23745f066d158f1420))
+  - Added position independent code option for asm. ([89615c5](https://github.com/ethers-io/ethers.js/commit/89615c59d385a58fa79b6bbd8eae53c30e45fe96))
+  - Added ASM semantic checking and the Pop placeholder. ([a33bf0e](https://github.com/ethers-io/ethers.js/commit/a33bf0e37f4f969cc03b85ebf0dbadcf3e9b068a))
+  - Better type safety for defineReadOnly. ([e7adc84](https://github.com/ethers-io/ethers.js/commit/e7adc84a972968f39a983efb6f21b6ceaacd6cc5))
+  - Fixed CLI sandbox quiting after prompt entry. ([ff9bc2a](https://github.com/ethers-io/ethers.js/commit/ff9bc2a282e617125bbca76702dec85149661390))
+
 ethers/v5.0.0-beta.172 (2020-02-04 00:59)
 -----------------------------------------
 

admin/changelog.js

@@ -105,9 +105,41 @@ async function generate() {
     return formatted.join("\n") + "\n";
 }
 
+function getChanges() {
+    const changes = [ ];
+
+    let lastLine = null;
+    fs.readFileSync(ChangelogPath).toString().split("\n").forEach((line) => {
+        line = line.trim();
+        if (line === "") { return; }
+
+        if (line.substring(0, 5) === "-----") {
+            changes.push({ title: lastLine, lines: [ ] });
+        } else if (line.substring(0, 1) === "-" && changes.length) {
+            changes[changes.length - 1].lines.push(line);
+        }
+        lastLine = line;
+    });
+
+    return changes;
+}
+
+function latestChange() {
+    const recent = getChanges()[0];
+
+    const match = recent.title.match(/ethers\/([^\(]*)\(([^\)]*)\)/);
+
+    return {
+        title: recent.title,
+        version: match[1].trim(),
+        data: match[2].trim(),
+        content: recent.lines.join("\n")
+    };
+}
+
 module.exports = {
     generate: generate,
+    latestChange: latestChange,
     ChangelogPath: ChangelogPath,
 }
 
-

admin/cmds/publish.js

@@ -2,13 +2,16 @@
 
 const config = require("../config");
 
+const { latestChange } = require("../changelog");
 const { getOrdered, loadPackage } = require("../depgraph");
+const { createRelease } = require("../github");
 const { getPackageVersion, publish } = require("../npm");
 const { log } = require("../log");
 
 const USER_AGENT = "ethers-dist@0.0.0";
 const TAG = "next";
 
+
 let dirnames = getOrdered();
 
 // Only publish specific packages
@@ -32,6 +35,8 @@ if (process.argv.length > 2) {
 (async function() {
     let token = null;
 
+    let includeEthers = false;
+
     // @TODO: Fail if there are any untracked files or unchecked in files
 
     // Load the token from the encrypted store
@@ -68,6 +73,7 @@ if (process.argv.length > 2) {
 
         if (dirname === "ethers") {
             options.tag = "next";
+            includeEthers = true;
         } else {
             options.tag = "latest";
         }
@@ -89,4 +95,20 @@ if (process.argv.length > 2) {
         log("  <green:Done.>");
     }
 
+    // Publish the GitHub release (currently beta)
+    const beta = true;
+    if (includeEthers) {
+
+        // The password above already succeeded
+        const username = await config.get("github-user");
+        const password = await config.get("github-release");
+
+        // Get the latest change from the changelog
+        const change = latestChange();
+
+        // Publish the release
+        const link = await createRelease(username, password, change.version, change.title, change.content, beta);
+        log(`<bold:Published Release:> ${ link }...`);
+    }
+
 })();

admin/config.js

@@ -57,6 +57,11 @@ Config.prototype.load = async function() {
     }
 };
 
+Config.prototype.keys = async function() {
+    await this.load();
+    return Object.keys(this.values);
+}
+
 Config.prototype.save = function() {
     this.values._junk = Buffer.from(randomBytes(16 + parseInt(Math.random() * 48))).toString("base64")
 
@@ -102,6 +107,9 @@ module.exports = {
     set: function(key, value) {
         config.set(key, value);
     },
+    keys: function() {
+        return config.keys();
+    },
     lock: function() {
         config.lock();
     }

admin/github.js

@@ -128,7 +128,35 @@ function syncIssues(user, password) {
     return _getIssues(user, password);
 }
 
+async function createRelease(user, password, tagName, title, body, prerelease, commit) {
+    const payload = {
+        tag_name: tagName,
+        target_commitish: (commit || "master"),
+        name: title,
+        body: body,
+        //draft: true,
+        draft: false,
+        prerelease: !!prerelease
+    };
+
+    const headers = {
+        "User-Agent": "ethers-io",
+    };
+
+    const result = await fetchJson({
+        url: "https://api.github.com/repos/ethers-io/ethers.js/releases",
+        user: user,
+        password: password,
+        headers: headers
+    }, JSON.stringify(payload));
+
+
+    return result.html_url;
+}
+
 module.exports = {
     getIssues,
     syncIssues,
+    createRelease,
 }
+

docs.wrm/api/contract.wrm

@@ -1,8 +0,0 @@
-_title: Contracts
-
-_null: Contract @<contract>
-_section: Contracts
-
-Explain what contracts are...
-
-_subsection: Buckets

docs.wrm/api/contract/contract.wrm

@@ -0,0 +1,162 @@
+_section: Contract @<contract> @SRC<contracts:class.Contract>
+
+_subsection: Properties
+
+_property: contract.address => string<[[address]]>
+This is the address (or ENS name) the contract was constructed with.
+
+_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: 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]]  @<contract-attach> @SRC<contracts:Contract.attach>
+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]]  @<contract-connect> @SRC<contracts:Contract.connect>
+Returns a new instance of the Contract, but connected to
+//providerOrSigner//.
+
+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
+will act on behalf of that signer.
+
+_property: contract.deployed() => Promise<[[contract]]>  @<contract-deployed> @SRC<contracts>
+
+_property: Contract.isIndexed(value) => boolean  @<contract-isIndexed> @SRC<contracts>
+
+
+_subsection: Events
+
+_property: contract.queryFilter(event [ , fromBlockOrBlockHash [ , toBlock ]) => Promise<Array<Event>> @<contract-queryfilter> @SRC<contracts>
+Return Events that match the //event//.
+
+_property: contract.listenerCount([ event ]) => number  @<contract-listenerCount> @SRC<contracts:Contract.listenerCount>
+Return the number of listeners that are subscribed to //event//. If
+no event is provided, returns the total count of all events.
+
+_property: contract.listeners(event) => Array<Listener>  @<contract-listeners> @SRC<contracts:Contract.listeners>
+Return a list of listeners that are subscribed to //event//.
+
+_property: contract.off(event, listener) => this  @<contract-off> @SRC<contracts>
+Unsubscribe //listener// to //event//.
+
+_property: contract.on(event, listener) => this  @<contract-on> @SRC<contracts>
+Subscribe to //event// calling //listener// when the event occurs.
+
+_property: contract.once(event, listener) => this  @<contract-once> @SRC<contracts>
+Subscribe once to //event// calling //listener// when the event
+occurs.
+
+_property: contract.removeAllListeners([ event ]) => this  @<contract-removeAllListeners> @SRC<contracts:Contract.removeAllListeners>
+Unsubscribe all listeners for //event//. If no event is provided,
+all events are unsubscribed.
+
+
+_subsection: Meta-Class  @<contract-metaclass>
+
+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
+determine what methods are available, so the following sections
+describe the generic ways to interact with the properties added
+at run-time during the **Contract** constructor.
+
+
+_heading: Read-Only Methods (constant)  @<contract-readonly>
+
+A constant method is read-only and evaluates a small amount of EVM
+code against the current blockchain state and can be computed by
+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<any>  @<contract-call>
+The type of the result depends on the ABI.
+
+For values that have a simple meaning in JavaScript, the types are fairly
+straight forward; strings and booleans are returned as JavaScript strings
+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.
+
+For bytes (both fixed length and dynamic), a [[datahexstring]] is returned.
+
+
+_heading: Write Methods (non-constant) @<contract-write>
+
+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
+will be verified by every node on the entire network as well by the
+miner who will compute the new state of the blockchain after executing
+it against the current state.
+
+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]]>  @<contract-send>
+Returns a [[provider-transactionresponse]] for the transaction after
+it is sent to the network. This requires the **Contract** has a
+signer.
+
+
+_heading: Write Methods Analysis @<contract-write-check>
+
+There are secveral options to analyze properties and results of a
+write method without actually executing it.
+
+_property: contract.estimate.METHOD_NAME(...args [ , overrides ]) => Promise<[[bignumber]]>  @<contract-estimateGas>
+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)>  @<contract-populateTransaction>
+Returns an [[types-unsignedtransaction]] which represents the transaction
+that would need to be signed and submitted to the network to execute
+//METHOD_NAME// with //args/ and //overrides//.
+
+_property: contract.staticCall.METHOD_NAME(...args [ , overrides ]) => Promise<any>  @<contract-staticCall>
+Rather than executing the state-change of a transaction, it is possible
+to ask a node to //pretend// that a call is not state-changing and
+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).
+
+_heading: Event Filters @<contract-filter>
+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.
+
+_property: contract.filters.EVENT_NAME(...args) => Filter
+Return a filter for //EVENT_NAME//, optionally filtering by additional
+constraints.
+
+Only ``indexed`` event parameters may be filtered. If a parameter is
+null (or not provided) then any value in that field matches.

docs.wrm/api/contract/example.wrm

@@ -0,0 +1,150 @@
+_section: Example: ERC-20 Contract
+
+_subsection: Connecting to a Contract
+
+_code: token.txt
+
+
+_heading: ERC20Contract @INHERIT<[[contract]]>
+
+_property: new ethers.Contract(address, abi, providerOrSigner)
+See the above code example for creating an Instance which will
+(in addition to the Contact methods and properties) automatically
+add the additional properties defined in //abi// to a **Contract**
+connected to //address// using the //providerOrSigner//.
+
+
+_subsection: Properties ^^//(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]]>
+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]]
+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.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: erc20.signer => [[signer]]
+If a signer was provided to the constructor, this is that signer.
+
+
+_subsection: Methods ^^//(inheritted from [[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]]
+Returns a new instance of the Contract, but connected to
+//providerOrSigner//.
+
+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
+will act on behalf of that signer.
+
+_property: erc20.deployed() => Promise<Contract>
+
+_property: Contract.isIndexed(value) => boolean
+
+
+_subsection: Events ^^//(inheritted from Contract)//^^ @<erc20-events>
+
+_property: erc20.queryFilter(event [ , fromBlockOrBlockHash [ , toBlock ]) => Promise<Array<Event>> @<erc20-queryfilter>
+Return Events that match the //event//.
+
+_property: erc20.listenerCount([ event ]) => number
+Return the number of listeners that are subscribed to //event//. If
+no event is provided, returns the total count of all events.
+
+_property: erc20.listeners(event) => Array<Listener>
+Return a list of listeners that are subscribed to //event//.
+
+_property: erc20.off(event, listener) => this
+Unsubscribe //listener// to //event//.
+
+_property: erc20.on(event, listener) => this
+Subscribe to //event// calling //listener// when the event occurs.
+
+_property: erc20.once(event, listener) => this
+Subscribe once to //event// calling //listener// when the event
+occurs.
+
+_property: erc20.removeAllListeners([ event ]) => this
+Unsubscribe all listeners for //event//. If no event is provided,
+all events are unsubscribed.
+
+
+_subsection: Meta-Class Methods ^^//(added at Runtime)//^^
+
+Since the Contract is a Meta-Class, the methods available here depend
+on the ABI which was passed into the **Contract**.
+
+_property: erc20.decimals([ overrides ]) => Promise<number>
+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
+[formatUnits](utils-formatunits] when displaying the token amounts in the UI.
+
+_property: erc20.getBalance(owner [, overrides ]) => Promise<[[bignumber]]>
+Returns the balance of //owner// for this ERC-20 token.
+
+_property: erc20.symbol([ overrides ]) => Promise<string>
+Returns the symbol of the token.
+
+_property: erc20_rw.transfer(target, amount [, overrides ]) => Promise<[[provider-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
+if this value is required. On-chain contracts calling the ``transfer``
+function have access to this result, which is why it is possible.
+
+_property: erc20.callStatic.transfer(target, amount [, overrides ]) => Promise<boolean>
+Performs a dry-run of transferring //amount// tokens to //target// from
+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]]>
+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
+to the network to transaction //amount// tokens to //target//.
+
+
+_note: Note on Estimating and Static Calling
+
+When you perform a static call, the current state is taken into account as
+best as Ethereum can determine. There are many cases where this can provide
+false positives and false negatives. The eventually consistent model of the
+blockchain also means there are certain consistency modes that cannot be
+known until an actual transaction is attempted.
+
+
+_subsection: Meta-Class Filters ^^//(added at Runtime)//^^
+
+Since the Contract is a Meta-Class, the methods available here depend
+on the ABI which was passed into the **Contract**.
+
+_property: erc20.filters.Transafer([ fromAddress [ , toAddress ] ]) => Filter
+Returns a new Filter which can be used to [query](erc20-queryfilter) or
+to [subscribe/unsubscribe to events](erc20-events).
+
+If //fromAddress// is null or not provided, then any from address matches.
+If //toAddress// is null or not provided, then any to address matches.

docs.wrm/api/contract/index.wrm

@@ -0,0 +1,8 @@
+_section: Contract Interaction @<contracts>
+
+Explain what contracts are...
+
+
+_toc:
+    contract
+    example

docs.wrm/api/contract/token.txt

@@ -0,0 +1,35 @@
+// A Human-Readable ABI; any supported ABI format could be used
+const abi = [
+    // Read-Only Functions
+    "function balanceOf(address owner) view returns (uint256)",
+    "function decimals() view returns (uint8)",
+    "function symbol() view returns (string)",
+
+    // Authenticated Functions
+    "function transfer(address to, uint amount) returns (boolean)",
+
+    // Events
+    "event Transfer(address indexed from, address indexed to, uint amount)"
+];
+
+// This can be an address or an ENS name
+const address = "demotoken.ethers.eth";
+
+// An example Provider (connceted to testnet)
+const provider = ethers.getDefaultProvider("ropsten");
+
+// An example Signer
+const signer = ethers.Wallet.createRandom(provider);
+
+// Read-Only; By connecting to a Provider, allows:
+// - Any constant function
+// - Querying Filters
+// - Populating Unsigned Transactions for non-constant methods
+// - Estimating Gas for non-constant (as an anonymous sender)
+// - Static Calling non-constant methods (as anonymous sender)
+const erc20 = new ethers.Contract(address, abi, provider);
+
+// Read-Write; By connecting to a Signer, allows:
+// - Everything from Read-Only (except as Signer, not anonymous)
+// - Sending transactions for non-constant functions
+const erc20_rw = new ethers.Contract(address, abi, signer)

docs.wrm/api/index.wrm

@@ -1,6 +1,4 @@
-_title: Application Programming Interface
-
-_section: Application Programming Interface (API)
+_section: Application Programming Interface @NAV<API>
 
 Here...
 

docs.wrm/api/other/assembly/api.wrm

@@ -0,0 +1,86 @@
+_section: Utilities @<asm-utilities>
+
+_subsection: Assembler
+
+The assembler utilities allow parsing and assembling an
+[Ethers ASM Dialect](asm-dialect) source file.
+
+_property: asm.parse(code) => [[asm-node]] @<asm-parse> @SRC<asm/assembler>
+Parse an ethers-format assembly file and return the [[asm-ast]].
+
+_property: asm.assemble(node) => string<[[datahexstring]]> @SRC<asm/assembler:function.assemble>
+Performs assembly of the [[asm-ast]] //node// and return the
+resulting bytecode representation.
+
+
+_subsection: Disassembler
+
+The **Disassembler** utilities make it easy to convert bytecode
+into an object which can easily be examined for program structure.
+
+_property: asm.disassemble(bytecode) => [[asm-bytecode]] @SRC<asm/assembler>
+Returns an array of Operations given //bytecode//.
+
+_property: asm.formatBytecode(operations) => string @SRC<asm/assembler>
+Create a formatted output of an array of [[asm-operation]].
+
+_heading: Bytecode @<asm-bytecode> @INHERIT<Array\<[[asm-operation]]\>>
+
+Each arary index represents an operation, collapsing multi-byte operations
+(i.e. ``PUSH``) into a single operation.
+
+_property: bytecode.getOperation(offset) => [[asm-operation]]
+Get the operation at a given //offset// into the bytecode. This ensures that
+the byte at //offset// is an operation and not data contained within a ``PUSH``,
+in which case null it returned.
+
+_heading: Operation @<asm-operation>
+
+An **Operation** is a single command from a disassembled bytecode
+stream.
+
+_property: operation.opcode => [[asm-opcode]]
+The opcode for this Operation.
+
+_property: operation.offset => number
+The offset into the bytecode for this Operation.
+
+_property: operation.pushValue => string<[[datahexstring]]>
+If the opcode is a ``PUSH``, this is the value of that push
+
+
+_subsection: Opcode @<asm-opcode> @SRC<asm/opcodes:class.Opcode>
+
+_property: asm.Opcode.from(valueOrMnemonic) => [[asm-opcode]]
+Create a new instnace of an Opcode for a given numeric value
+(e.g. 0x60 is PUSH1) or mnemonic string (e.g. "PUSH1").
+
+_heading: Properties
+
+_property: opcode.value => number
+The value (bytecode as a number) of this opcode.
+
+_property: opcode.mnemonic => string
+The mnemonic string of this opcode.
+
+_property: opcode.delta => number
+The number of items this opcode will consume from the stack.
+
+_property: opcode.alpha => number
+The number of items this opcode will push onto the stack.
+
+_property: opcode.doc => string
+A short description of what this opcode does.
+
+_property: opcode.isMemory() => "read" | "write" | "full"
+Returns true if the opcode accesses memory.
+
+_property: opcode.isStatic() => boolean
+Returns true if the opcode cannot change state.
+
+_property: opcode.isJump() => boolean
+Returns true if the opcode is a jumper operation.
+
+_property: opcode.isPush() => number
+Returns 0 if the opcode is not a ``PUSH*``, or the number
+of bytes this opcode will push if it is.

docs.wrm/api/other/assembly/ast.wrm

@@ -1,78 +1,15 @@
-_title: Assembly
+_section: Abstract Syntax Tree @<asm-ast>
 
-_section: Assembly @<asm>
-
-_subsection: Opcode @<asm-opcode>
-
-_property: asm.Opcode.from(valueOrMnemonic) => [[asm-opcode]]
-Create a new instnace of an Opcode for a given numeric value
-(e.g. 0x60 is PUSH1) or mnemonic (e.g. "PUSH1").
-
-_property: opcode.value => number
-The value (bytecode as a number) of this opcode.
-
-_property: opcode.mnemonic => string
-The mnemonic string of this opcode.
-
-_property: opcode.delta => number
-The number of items this opcode will consume from the stack.
-
-_property: opcode.alpha => number
-The number of items this opcode will push onto the stack.
-
-_property: opcode.doc => string
-A short description of what this opcode does.
-
-_property: opcode.isMemory() => boolean
-Returns true if the opcode accesses memory.
-
-_property: opcode.isStatic() => boolean
-Returns true if the opcode cannot change state.
-
-_property: opcode.isJump() => boolean
-Returns true if the opcode is a jumper operation.
-
-_property: opcode.isPush() => number
-Returns 0 if the opcode is not a ``PUSH*``, or the number
-of bytes this opcode will push if it is.
-
-_subsection: Assembler
-
-_heading: Operation @<asm-operation>
-
-An **Operation** is a single command from a disassembled bytecode
-stream.
-
-_property: operation.opcode => [[asm-opcode]]
-_property: operation.offset => number
-_property: operation.pushValue => string
-
-_heading: Functions
-
-_property: asm.parse(code) => [[asm-node]] @SRC<asm/assembler>
-Parse an ethers-format assembly file and return the [[asm-ast]].
-
-_property: asm.assemble(node) => string<[[datahexstring]]> @SRC<asm/assembler:function.assemble>
-Performs assembly of the [[asm-ast]] //node// and return the
-resulting bytecode representation.
-
-_property: asm.disassemble(bytecode) => Array<[[asm-operation]]> @SRC<asm/assembler>
-Returns an array of Operations given //bytecode//.
-
-In addition to a standard array, the return also has a
-``getOperation(offset)`` method, which can be used to get
-the operation at a given byte offset, which prevents access
-to internal ``PUSH`` bytes (i.e. safe JUMPDEST).
-
-_property: asm.formatBytecode(operations) => string @SRC<asm/assembler>
-Create a formatted output of an array of [[asm-operation]].
-
-_subsection: Abstract Syntax Tree @<asm-ast>
-
-Parsing an file using the [Ethers ASM Grammar](link-ethers-asm-grammar)
-will generate an Abstract Syntax Tree. The root node will always
+Parsing a file using the [Ethers ASM Dialect](asm-dialect) will
+generate an Abstract Syntax Tree. The root node will always
 be a [[asm-scopenode]] whose name is ``_``.
 
+To parse a file into an Abstract Syntax tree, use the [parse](asm-parse)
+function.
+
+
+_subsection: Types
+
 _heading: Location @<asm-location>
 
 _property: offset => number
@@ -85,6 +22,10 @@ _property: source => string
 The source code of this node.
 
 
+_subsection: Nodes
+
+@TODO: Place a diagram here showing the hierarchy
+
 _heading: Node @<asm-node> @SRC<asm:class.Node>
 
 _property: node.tag => string
@@ -112,6 +53,19 @@ value should be taken verbatim and no ``PUSH`` operation shoud be
 added, otherwise false.
 
 
+_heading: PopNode @<asm-popnode> @INHERIT<[[asm-valuenode]]> @SRC<asm:class.PopNode>
+
+A **PopNode** is used to store a place-holder for an implicit pop from the
+stack. It represents the code for an implicit place-holder (i.e. ``$$``) or an
+explicit place-holder (e.g. ``$1``), which indicates the expect stack position
+to consume.
+
+_property: literalNode.index => number
+
+The index this **PopNode** is representing. For an implicit place-holder
+this is ``0``.
+
+
 _heading: LinkNode @<asm-linknode> @INHERIT<[[asm-valuenode]]> @SRC<asm:class.LinkNode>
 
 A **LinkNode** represents a link to another [[asm-node]]'s data,
@@ -192,3 +146,5 @@ will use when resolving offset locations, using ``@myScope{ ... }``.
 
 _property: scopeNode.statements => Array<[[asm-node]]>
 The list of child nodes for this scope.
+
+

docs.wrm/api/other/assembly/dialect.wrm

@@ -0,0 +1,115 @@
+_section: Ethers ASM Dialect @<asm-dialect>
+
+This provides a quick, high-level overcview of the **Ethers ASM Dialect**
+for EVM, which is defined by the [Ethers ASM Dialect Grammar](link-ethers-asm-grammar)
+
+Once a program is compiled by a higher level langauge into ASM (assembly),
+or hand-coded directly in ASM, it needs to be assembled into bytecode.
+
+The assembly process performs a very small set of operations and is
+intentionally simple and closely related to the underlying EVM bytecode.
+
+Operations include embedding programs within programs (for example the
+deployment bootstrap has the runtime embedded in it) and computing the
+necessary offsets for jump operations.
+
+The [Command-Line Assembler](cli-asm) can be used to assemble an
+//Ethers ASM Dialect// file or to disassemble bytecode into its
+human-readable (ish) opcodes and literals.
+
+
+_subsection: Opcodes @<asm-dialect-opcode>
+
+An **Opcode** may be provided in either a //functional// or
+//instructional// syntax. For Opcodes that require parameters,
+the //functional// syntax is recommended and the //instructional//
+syntax will raise a warning.
+
+@TODO: Examples
+
+
+_subsection: Labels @<asm-dialect-label>
+
+A **Label** is a position in the program which can be jumped to. A
+``JUMPDEST`` is automatically added to this point in the assembled
+output.
+
+@TODO: Exmaples
+
+
+_subsection: Literals @<asm-dialect-literal>
+
+A **Literal** puts data on the stack when executed using a ``PUSH``
+operation.
+
+A **Literal** can be provided using a [[datahexstring]] or a decimal
+byte value.
+
+@TODO: exmples
+
+
+_subsection: Comments @<asm-dialect-comment>
+
+To enter a comment in the **Ethers ASM Dialect**, any text following
+a semi-colon (i.e. ``;``) is ignored by the assembler.
+
+
+_subsection: Scopes @<asm-dialect-scope>
+
+A common case in Ethereum is to have one program embedded in another.
+
+The most common use of this is embedding a Contract **runtime bytecode**
+within a **deployment bytecode**, which can be used as **init code**.
+
+When deploying a program to Ethereum, an **init transaction** is used. An
+//init transaction// has a null ``to`` address and contains bytecode in
+the ``data``. This ``data`` bytecode is a program, that when executed
+returns some other bytecode as a result, this restul is the bytecode
+to be installed.
+
+Therefore it is important that embedded code uses jumps relative to itself,
+not the entire program it is embedded in, which also means that a jump
+can **only** target its own scope, no parent or child scopes. This is
+enforced by the assembler.
+
+A scope may access the offset of any child [[asm-dialect-datasegment]] or
+child [[asm-dialect-scope]] (with respect to itself) and may access the length
+of any [[asm-dialect-datasegment]] or [[asm-dialect-scope]] anywhere in the program.
+
+Every program in the **Ethers ASM Dialect** has a top-leve scope named ``_``.
+
+
+_subsection: Data Segment @<asm-dialect-datasegment>
+
+A **Data Segment** allows arbitrary data to be embedded into a program,
+which can be useful for lookup tables or deploy-time constants.
+
+An emtpty **Data Segment** can also be used when a labelled location is
+required, but without the ``JUMPDEST`` which a [[asm-dialect-label]] adds.
+
+@TODO: Example
+
+
+_subsection: Links @<asm-dialect-links>
+
+A **Link** allows access to a [[asm-dialect-scope]], [[asm-dialect-datasegment]] or [[asm-dialect-label]].
+
+To access the byte offset of a labelled item, use ``$foobar``.
+
+For a [[asm-dialect-label]], the target must be directly reachable within this scope. For
+a [[asm-dialect-datasegment]] or a [[asm-dialect-scope]], it can be inside the same scope or any
+child scope.
+
+For a [[asm-dialect-datasegment]] or a [[asm-dialect-label]], there is an additional type of
+**Link**, which provides the length of the data or bytecode respectively. A
+**Length Link** is accessed by ``#foobar`` and is pushed on the stack as a
+literal.
+
+
+_subsection: Stack Placeholders @<asm-dialect-placeholder>
+
+@TODO: exampl
+
+
+_subsection: Evaluation and Excution @<asm-dialect-scripting>
+

docs.wrm/api/other/assembly/index.wrm

@@ -0,0 +1,6 @@
+_section: Assembly
+
+_toc:
+    dialect
+    api
+    ast

docs.wrm/api/other/hardware/index.wrm

@@ -1,5 +1,3 @@
-_title: Hardware Wallets
-
 _section: Hardware Wallets
 
 _subsection: LedgerSigner @<hw-ledger> @INHERIT<[[signer]]> @SRC<hardware-wallets:class.LedgerSigner>

docs.wrm/api/other/index.wrm

@@ -1,5 +1,3 @@
-_title: Other Libraries
-
 _section: Other Libraries
 
 Now that ethers is more modular, it is possible to have additional

docs.wrm/api/providers/api-providers.wrm

@@ -1,5 +1,3 @@
-_title: API Providers
-
 _section: API Providers
 
 There are many services which offer a web API for accessing
@@ -26,7 +24,7 @@ _definition: **Supported Networks**
 
 - Homestead (Mainnet)
 - Ropsten (proof-of-work testnet)
-- Rinkeby (proof-of-Authority testnet)
+- Rinkeby (proof-of-authority testnet)
 - Görli (clique testnet)
 - Kovan (proof-of-authority testnet)
 
@@ -40,7 +38,7 @@ _definition: **Supported Networks**
 
 - Homestead (Mainnet)
 - Ropsten (proof-of-work testnet)
-- Rinkeby (proof-of-Authority testnet)
+- Rinkeby (proof-of-authority testnet)
 - Görli (clique testnet)
 - Kovan (proof-of-authority testnet)
 
@@ -53,7 +51,7 @@ _definition: **Supported Networks**
 
 - Homestead (Mainnet)
 - Ropsten (proof-of-work testnet)
-- Rinkeby (proof-of-Authority testnet)
+- Rinkeby (proof-of-authority testnet)
 - Görli (clique testnet)
 - Kovan (proof-of-authority testnet)
 

docs.wrm/api/providers/index.wrm

@@ -1,5 +1,3 @@
-_title: Providers
-
 _section: Providers
 
 A **Provider** is an abstraction of a connection to the

docs.wrm/api/providers/jsonrpc-provider.wrm

@@ -1,5 +1,3 @@
-_title: JSON-RPC Provider
-
 _section: JsonRpcProvider  @<provider-jsonrpc> @INHERIT<[[provider]]>
 
 The [JSON-RPC API](link-jsonrpc) is a

docs.wrm/api/providers/other.wrm

@@ -1,5 +1,3 @@
-_title: Other Providers
-
 _section: Other Providers
 
 Others...

docs.wrm/api/providers/provider.wrm

@@ -1,6 +1,3 @@
-_title: Abstract Provider
-
-
 _section: Provider @<provider>
 
 Explain what a provider is...

docs.wrm/api/providers/types.wrm

@@ -1,8 +1,6 @@
-_title: Types
-
 _section: Types
 
-_heading: BlockTag @<provider-blocktag>
+_subsection: BlockTag @<provider-blocktag>
 A **BlockTag** specifies a specific location in the Blockchain.
 
 - **``"latest"``** -- The most recently mined block

docs.wrm/api/signer.wrm

@@ -1,5 +1,3 @@
-_title: Signer
-
 _section: Signers
 
 A Signer represents...
@@ -200,6 +198,10 @@ The address of this **VoidSigner**.
 
 _subsection: ExternallyOwnedAccount  @<externally-owned-account>
 
+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.
@@ -208,10 +210,8 @@ _property: eoa.privateKey => string<[[datahexstring]]<32>>
 
 The privateKey of this EOA
 
-_property: eoa.mnemonic => string
+_property: eoa.mnemonic => [[hdnode-mnemonic]]
 
-//Optional//. The account HD mnemonic, if it has one and can be determined.
-
-_property: eoa.path => string
-
-//Optional//. The account HD path, if it has one and can be determined.
+//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.

docs.wrm/api/utils/abi/fragments.wrm

@@ -1,6 +1,4 @@
-_title: Application Binary Interface
-
-_section: Application Binary Interface
+_section: Fragments
 
 Explain an ABI.
 
@@ -23,29 +21,30 @@ The Human-Readable ABI was
 
 [article](link-ricmoo-humanreadableabi)
 
-_heading: Output Formats @<abi-outputformats> @src<abi/fragments:FormatTypes>
+
+_heading: Output Formats @<abi-outputformats> @SRC<abi/fragments:FormatTypes>
 
 Each [[abi-fragment]] and [[abi-paramtype]] may be output using its ``format``
 method.
 
-_property: utils.FragmentTypes.full => string
+_property: ethers.utils.FragmentTypes.full => string
 
 This is a full human-readable string, including all parameter names, any
 optional modifiers (e.g. ``indexed``, ``public``, etc) and white-space
 to aid in human readabiliy.
 
-_property: utils.FragmentTypes.minimal => string
+_property: ethers.utils.FragmentTypes.minimal => string
 
 This is similar to ``full``, except with no unnecessary whitespace or parameter
 names. This is useful for storing a minimal string which can still fully
 reconstruct the original Fragment using [Fragment&thinsp;.&thinsp;from](abi-fragment-from).
 
-_property: utils.FragmentTypes.json => string
+_property: ethers.utils.FragmentTypes.json => string
 
 This returns a JavaScript Object which is safe to call ``JSON.stringify``
 on to create a JSON string.
 
-_property: utils.FragmentTypes.sighash => string
+_property: ethers.utils.FragmentTypes.sighash => string
 
 This is a minimal output format, which is used by Solidity when computing a
 signature hash or an event topic hash.
@@ -60,9 +59,9 @@ _subsection: Fragment @<abi-fragment> @SRC<abi/fragments:class.Fragment>
 
 An ABI is a collection of **Fragments**, where each fragment specifies:
 
-- An Event
-- A Function
-- A Constructor
+- An [Event](abi-eventfragment)
+- A [Function](abi-functionfragment)
+- A [Constructor](abi-constructorfragment)
 
 _heading: Properties
 
@@ -87,11 +86,11 @@ the Constructor, Event of Function.
 
 _heading: Methods
 
-_property: utils.Fragment.from(objectOrString) => [[abi-fragment]] @<abi-fragment-from> @SRC<abi/fragments:Fragment.from>
+_property: ethers.utils.Fragment.from(objectOrString) => [[abi-fragment]] @<abi-fragment-from> @SRC<abi/fragments:Fragment.from>
 
 Returns a 
 
-_property: utils.Fragment.isFragment(object) => boolean @<abi-isfragment> @SRC<abi/fragments:Fragment.isFragment>
+_property: ethers.utils.Fragment.isFragment(object) => boolean @<abi-isfragment> @SRC<abi/fragments:Fragment.isFragment>
 
 Tra lal al
 
@@ -119,11 +118,11 @@ This is the state mutability of the constructor. It can be any of:
 
 _heading: Methods
 
-_property: utils.ConstructorFragment.from(objectOrString) => [[abi-constructorfragment]] @<abi-constructorfragment-from> @SRC<abi/fragments:ConstructorFragment.from>
+_property: ethers.utils.ConstructorFragment.from(objectOrString) => [[abi-constructorfragment]] @<abi-constructorfragment-from> @SRC<abi/fragments:ConstructorFragment.from>
 
 Tra la la...
 
-_property: utils.ConstructorFragment.isConstructorFragment(object) => boolean @<abi-isconstructorfragment> @SRC<abi/fragments:ConstructorFragment.isConstructorFragment>
+_property: ethers.utils.ConstructorFragment.isConstructorFragment(object) => boolean @<abi-isconstructorfragment> @SRC<abi/fragments:ConstructorFragment.isConstructorFragment>
 
 Tra lal al
 
@@ -139,11 +138,11 @@ topic hash as topic0 when creating a log.
 
 _heading: Methods
 
-_property: utils.EventFragment.from(objectOrString) => [[abi-eventfragment]] @<abi-eventfragment-from> @SRC<abi/fragments:EventFragment.from>
+_property: ethers.utils.EventFragment.from(objectOrString) => [[abi-eventfragment]] @<abi-eventfragment-from> @SRC<abi/fragments:EventFragment.from>
 
 Tra la la...
 
-_property: utils.EventFragment.isEventFragment(object) => boolean @<abi-iseventfragment> @SRC<abi/fragments:EventFragment.isEventFragment>
+_property: ethers.utils.EventFragment.isEventFragment(object) => boolean @<abi-iseventfragment> @SRC<abi/fragments:EventFragment.isEventFragment>
 
 Tra lal al
 
@@ -172,11 +171,11 @@ A list of the Function output parameters.
 
 _heading: Method
 
-_property: utils.FunctionFragment.from(objectOrString) => [[abi-functionfragment]] @<abi-functionfragment-from> @SRC<abi/fragments:ConstructorFragment.from>
+_property: ethers.utils.FunctionFragment.from(objectOrString) => [[abi-functionfragment]] @<abi-functionfragment-from> @SRC<abi/fragments:ConstructorFragment.from>
 
 Tra la la...
 
-_property: utils.FunctionFragment.isFunctionFragment(object) => boolean @<abi-isfunctionfragment> @SRC<abi/fragments:FunctionFragment.isFunctionFragment>
+_property: ethers.utils.FunctionFragment.isFunctionFragment(object) => boolean @<abi-isfunctionfragment> @SRC<abi/fragments:FunctionFragment.isFunctionFragment>
 
 Tra lal al
 
@@ -229,14 +228,14 @@ _heading: Methods
 
 Tra la la...
 
-_property: paramType.format([ outputType = "sighash" ])
+_property: paramType.format([ outputType = sighash ])
 
 Tra la la...
 
-_property: utils.ParamType.from(objectOrString) => [[abi-paramtype]] @<abi-paramtype-from> @SRC<abi/fragments:ParamType.from>
+_property: ethers.utils.ParamType.from(objectOrString) => [[abi-paramtype]] @<abi-paramtype-from> @SRC<abi/fragments:ParamType.from>
 
 Tra la la...
 
-_property: utils.ParamType.isParamType(object) => boolean @<abi-paramtype-isparamtype> @SRC<abi/fragments:ParamType.isParamType>
+_property: ethers.utils.ParamType.isParamType(object) => boolean @<abi-paramtype-isparamtype> @SRC<abi/fragments:ParamType.isParamType>
 
 Tra la la...

docs.wrm/api/utils/abi/index.wrm

@@ -0,0 +1,5 @@
+_section: Application Binary Interface @NAV<ABI>
+
+_toc:
+  interface
+  fragments

docs.wrm/api/utils/abi/interface.wrm

@@ -0,0 +1,196 @@
+_section: Interface @<abi-interface> @SRC<abi/interface:class.Interface>
+
+The **Interface** Class abstracts the encoding and decoding required
+to interact with contracts on the Ethereum network.
+
+Many of the standards organically evolved along side the [[link-solidity]]
+language, which other languages have adopted to remain compatibile with
+existing deployed contracts.
+
+The EVM itself does not understand what the ABI is. It is simply an agreed
+upon set of formats to encode various types of data which each contract can
+expect so they can interoperate with each other.
+
+
+_subsection: Creating Instances
+
+_property: new ethers.utils.Interface(abi) @SRC<abi/interface:constructor.Interface>
+Create a new **Interface** from a JSON string or object representing
+//abi//.
+
+The //abi// may be a JSON string or the parsed Object (using JSON.parse)
+which is emitted by the [Solidity compiler](link-solc-output) (or compatible languages).
+
+The //abi// may also be a [Human-Readable Abi](link-ricmoo-humanreadableabi),
+which is a format the Ethers created to simplify manually typing the ABI
+into the source and so that a Contract ABI can also be referenced easily
+within the same source file.
+
+_subsection: Properties
+
+_property: interface.fragments => Array<[[abi-fragment]]>
+All the [Fragments](abi-fragment) in the interface.
+
+_property: interface.events => Array<[[abi-eventfragment]]>
+All the [Event Fragments](abi-eventfragment) in the interface.
+
+_property: interface.functions => Array<[[abi-functionfragment]]>
+All the [Function Fragments](abi-functionfragment) in the interface.
+
+_property: interface.deploy => [[abi-constructorfragment]]
+The [Constructor Fragments](abi-constructorfragment) for the interface.
+
+
+_subsection: Formatting
+
+_property: interface.format( [ format ]) => string | Array<string> @SRC<abi/interface>
+Return the formatted **Interface**. If the format type is ``json`` a
+single string is returned, otherwise an Array of the human-readable
+strings is returned.
+
+
+_subsection: Fragment Access
+
+_property: interface.getFunction(fragment) => [[abi-functionfragment]]  @SRC<abi/interface>
+Returns the [[abi-functionfragment]] for //fragment// (see [[abi-fragmentid]]).
+
+_property: interface.getEvent(fragment) => [[abi-eventfragment]] @SRC<abi/interface>
+Returns the [[abi-eventfragment]] for //fragment// (see [[abi-fragmentid]]).
+
+
+_subsection: Signature and Topic Hashes
+
+_property: interface.getSighash(fragment) => string<[[datahexstring]]<4>> @SRC<abi/interface:method.Interface.getSighash>
+Return the sighash (or Function Selector) for //fragment// (see [[abi-fragmentid]]).
+
+_property: interface.getEventTopic(fragment) => string<[[datahexstring]]<32>> @SRC<abi/interface:method.Interface.getEventTopic>
+Return the topic hash for //fragment// (see [[abi-fragmentid]]).
+
+
+_subsection: Encoding Data
+
+_property: interface.encodeDeploy([ values ]) => string<[[datahexstring]]> @SRC<abi/interface>
+Return the encoded deployment data, which can be concatenated to the
+deployment bytecode of a contract to pass //values// into the contract
+constructor.
+
+_property: interface.encodeFilterTopics(fragment [ , values ]) => Array<topic | Array<topic>> @SRC<abi/interface>
+Returns the encoded topic filter, which can be passed to getLogs for //fragment//
+(see [[abi-fragmentid]]) for the given //values//.
+
+Each //topic// is a 32 byte (64 nibble) [[datahexstring]].
+
+_property: interface.encodeFunctionData(fragment [ , values ]) => string<[[datahexstring]]> @SRC<abi/interface>
+Returns the encoded data, which can be used as the data for a transaction for
+//fragment// (see [[abi-fragmentid]]) for the given //values//.
+
+_property: interface.encodeFunctionResult(fragment [ , values ]) => string<[[datahexstring]]> @SRC<abi/interface>
+Returns the encoded result, which would normally be the response from a call for
+//fragment// (see [[abi-fragmentid]]) for the given //values//.
+
+Most developers will not need this method, but may be useful for authors of a mock blockchain.
+
+
+_subsection: Decoding Data
+
+_property: interface.decodeEventLog(fragment, data [ , topics ]) => [[abi-result]] @SRC<abi/interface>
+Returns the decoded event values from an event log for
+//fragment// (see [[abi-fragmentid]]) for the given //data//
+with the optional //topics//.
+
+If //topics// is not specified, placeholders will be inserted into the result.
+
+_property: interface.decodeFunctionData(fragment, data) => [[abi-result]] @SRC<abi/interface>
+Returns the decoded values from transaction data for
+//fragment// (see [[abi-fragmentid]]) for the given //data//.
+
+Most developers will not need this method, but may be useful for debugging
+or inspecting transactions.
+
+_property: interface.decodeFunctionResult(fragment, data) => [[abi-result]] @SRC<abi/interface>
+Returns the decoded values from the result of a call for
+//fragment// (see [[abi-fragmentid]]) for the given //data//.
+
+
+_subsection: Parsing
+
+The functions are generally the most useful for most developers. They will
+automatically search the ABI for a matching Event or Function and decode
+the components as a fully specified description.
+
+_property: interface.parseLog(log) => [[abi-log]] @SRC<abi/interface>
+Search the event that matches the //log// topic hash and parse the values
+the log represents.
+
+_property: interface.parseTransaction(transaction) => [[abi-transaction]] @SRC<abi/interface>
+Search for the function that matches the //transaction// data sighash
+and parse the transaction properties.
+
+
+_subsection: Types
+
+_heading: Result @<abi-result> @INHERIT<Array&lt;any&gt;>
+
+A **Result** is an array, so each value can be accessed as a positional
+argument.
+
+Additionally, if values are named, the identical object as its positional
+value can be accessed by its name.
+
+The name ``length`` is however reserved as it is part of the Array, so
+any named value for this key is renamed to ``_length``. If there is a
+name collision, only the first is available by its key.
+
+
+_heading: LogDescription @<abi-log>
+
+_property: logDescription.args => [[abi-result]]
+The values of the input parameters of the event.
+
+_property: logDescription.eventFragment => [[abi-eventfragment]]
+The [[abi-eventfragment]] which matches the topic in the Log.
+
+_property: logDescription.name => string
+The event name. (e.g. ``Transfer``)
+
+_property: logDescription.signature => string
+The event signature. (e.g. ``Transfer(address,address,uint256)``)
+
+_property: logDescription.topic => string
+The topic hash.
+
+
+_heading: TransactionDescription @<abi-transaction>
+
+_property: transactionDescription.args => [[abi-result]]
+The decoded values from the transaction data which were passed
+as the input parameters.
+
+_property: transactionDescription.functionFragment => [[abi-functionfragment]]
+The [[abi-functionfragment]] which matches the sighash in the transaction data.
+
+_property: transactionDescription.name => string
+The name of the function. (e.g. ``transfer``)
+
+_property: transactionDescription.sighash => string
+The sighash (or function selector) that matched the transaction data.
+
+_property: transactionDescription.signature => string
+The signature of the function. (e.g. ``transfer(address,uint256)``)
+
+_property: transactionDescription.value => [[bignumber]]
+The value from the transaction.
+
+
+_subsection: Specifying Fragments @<abi-fragmentid>
+
+When specifying a fragment to any of the functions in an **Interface**,
+any of the following may be used:
+
+- The name of the event or function, if it is unique and non-ambiguous
+  within the ABI (e.g. ``transfer``)
+- The signature of the event or function. The signature is normalized,
+  so, for example, ``uint`` and ``uint256`` are equivalent (e.g. ``transfer(address, uint)``)
+- The sighash or topichash of the function. The sighash is often referred
+  to the function selector in Solidity (e.g. ``0xa9059cbb``)
+- A [[abi-fragment]]    

docs.wrm/api/utils/address.wrm

@@ -1,5 +1,3 @@
-_title: Addresses
-
 _section: Addresses @<addresses>
 
 Explain addresses,formats and checksumming here.
@@ -43,7 +41,7 @@ To convert an address into the ICAP format, see [getIcapAddress](utils-getIcapAd
 
 _subsection: Functions
 
-_property: utils.getAddress(address) => string<[[address]]>  @<utils-getAddress> @SRC<address>
+_property: ethers.utils.getAddress(address) => string<[[address]]>  @<utils-getAddress> @SRC<address>
 Returns //address// as a Checksum Address.
 
 If //address// is an invalid 40-nibble [[hexstring]] or if it contains mixed case and
@@ -52,17 +50,17 @@ the checksum is invalid, an InvalidArgument Error is throw.
 The value of //address// may be any supported address format.
 
 
-_property: utils.isAddress(address) => boolean  @<utils-isAddress> @SRC<address>
+_property: ethers.utils.isAddress(address) => boolean  @<utils-isAddress> @SRC<address>
 Returns true if //address// is valid (in any supported format).
 
-_property: utils.getIcapAddress(address) => string<[IcapAddress](address-icap)>  @<utils-getIcapAddress> @SRC<address>
+_property: ethers.utils.getIcapAddress(address) => string<[IcapAddress](address-icap)>  @<utils-getIcapAddress> @SRC<address>
 Returns //address// as an [ICAP address](link-icap).
 Supports the same restrictions as [utils.getAddress](utils-getAddress).
 
-_property: utils.getContractAddress(transaction) => string<[[address]]>  @<utils-getcontractaddress> @SRC<address>
+_property: ethers.utils.getContractAddress(transaction) => string<[[address]]>  @<utils-getcontractaddress> @SRC<address>
 Returns the contract address that would result if //transaction// was
 used to deploy a contract.
 
-_property: utils.getCreate2Address(from, salt, initCodeHash) => string<[[address]]> @<utils.getCreate2Address> @SRC<address>
+_property: ethers.utils.getCreate2Address(from, salt, initCodeHash) => string<[[address]]> @<utils-getCreate2Address> @SRC<address>
 Returns the contract address that would result from the given
 [CREATE2](link-eip-1014) call.

docs.wrm/api/utils/bignumber.wrm

@@ -1,9 +1,15 @@
-_title: Big Number
-
-
 _section: BigNumber @<bignumber>
 
-Explain about BigNumber here...
+Many operations in Ethereum operation on numbers which are
+[outside the range of safe values](notes-safenumbers) to use
+in JavaScript.
+
+A **BigNumber** is an object which safely allows mathematic operations
+on numbers of any magnitude.
+
+Most operations which need to return a value will return a **BigNumber**
+and parameters which accept values will generally accept them.
+
 
 _heading: Importing
 
@@ -25,10 +31,10 @@ _definition: **//BytesLike//**
 A [BytesLike](byteslike) Object, such as an Array or Uint8Array.
 
 _definition: **//BigNumber//**
-An existing BigNumber instance.
+An existing [[bignumber]] instance.
 
 _definition: **//number//**
-A number that is within the safe range for JavaScript numbers.
+A number that is within the [safe range](link-js-maxsafe) for JavaScript numbers.
 
 _definition: **//BigInt//**
 A JavaScript [BigInt](link-js-bigint)
@@ -39,10 +45,10 @@ _subsection: Creating Instances
 
 The constructor of BigNumber cannot be called directly. Instead, Use the static ``BigNumber.from``.
 
-_property: BigNumber.from(aBigNumberish) => [[bignumber]]
+_property: ethers.BigNumber.from(aBigNumberish) => [[bignumber]]
 Returns an instance of a **BigNumber** for //aBigNumberish//.
 
-_heading: Examples:
+_heading: Examples:  @<>
 
 _code: bignumber-create.js
 
@@ -129,12 +135,12 @@ _property: bignumber.toString() => string  @SRC<bignumber:BigNumber.toString>
 Returns the value of //bignumber// as a base-10 string.
 
 _property: bignumber.toHexString() => string<[[datahexstring]]>  @SRC<bignumber:BigNumber.toHexString>
-Returns the value of //bignumber// as a base-16, `0x`-prefixed [hexstring](hexstring).
+Returns the value of //bignumber// as a base-16, ``0x``-prefixed [[datahexstring]].
 
 
 _heading: Inspection
 
-_property: BigNumnber.isBigNumber(object) => boolean  @SRC<bignumber>
+_property: ethers.BigNumnber.isBigNumber(object) => boolean  @SRC<bignumber>
 Returns true if and only if the //object// is a BigNumber object.
 
 
@@ -142,11 +148,13 @@ _heading: Examples
 
 _code: bignumber-examples.js
 
+
 _subsection: Notes
 
-A few short notes on numbers...
+This section is a for a couple of questions that come up frequently.
 
-_heading: Why can't I just use numbers?
+
+_heading: Why can't I just use numbers? @<notes-safenumbers>
 
 The first problem many encounter when dealing with Ethereum is
 the concept of numbers. Most common currencies are broken down
@@ -173,3 +181,61 @@ The functions [parseEther( etherString )](http://linkto) and
 between string representations, which are displayed to or entered
 by the user and Big Number representations which can have
 mathematical operations handled safely.
+
+
+_heading: Why not BigNumber.js, BN.js, BigDecimal, etc?
+
+Everyone has their own favourite Big Number library, and once someone
+has choosen one, it becomes part of their identity, like their editor,
+vi vs emacs. There are over 100 Big Number libraries on [npm](link-npm-query-bignumber).
+
+One of the biggest differences between the Ethers [[bignumber]] object and
+other libraries is that it is immutable, which is very important when
+dealing with the asynchronous nature of the blockchain.
+
+Capturing the value is not safe in async functions, so immutability
+protects us from easy to make mistakes, which is not possible on the
+low-level library's objects which supports myriad in-place operations.
+
+Second, the Ethers [[bignumber]] provides all the functionality required
+internally and should generally be sufficient for most developers while
+not exposing some of the more advanced and rare functionality. So it will
+be eaiser to swap out the underlying library without impacting consumers.
+
+For example, if [[link-npm-bnjs]] was exposed, someone may use the
+greatest-common-denominator functions, which would then be functionality
+the replacing library should also provide to ensure anyone depending on
+that functionality is not broken.
+
+
+_heading: Why BN.js??
+
+The reason why [[link-npm-bnjs]] is used internally as the big
+number is because that is the library used by [[link-npm-elliptic]].
+
+Therefore it **must** be included regardless, so we leverage that
+library rather than adding another Big Number library, which would
+mean two different libraries offering the same functionality.
+
+This has saved about 85kb (80% of this library size) of library size
+over other libraries which include separate Big Number libraries for
+various purposes.
+
+
+_heading: Why not allow us to set a global Big Number library?
+
+Another comment that comes up frequently is tha desire to specify a
+global user-defined Big Number library, which all functions would
+return.
+
+This becomes problematic since your code may live along side other
+libraries or code that use Ethers. In fact, even Ethers uses a lot
+of the public functions internally.
+
+If you, for example, used a library that used ``a.plus(b)`` instead
+of ``a.add(b)``, this would break Ethers when it tries to compute
+fees internally, and other libraries likely have similar logic.
+
+But, the [[bignumber]] prototype is exposed, so you can always add a
+``toMyCustomBigNumber()`` method to all [[bignumber]]'s globally
+which is safe.

docs.wrm/api/utils/bytes.wrm

@@ -1,5 +1,3 @@
-_title: Byte Manipulation
-
 _section: Byte Manipulation
 
 Tra la la...
@@ -55,13 +53,13 @@ missing values can be computed).
 
 _subsection: Inspection
 
-_property: utils.isBytes(object) => boolean  @<utils-isbytes> @SRC<bytes>
+_property: ethers.utils.isBytes(object) => boolean  @<utils-isbytes> @SRC<bytes>
 Returns true if and only if //object// is a valid [[bytes]].
 
-_property: utils.isBytesLike(object) => boolean  @<utils-isbyteslike> @SRC<bytes>
+_property: ethers.utils.isBytesLike(object) => boolean  @<utils-isbyteslike> @SRC<bytes>
 Returns true if and only if //object// is a [[bytes]] or [[datahexstring]].
 
-_property: utils.isHexString(object, [ length ] ) => boolean  @<utils-ishexstring> @SRC<bytes>
+_property: ethers.utils.isHexString(object, [ length ] ) => boolean  @<utils-ishexstring> @SRC<bytes>
 Returns true if and only if //object// is a valid hex string.
 If //length// is specified and //object// is not a valid [[datahexstring]] of
 //length// bytes, an InvalidArgument error is thrown.
@@ -69,13 +67,13 @@ If //length// is specified and //object// is not a valid [[datahexstring]] of
 
 _subsection: Converting between Arrays and Hexstrings
 
-_property: utils.arrayify(datahexstringOrArrayish [ , options ]) => Uint8Array  @<utils-arrayify> @SRC<bytes>
+_property: ethers.utils.arrayify(datahexstringOrArrayish [ , options ]) => Uint8Array  @<utils-arrayify> @SRC<bytes>
 Converts //datahexstringOrArrayish// to a Uint8Array.
 
-_property: utils.hexlify(hexstringOrArrayish) => string<[[datahexstring]]>  @<utils-hexlify> @SRC<bytes>
+_property: ethers.utils.hexlify(hexstringOrArrayish) => string<[[datahexstring]]>  @<utils-hexlify> @SRC<bytes>
 Converts //hexstringOrArrayish// to a [[datahexstring]].
 
-_property: utils.hexValue(aBigNumberish) => string<[[hexstring]]>  @<utils-hexvalue> @SRC<bytes>
+_property: ethers.utils.hexValue(aBigNumberish) => string<[[hexstring]]>  @<utils-hexvalue> @SRC<bytes>
 Converts //aBigNumberish// to a [[hexstring]], with no __unnecessary__ leading
 zeros.
 
@@ -86,13 +84,13 @@ _code: bytes-conversion.js
 
 _subsection: Array Manipulation
 
-_property: utils.concat(arrayOfBytesLike) => Uint8Array  @<utils-concat> @SRC<bytes>
+_property: ethers.utils.concat(arrayOfBytesLike) => Uint8Array  @<utils-concat> @SRC<bytes>
 Concatenates all the [[byteslike]] in //arrayOfBytesLike// into a single Uint8Array.
 
-_property: utils.stripZeros(aBytesLike) => Uint8Array  @<utils-stripzeros> @SRC<bytes>
+_property: ethers.utils.stripZeros(aBytesLike) => Uint8Array  @<utils-stripzeros> @SRC<bytes>
 Returns a Uint8Array with all leading ``0`` bytes of //aBtyesLike// removed.
 
-_property: utils.zeroPad(aBytesLike, length) => Uint8Array  @<utils-zeropad> @SRC<bytes>
+_property: ethers.utils.zeroPad(aBytesLike, length) => Uint8Array  @<utils-zeropad> @SRC<bytes>
 Retutns a Uint8Array of the data in //aBytesLike// with ``0`` bytes prepended to
 //length// bytes long.
 
@@ -102,22 +100,22 @@ error will be thrown.
 
 _subsection: Hexstring Manipulation
 
-_property: utils.hexConcat(arrayOfBytesLike) => string<[[datahexstring]]>  @<utils-hexconcat> @SRC<bytes>
+_property: ethers.utils.hexConcat(arrayOfBytesLike) => string<[[datahexstring]]>  @<utils-hexconcat> @SRC<bytes>
 Concatenates all the [[byteslike]] in //arrayOfBytesLike// into a single [[datahexstring]]
 
-_property: utils.hexDataLength(aBytesLike) => string<[[datahexstring]]>  @<utils-hexdatalength> @SRC<bytes>
+_property: ethers.utils.hexDataLength(aBytesLike) => string<[[datahexstring]]>  @<utils-hexdatalength> @SRC<bytes>
 Returns the length (in bytes) of //aBytesLike//.
 
-_property: utils.hexDataSlice(aBytesLike, offset [ , endOffset ] ) => string<[[datahexstring]]>  @<utils-hexdataslice> @SRC<bytes>
+_property: ethers.utils.hexDataSlice(aBytesLike, offset [ , endOffset ] ) => string<[[datahexstring]]>  @<utils-hexdataslice> @SRC<bytes>
 Returns a [[datahexstring]] representation of a slice of //aBytesLike//, from
 //offset// (in bytes) to //endOffset// (in bytes). If //endOffset// is
 omitted, the length of //aBytesLike// is used.
 
-_property: utils.hexStripZeros(aBytesLike) => string<[[hexstring]]>  @<utils-hexstripzeros> @SRC<bytes>
+_property: ethers.utils.hexStripZeros(aBytesLike) => string<[[hexstring]]>  @<utils-hexstripzeros> @SRC<bytes>
 Returns a [[hexstring]] representation of //aBytesLike// with all
 leading zeros removed.
 
-_property: utils.hexZeroPad(aBytesLike, length) => string<[[datahexstring]]>  @<utils-hexzeropad> @SRC<bytes>
+_property: ethers.utils.hexZeroPad(aBytesLike, length) => string<[[datahexstring]]>  @<utils-hexzeropad> @SRC<bytes>
 Returns a [[datahexstring]] representation of //aBytesLike// padded to //length// bytes.
 
 If //aBytesLike// is already longer than //length// bytes long, an InvalidArgument
@@ -126,11 +124,18 @@ error will be thrown.
 
 _subsection: Signature Conversion
 
-_property: utils.joinSignature(aSignatureLike) => string<[FlatSignature](signature-flat)>  @<utils-joinsignature> @SRC<bytes>
+_property: ethers.utils.joinSignature(aSignatureLike) => string<[FlatSignature](signature-flat)>  @<utils-joinsignature> @SRC<bytes>
 Return the flat-format of //aSignaturelike//, which is 65 bytes (130 nibbles)
 long, concatenating the **r**, **s** and (normalized) **v** of a Signature.
 
-_property: utils.splitSignature(aSignatureLikeOrBytesLike) => [[signature]]  @<utils-splitsignature> @SRC<bytes>
+_property: ethers.utils.splitSignature(aSignatureLikeOrBytesLike) => [[signature]]  @<utils-splitsignature> @SRC<bytes>
 Return the full expanded-format of //aSignaturelike// or a flat-format [[datahexstring]].
 Any missing properties will be computed.
 
+_subsection: Random Bytes
+
+_property: ethers.utils.randomBytes(length) => Uint8Array  @<utils-randombytes> @SRC<random/index>
+Return a new Uint8Array of //length// random bytes.
+
+_property: ethers.utils.shuffled(array) => Array<any>  @<utils.shuffled> @SRC<random>
+Return a copy of //array// shuffled using [[link-wiki-shuffle]].

docs.wrm/api/utils/constants.wrm

@@ -1,5 +1,3 @@
-_title: Constants
-
 _section: Constants @<constants>
 
 The **ethers.contants** Object contains commonly used values.
@@ -11,38 +9,38 @@ _code: constants-import.js
 
 _subsection: Bytes
 
-_property: constants.AddressZero => string<[Address](address)>  @<constants-addresszero> @SRC<constants>
+_property: ethers.constants.AddressZero => string<[Address](address)>  @<constants-addresszero> @SRC<constants>
 The Address Zero, which is 20 bytes (40 nibbles) of zero.
 
-_property: constants.HashZero => string<[[datahexstring]]<32>>  @<constants-hashzero> @SRC<constants>
+_property: ethers.constants.HashZero => string<[[datahexstring]]<32>>  @<constants-hashzero> @SRC<constants>
 The Hash Zero, which is 32 bytes (64 nibbles) of zero.
 
 
 _subsection: Strings
 
-_property: constants.EtherSymbol => string  @<constants-ethersymbol> @SRC<constants>
+_property: ethers.constants.EtherSymbol => string  @<constants-ethersymbol> @SRC<constants>
 The Ether symbol, **&Xi;**.
 
 
 _subsection: BigNumber
 
-_property: constants.NegativeOne => [[bignumber]]  @<constants-negativeone> @SRC<constants>
+_property: ethers.constants.NegativeOne => [[bignumber]]  @<constants-negativeone> @SRC<constants>
 The BigNumber value representing ``"-1"``.
 
-_property: constants.Zero => [[bignumber]]  @<constants-zero> @SRC<constants>
+_property: ethers.constants.Zero => [[bignumber]]  @<constants-zero> @SRC<constants>
 The BigNumber value representing ``"0"``.
 
-_property: constants.One => [[bignumber]]  @<constants-one> @SRC<constants>
+_property: ethers.constants.One => [[bignumber]]  @<constants-one> @SRC<constants>
 The BigNumber value representing ``"1"``.
 
-_property: constants.Two => [[bignumber]]  @<constants-two> @SRC<constants>
+_property: ethers.constants.Two => [[bignumber]]  @<constants-two> @SRC<constants>
 The BigNumber value representing ``"2"``.
 
-_property: constants.WeiPerEther => [[bignumber]]  @<constants-weiperether> @SRC<constants>
+_property: ethers.constants.WeiPerEther => [[bignumber]]  @<constants-weiperether> @SRC<constants>
 The BigNumber value representing ``"1000000000000000000"``, which is the
 number of Wei per Ether.
 
-_property: constants.MaxUint256 => [[bignumber]]  @<constants-maxuint256> @SRC<constants>
+_property: ethers.constants.MaxUint256 => [[bignumber]]  @<constants-maxuint256> @SRC<constants>
 The BigNumber value representing the maximum ``uint256`` value.
 
 

docs.wrm/api/utils/display-logic.wrm

@@ -1,5 +1,3 @@
-_title: Display Logic and Input
-
 _section: Display Logic and Input
 
 When creating an Application, it is useful to convert between
@@ -46,23 +44,23 @@ _subsection: Functions
 
 _heading: Formatting
 
-_property: utils.commify(value) => string  @<util-commify> @SRC<units>
+_property: ethers.utils.commify(value) => string  @<utils-commify> @SRC<units>
 Returns a string with value grouped by 3 digits, separated by ``,``.
 
 
 _heading: Conversion @<unit-conversion>
 
-_property: utils.formatUnits(value [ , unit = "ether" ] ) => string  @<util-formatunits> @SRC<units>
+_property: ethers.utils.formatUnits(value [ , unit = "ether" ] ) => string  @<utils-formatunits> @SRC<units>
 Returns a string representation of //value// formatted with //unit//
 digits (if it is a number) or to the unit specified (if a string).
 
-_property: utils.formatEther(value) => string  @<util-formatether> @SRC<units>
+_property: ethers.utils.formatEther(value) => string  @<utils-formatether> @SRC<units>
 The equivalent to calling ``formatUnits(value, "ether")``.
 
-_property: utils.parseUnits(value [ , unit = "ether" ] ) => [BigNumber](bignumber)  @<util-parseunits> @SRC<units>
+_property: ethers.utils.parseUnits(value [ , unit = "ether" ] ) => [BigNumber](bignumber)  @<utils-parseunits> @SRC<units>
 Returns a [BigNumber](bignumber) representation of //value//, parsed with
 //unit// digits (if it is a number) or from the unit specified (if
 a string).
 
-_property: utils.parseEther(value) => [BigNumber](bignumber)  @<util-parseether> @SRC<units>
+_property: ethers.utils.parseEther(value) => [BigNumber](bignumber)  @<utils-parseether> @SRC<units>
 The equivalent to calling ``parseUnits(value, "ether")``.

docs.wrm/api/utils/encoding.wrm

@@ -1,21 +1,49 @@
-_title: Encoding Utilies
+_section: Encoding Utilities @<encoding>
 
-_section: Encoding Utilities
-
-_property: utils.base58.decode(textData) => Uin8Array
+_subsection: Base58 @<bse58> @SRC<basex:Base58>
 
+_property: ethers.utils.base58.decode(textData) => Uin8Array
 Return a typed Uint8Array representation of //textData// decoded using
 base-58 encoding.
 
-_property: utils.base58.encode(aBytesLike) => string
-
+_property: ethers.utils.base58.encode(aBytesLike) => string
 Return //aBytesLike// encoded as a string using the base-58 encoding.
 
-_property: utils.base64.decode(textData) => Uin8Array
 
+_subsection: Base64 @<base64>
+
+_property: ethers.utils.base64.decode(textData) => Uin8Array  @SRC<base64>
 Return a typed Uint8Array representation of //textData// decoded using
 base-64 encoding.
 
-_property: utils.base64.encode(aBytesLike) => string
-
+_property: ethers.utils.base64.encode(aBytesLike) => string  @SRC<base64>
 Return //aBytesLike// encoded as a string using the base-64 encoding.
+
+
+_subsection: Recursive-Length Prefix @<rlp>
+
+The [[link-rlp]] encoding is used throughout Ethereum to serialize nested
+structures of Arrays and data.
+
+_property: ethers.utils.RLP.encode(dataObject) => string<[[datahexstring]]>  @<rlp-encode> @SRC<rlp>
+Encode a structured Data Object into its RLP-encoded representation.
+
+Each Data component may be an valid [[byteslike]].
+
+_property: ethers.utils.RLP.decode(aBytesLike) => [DataObject](rlp-dataobject)  @<rlp-decode> @SRC<rlp>
+Decode an RLP-encoded //aBytesLike// into its structured Data Object.
+
+All Data components will be returned as a [[datahexstring]].
+
+_heading: Data Object @<rlp-dataobject>
+
+A **Data Object** is a recursive structure which is used to serialize many
+internal structures in Ethereum. Each **Data Object** can either be:
+
+- Binary Data
+- An Array of **Data Objects** (i.e. this recursively includes Nesting)
+
+_definition: **Examples**
+
+- ``"0x1234"``
+- ``[ "0x1234", [ "0xdead", "0xbeef" ], [ ] ]``

docs.wrm/api/utils/fixednumber.wrm

@@ -1,55 +1,8 @@
-_title: Fixed Number
-
 _section: FixedNumber @<fixednumber>
 
-_subsection: FixedFormat @<fixedformat>
-
-A **FixedFormat** is a simple object which represents a decimal
-(base-10) Fixed-Point data representation. Usually using this
-class directly is uneccessary, as passing in a [[fixedformatstring]]
-directly into the [[fixednumber]] will automatically create this.
-
-_heading: Format Strings  @<fixedformatstring>
-
-A format string is composed of three components, including signed-ness,
-bit-width and number of decimals.
-
-A signed format string begins with ``fixed``, which an unsigned format
-string begins with ``ufixed``, followed by the width (in bits) and the
-number of decimals.
-
-The width must be conguent to 0 mod 8 (i.e. ``(width % 8) == 0``) and no
-larger than 256 bits and the number of decimals must be no larger than 80.
-
-For example:
-
-- **fixed128x18** is signed, 128 bits wide and has 18 decimals; this is useful for most purposes
-- **fixed32x0** is signed, 32 bits wide and has 0 decimals; this would be the same as a ``int32_t` in C
-- **ufixed32x0** is unsigned, 32 bits wide and has 0 decimals; this would be the same as a ``uint32_t` in C
-- **fixed** is shorthand for ``fixed128x18`
-- **ufixed** is shorthand for ``ufixed128x18`
-
-_heading: Creating Instances
-
-_property: FixedFormat.from(value = "fixed128x18") => [[fixedformat]]  @<fixednumber-from> @SRC<bignumber/fixednumber:FixedFormat.from>
-
-Returns a new instance of a **FixedFormat** defined by //value//. Any valid [[fixedformatstring]]
-may be passed in as well as any object which has any of ``signed``, ``width`` and ``decimals``
-defined, including a [[fixedformat]] object.
-
-_heading: Properties
-
-_property: fixedFormat.signed => boolean
-
-_property: fixedFormat.width => number
-
-_property: fixedFormat.decimals => number
-
-_property: fixedFormat.name => string
-
-
-_definition: **//"fixed"//**
-A shorthand for ``fixed128x80``.
+A **FixedNumber** is a fixed-width (in bits) number with an internal
+base-10 divisor, which allows it to represent a decimal fractional
+component.
 
 _subsection: Creating Instances
 
@@ -117,3 +70,57 @@ _heading: Inspection
 _property: FixedNumber.isFixedNumber(value) => boolean  @SRC<bignumber/fixednumber>
 Returns true if and only if //value// is a **FixedNumber**.
 
+
+_subsection: FixedFormat @<fixedformat>
+
+A **FixedFormat** is a simple object which represents a decimal
+(base-10) Fixed-Point data representation. Usually using this
+class directly is uneccessary, as passing in a [[fixedformatstring]]
+directly into the [[fixednumber]] will automatically create this.
+
+_heading: Format Strings  @<fixedformatstring>
+
+A format string is composed of three components, including signed-ness,
+bit-width and number of decimals.
+
+A signed format string begins with ``fixed``, which an unsigned format
+string begins with ``ufixed``, followed by the width (in bits) and the
+number of decimals.
+
+The width must be conguent to 0 mod 8 (i.e. ``(width % 8) == 0``) and no
+larger than 256 bits and the number of decimals must be no larger than 80.
+
+For example:
+
+- **fixed128x18** is signed, 128 bits wide and has 18 decimals; this is useful for most purposes
+- **fixed32x0** is signed, 32 bits wide and has 0 decimals; this would be the same as a ``int32_t` in C
+- **ufixed32x0** is unsigned, 32 bits wide and has 0 decimals; this would be the same as a ``uint32_t` in C
+- **fixed** is shorthand for ``fixed128x18`
+- **ufixed** is shorthand for ``ufixed128x18`
+
+_heading: Creating Instances
+
+_property: FixedFormat.from(value = "fixed128x18") => [[fixedformat]]  @<fixednumber-from> @SRC<bignumber/fixednumber:FixedFormat.from>
+
+Returns a new instance of a **FixedFormat** defined by //value//. Any valid [[fixedformatstring]]
+may be passed in as well as any object which has any of ``signed``, ``width`` and ``decimals``
+defined, including a [[fixedformat]] object.
+
+_heading: Properties
+
+_property: fixedFormat.signed => boolean
+The signed-ness of //fixedFormat//, true if negative values are supported.
+
+_property: fixedFormat.width => number
+The width (in bits) of //fixedFormat//.
+
+_property: fixedFormat.decimals => number
+The number of decimal points of //fixedFormat//.
+
+_property: fixedFormat.name => string
+The name of the //fixedFormat//, which can be used to recreate the format
+and is the string that the Solidity language uses to represent this format.
+
+_definition: **//"fixed"//**
+A shorthand for ``fixed128x80``.
+

docs.wrm/api/utils/hashing.wrm

@@ -1,5 +1,3 @@
-_title: Hashing
-
 _section: Hashing Algorithms
 
 Explain what hash functions are?
@@ -39,12 +37,12 @@ Use the [SHA2-512](link-wiki-sha2) hash algorithm.
 _subsection: Common Hashing Helpers
 
 _property: ethers.utils.hashMessage(message) => string<[[datahexstring]]<32>>  @<utils-hashmessage> @SRC<hash>
-Computes the Ethereum message digest of //message//. Ethereum messages are
+Computes the [[link-eip-191]] personal message digest of //message//. Personal messages are
 converted to UTF-8 bytes and prefixed with ``\\x19Ethereum Signed Message:``
 and the length of //message//.
 
 _property: ethers.utils.id(text) => string<[[datahexstring]]<32>>  @<utils-id> @SRC<hash>
-The Ethereum Identity function computs the keccak256 hash of the //text// bytes.
+The Ethereum Identity function computs the [KECCAK256](link-wiki-sha3) hash of the //text// bytes.
 
 _property: ethers.utils.namehash(name) => string<[[datahexstring]]<32>>  @<utils-namehash> @SRC<hash>
 Returns the [ENS Namehash](link-namehash) of //name//.
@@ -61,11 +59,11 @@ Returns the non-standard encoded //arrayOfValues// packed according to
 their respecive type in //arrayOfTypes//.
 
 _property: ethers.utils.solidityKeccak256(arrayOfTypes, arrayOfValues) => string<[[datahexstring]]<32>>  @<utils-soliditykeccak256> @SRC<solidity:keccak256>
-Returns the KECCAK256 of the non-standard encoded //arrayOfValues// packed
+Returns the [KECCAK256](link-wiki-sha3) of the non-standard encoded //arrayOfValues// packed
 according to their respective type in //arrayOfTypes//.
 
 _property: ethers.utils.soliditySha256(arrayOfTypes, arrayOfValues) => string<[[datahexstring]]<32>>  @<utils-soliditysha256> @SRC<solidity:sha256>
-Returns the SHA2-256 of the non-standard encoded //arrayOfValues// packed
+Returns the [SHA2-256](link-wiki-sha2) of the non-standard encoded //arrayOfValues// packed
 according to their respective type in //arrayOfTypes//.
 
 

docs.wrm/api/utils/hdnode.wrm

@@ -0,0 +1,125 @@
+_section: HD Wallet
+
+TODO: Explain [BIP32](link-bip-32) [BIP-39](link-bip-39) and whatnot here...
+
+_subsection: Types
+
+_heading: Constants @<hdnode-defaultpath> @SRC<hdnode:defaultPath>
+
+_property: ethers.utils.defaultPath => "m/44'/60'/0'/0/0"
+The default path for Ethereum in an HD Wallet
+
+
+_heading: Mnemonic @<hdnode-mnemonic>
+
+_property: mnemonic.phrase => string
+The mnemonic phrase for this mnemonic. It is 12, 15, 18, 21 or 24 words long
+and separated by the whitespace specified by the ``locale``.
+
+_property: mnemonic.path => string
+The HD path for this mnemonic.
+
+_property: mnemonic.locale => string
+The language of the wordlist this mnemonic is using.
+
+
+_subsection: HDNode @<hdnode> @SRC<hdnode:class.HDNode>
+
+_heading: Creating Instances
+
+_property: ethers.HDNode.fromMnemonic(phrase [, password [, wordlist ] ]) => [[hdnode]]  @SRC<hdnode>
+Return the [[hdnode]] for //phrase// with the optional //password//
+and //wordlist//.
+
+_property: ethers.HDNode.fromSeed(aBytesLike) => [[hdnode]]  @SRC<hdnode>
+Return the [[hdnode]] for the seed //aBytesLike//.
+
+_property: ethers.HDNode.fromExtendedKey(extendedKey) => [[hdnode]]  @SRC<hdnode>
+Return the [[hdnode]] for the //extendedKey//. If //extendedKey// was
+neutered, the **HDNode** will only be able to compute addresses and not
+private keys.
+
+
+_heading: Properties
+
+_property: hdNode.privateKey => string<[[datahexstring]]<32>>
+The private key for this HDNode.
+
+_property: hdNode.publicKey => string<[[datahexstring]]<33>>
+The (compresses) public key for this HDNode.
+
+_property: hdNode.fingerprint => string<[[datahexstring]]<4>>
+The fingerprint is meant as an index to quickly match parent and
+children nodes together, however collisions may occur and software
+should verify matching nodes.
+
+Most developers will not need to use this.
+
+_property: hdNode.parentFingerprint => string<[[datahexstring]]<4>>
+The fingerprint of the parent node. See //fingerprint// for more
+details.
+
+Most developers will not need to use this.
+
+_property: hdNode.address => string<[[address]]>
+The address of this HDNode.
+
+_property: hdNode.mnemonic => [[hdnode-mnemonic]]
+The mnemonic of this HDNode, if known.
+
+_property: hdNode.path => string
+The path of this HDNode, if known. If the //mnemonic// is also known,
+this will match ``mnemonic.path``.
+
+_property: hdNode.chainCode => string<[[datahexstring]]<32>>
+The chain code is used as a non-secret private key which is then used
+with EC-multiply to provide the ability to derive addresses without
+the private key of child non-hardened nodes.
+
+Most developers will not need to use this.
+
+_property: hdNode.index => number
+The index of this HDNode. This will match the last component of
+the //path//.
+
+Most developers will not need to use this.
+
+_property: hdNode.depth => number
+The depth of this HDNode. This will match the number of components
+(less one, the ``m/``) of the //path//.
+
+Most developers will not need to use this.
+
+_property: hdNode.extendedKey => string
+A serialized string representation of this HDNode. Not all properties
+are included in the serialization, such as the mnemonic and path, so
+serializing and deserializing (using the ``fromExtendedKey`` class
+method) will result in reduced information.
+
+
+_heading: Methods
+
+_property: hdNode.neuter() => [[hdnode]] @SRC<hdnode>
+Return a new instance of //hdNode// with its private key removed
+but all otehr properties preserved. This ensures that the key
+can not leak the private key of itself or any derived children,
+but may still be used to compute the addresses of itself and
+any non-hardened children.
+
+_property: hdNode.derivePath(path) => [[hdnode]]  @SRC<hdnode>
+Return a new [[hdnode]] which is the child of //hdNode// found
+by deriving //path//.
+
+
+
+_subsection: Other Functions
+
+_property: ethers.utils.mnemonicToSeed(phrase [ , password]) => string<[[datahexstring]]<64>>  @SRC<hdnode>
+Convert a mnemonic phrase to a seed, according to [BIP-39](link-bip-39).
+
+_property: ethers.utils.mnemonicToEntropy(phrase [ , wordlist ]) => string<[[datahexstring]]> @SRC<hdnode>
+Convert a mnemonic phrase to its entropy, according to [BIP-39](link-bip-39).
+
+_property: ethers.utils.isValidMnemonic(phrase [ , wordlist ]) => boolean  @SRC<hdnode>
+Returns true if //phrase// is a valid mnemonic phrase, by
+testing the checksum.

docs.wrm/api/utils/index.wrm

@@ -1,18 +1,23 @@
-_title: Utilities
-
 _section: Utilities
 
 These utilities are used extensively within the library, but
 are also quite useful for application developers.
 
 _toc:
-    address
     abi
+    address
     bignumber
     bytes
     constants
     display-logic
+    encoding
     fixednumber
     hashing
+    hdnode
+    logger
+    properties
+    signing-key
     strings
     transactions
+    web
+    wordlists

docs.wrm/api/utils/logger.wrm

@@ -0,0 +1,208 @@
+_section: Logging @<logging>
+
+These are just a few simple logging utilities provided to simplify
+and standardize the error facilities across the Ethers library.
+
+The [[logger]] library has zero dependencies and is intentionally
+very light so it can be easily included in each library.
+
+The [Censorship](logger-censorship) functionality relies on one instance
+of the Ethers library being included. In large bundled packages or when
+``npm link`` is used, this may not be the case. If you require this
+functionality, ensure that your bundling is configured properly.
+
+
+_subsection: Logger @<logger> @SRC<logger:class.Logger>
+
+_property: new ethers.utils.Logger(version) @SRC<logger:constructor.Logger>
+Create a new logger which will include //version// in all errors thrown.
+
+_property: Logger.globalLogger() => [[logger]] @SRC<logger>
+Returns the singleton global logger.
+
+
+_heading: Logging Output
+
+_property: logger.debug(...args) => void @SRC<logger>
+Log debugging information.
+
+_property: logger.info(...args) => void @SRC<logger>
+Log generic information.
+
+_property: logger.warn(...args) => void @SRC<logger>
+Log warnings.
+
+
+_heading: Errors
+
+These functions honor the current [Censorship](logger-censorship) and help create
+a standard error model for detecting and processing errors within Ethers.
+
+_property: logger.makeError(message [ , code = UNKNOWN_ERROR [ , params ] ]) => Error @SRC<logger>
+Create an Error object with //message// and an optional //code// and
+additional //params// set. This is useful when an error is needed to be
+rejected instead of thrown.
+
+_property: logger.throwError(message [ , code = UNKNOWN_ERROR [ , params ] ]) => never @SRC<logger>
+Throw an Error with //message// and an optional //code// and
+additional //params// set.
+
+_property: logger.throwArgumentError(message, name, value) => never @SRC<logger>
+Throw an [INVALID_ARGUMENT](error-invalidargument) Error with //name// and //value//.
+
+
+_heading: Usage Validation
+
+There can be used to ensure various properties and actions are safe.
+
+_property: logger.checkAbstract(target, kind) => void @SRC<logger>
+Checks that //target// is not //kind// and performs the same operatons
+as ``checkNew``. This is useful for ensuring abstract classes are not
+being instantiated.
+
+_property: logger.checkArgumentCount(count, expectedCound [ , message) => void @SRC<logger>
+If //count// is not equal to //expectedCount//, throws a [MISSING_ARGUMENT](error-missingargument)
+or [UNEXPECTED_ARGUMENT](error-unexpectedargument) error.
+
+_property: logger.checkNew(target, kind) => void @SRC<logger>
+If //target// is not a valid ``this`` or ``target`` value, throw a
+[MISSING_NEW](error-missingnew) error. This is useful to ensure
+callers of a Class are using ``new``.
+
+_property: logger.checkNormalize(message) => void @SRC<logger>
+Check that the environment has a correctly functioning [[link-js-normalize]]. If not, a
+[UNSUPPORTED_OPERATION](error-unsupported) error is thrown.
+
+_property: logger.checkSafeUint53(value [, message ]) => void @SRC<logger>
+If //value// is not safe as a [JavaScript number](link-wiki-ieee754), throws a
+[NUMERIC_FAULT](error-numericfault) error.
+
+
+_heading: Censorship @<logger-censorship>
+
+_property: Logger.setCensorship(censor [ , permanent = false ]) => void @SRC<logger>
+Set error censorship, optionally preventing errors from being uncensored.
+
+In production applications, this prevents any error from leaking information
+by masking the message and values of errors.
+
+This can impact debugging, making it substantially more difficult.
+
+_property: Logger.setLogLevel(logLevel) => void @SRC<logger>
+Set the log level, to suppress logging output below a [particular log level](logger-levels).
+
+
+_subsection: Errors @<errors>
+
+Every error in Ethers has a ``code`` value, which is a string that will
+match one of the following error codes.
+
+
+_heading: Generic Error Codes
+
+_property: Logger.errors.NOT_IMPLEMENTED
+The operation is not implemented.
+
+_property: Logger.errors.SERVER_ERROR
+There was an error communicating with a server.
+
+_property: Logger.errors.TIMEOUT @<error-timeout>
+A timeout occurred.
+
+_property: Logger.errors.UNKNOWN_ERROR @<error-unknown>
+A generic unknown error.
+
+_property: Logger.errors.UNSUPPORTED_OPERATION @<error-unsupported>
+The operation is not supported.
+
+
+_heading: Safety Error Codes
+
+_property: Logger.errors.BUFFER_OVERRUN
+The amount of data needed is more than the amount of data required,
+which would cause the data buffer to read past its end.
+
+_property: Logger.errors.NUMERIC_FAULT @<error-numericfault>
+There was an invalid operation done on numeric values.
+
+Common cases of this occur when there is [[link-wiki-overflow]],
+[[link-wiki-underflow]] in fixed numeric types or division by zero.
+
+
+_heading: Usage Error Codes
+
+_property: Logger.errors.INVALID_ARGUMENT @<error-invalidargument>
+The type or value of an argument is invalid. This will generally also
+include the ``name`` and ``value`` of the argument. Any function which
+accepts sensitive data (such as a private key) will include the string
+``[\[REDACTED]\]`` instead of the value passed in.
+
+_property: Logger.errors.MISSING_ARGUMENT @<error-missingargument>
+An expected parameter was not specified.
+
+_property: Logger.errors.MISSING_NEW @<error-missingnew>
+An object is a Class, but is now being called with ``new``.
+
+_property: Logger.errors.UNEXPECTED_ARGUMENT @<error-unexpectedargument>
+Too many parameters we passed into a function.
+
+
+_heading: Ethereum Error Codes
+
+_property: Logger.errors.CALL_EXCEPTION
+An attempt to call a blockchain contract (getter) resulted in a
+revert or other error.
+
+_property: Logger.errors.INSUFFICIENT_FUNDS
+The account is attempting to make a transaction which costs more than is
+available.
+
+A sending account must have enough ether to pay for the value, the gas limit
+(at the gas price) as well as the intrinsic cost of data. The intrinsic cost
+of data is 4 gas for each zero byte and 68 gas for each non-zero byte.
+
+_property: Logger.errors.NETWORK_ERROR
+An Ethereum network validation error, such as an invalid chain ID.
+
+_property: Logger.errors.NONCE_EXPIRED
+The nonce being specified has already been used in a mined transaction.
+
+_property: Logger.errors.REPLACEMENT_UNDERPRICED
+When replacing a transaction, by using a nonce which has already been sent to
+the network, but which has not been mined yet the new transaction must specify
+a higher gas price.
+
+This error occurs when the gas price is insufficient to //bribe// the transaction
+pool to prefer the new transaction over the old one. Generally, the new gas price
+should be about 50% + 1 wei more, so if a gas price of 10 gwei was used, the
+replacement should be 15.000000001 gwei.
+
+_property: Logger.errors.UNPREDICTABLE_GAS_LIMIT
+When estimating the required amount of gas for a transaction, a node is queried for
+its best guess.
+
+If a node is unable (or unwilling) to predict the cost, this error occurs.
+
+The best remedy for this situation is to specify a gas limit in the transaction
+manually.
+
+This error can also indicate that the transaction is expected to fail regardless,
+if for example an account with no tokens is attempting to send a token.
+
+
+_subsection: Log Levels @<logger-levels>
+
+_property: Logger.levels.DEBUG
+Log all output, including debugging information.
+
+_property: Logger.levels.INFO
+Only log output for infomational, warnings and errors.
+
+_property: Logger.levels.WARNING
+Only log output for warnings and errors.
+
+_property: Logger.levels.ERROR
+Only log output for errors.
+
+_property: Logger.levels.OFF
+Do not output any logs.

docs.wrm/api/utils/properties.wrm

@@ -1,7 +1,9 @@
-_title: Property Utilities
-
 _section: Property Utilities
 
-_property: utils.resolveProperties(anObject) => Promise<any> @<utils-resolveproperties> @SRC<properties>
-
+_property: ethers.utils.checkPropertoes() => void
 
+_property: ethers.utils.deepCopy(anObject) => any
+_property: ethers.utils.defineReadOnly(anObject, name, value) => void
+_property: ethers.utils.getStatic(aConstructor, key) => any
+_property: ethers.utils.resolveProperties(anObject) => Promise<any> @<utils-resolveproperties> @SRC<properties>
+_property: ethers.utils.shallowCopy(anObject) => any

docs.wrm/api/utils/signing-key.wrm

@@ -1,7 +1,35 @@
-_title: Signing Keys
+_section: Signing Key @<utils-signingkey>
 
-_section: Signing Key
+_property: new ethers.utils.SigningKey(privateKey)
+Create a new SigningKey for //privateKey//.
 
+_property: signingKey.privateKey => string<[[datahexstring]]<32>>
+The private key for this Signing Key.
+
+_property: signingKey.publicKey => string<[[datahexstring]]<65>>
+The uncompressed public key for this Signing Key. It will always be
+65 bytes (130 nibbles) and begine with ``0x04``.
+
+_property: signingKey.compressedPublicKey => string<[[datahexstring]]<33>>
+The compressed public key for this Signing Key. It will always be
+33 bytes (66 nibbles) and begine with either ``0x02`` or ``0x03``.
+
+_property: signingKey.signDisgest(digest) => [[signature]]
+Sign the //digest// and return the signature.
+
+_property: signingKey.computeSharedSecret(otherKey) => string<[[datahexstring]]<32>>
+Compute the ECDH shared secret with //otherKey//. The //otherKey// may be
+either a public key or a private key, but generally will be a public key from
+another party.
+
+It is best practice that each party computes the hash of this before using it
+as a symmetric key.
+
+_property: SigningKey.isSigningKey(anObject) => boolean
+Returns true if //anObject// is a SigningKey.
+
+
+_subsection: Other Functions
 
 _property: ethers.utils.verifyMessage(message, signature) => string<[[address]]>  @<utils-verifymessage> @SRC<wallet>
 Returns the address that signed //message// producing //signature//. The
@@ -10,3 +38,10 @@ in which case it will be normalized to compute the `recoveryParam` which
 will then be used to compute the address; this allows systems which use
 the v to encode additional data (such as [EIP-155](link-eip-155))
 to be used since the v parameter is still completely non-ambiguous.
+
+_property: ethers.utils.recocverPublicKey(digest, signature) => string<[[datahexstring]]<65>> @<utils-recoverpublickey>
+
+_property: ethers.utils.computePublicKey(key [, compressed = false ]) => string<[[datahexstring]]> @<utils-computepublickey>
+Computes the public key of //key//, optionally compressing it. The //key//
+can be any form of public key (compressed or uncompressed) or a private
+key.

docs.wrm/api/utils/strings.wrm

@@ -1,5 +1,3 @@
-_title: Strings
-
 _section: Strings
 
 Tra la la

docs.wrm/api/utils/transactions.wrm

@@ -1,53 +1,98 @@
-_title: Transactions
-
 _section: Transactions @<utils-transactions>
 
 _subsection: Types
 
 _heading: UnsignedTransaction @<types-unsignedtransaction>
-An unsigned transaction represents a transaction that has not been signed.
+An unsigned transaction represents a transaction that has not been
+signed and its values are flexible as long as they are not ambiguous.
 
 _property: unsignedTransaction.to => string<[Address](address)>
+The addres this transaction is to.
 
 _property: unsignedTransaction.nonce => number
+The nonce of this transaction.
 
-_property: unsignedTransaction.gasLimit => [[bignumber]]
+_property: unsignedTransaction.gasLimit => [[bignumberish]]
+The gas limit for this transaction.
 
-_property: unsignedTransaction.gasPrice => [[bignumber]]
+_property: unsignedTransaction.gasPrice => [[bignumberish]]
+The gas price for this transaction.
 
 _property: unsignedTransaction.data => [[byteslike]]
+The data for this transaction.
 
-_property: unsignedTransaction.value => [[bignumber]]
+_property: unsignedTransaction.value => [[bignumberish]]
+The value (in wei) for this transaction.
 
 _property: unsignedTransaction.chainId => number
+The chain ID for this transaction. If the chain ID is 0 or null,
+then [[link-eip-155]] is disabled and legacy signing is
+used, unless overridden in a signature.
 
 
 _heading: Transaction @<types-transaction>
 A generic object to represent a transaction.
 
-_property: unsignedTransaction.hash => string<[[datahexstring]]<32>>
+_property: transaction.hash => string<[[datahexstring]]<32>>
+The transaction hash, which can be used as an identifier for
+//transaction//. This is the keccak256 of the serialized RLP encoded
+representation of //transaction//.
 
 _property: unsignedTransaction.to => string<[Address](address)>
+The address //transaction// is to.
 
-_property: unsignedTransaction.from => string<[Address](address)>
+_property: transaction.from => string<[Address](address)>
+The address //transaction// is from.
 
-_property: unsignedTransaction.nonce => number
+_property: transaction.nonce => number
+The nonce for //transaction//. Each transaction sent to the network
+from an account includes this, which ensures the order and
+non-replayability of a transaction. This must be equal to the current
+number of transactions ever sent to the network by the **from** address.
 
-_property: unsignedTransaction.gasLimit => [[bignumber]]
+_property: transaction.gasLimit => [[bignumber]]
+The gas limit for //transaction//. An account must have enough ether to
+cover the gas (at the specified **gasPrice**). Any unused gas is
+refunded at the end of the transaction, and if there is insufficient gas
+to complete execution, the effects of the trasaction are reverted, but
+the gas is **fully consumed** and an out-of-gas error occurs.
 
-_property: unsignedTransaction.gasPrice => [[bignumber]]
+_property: transaction.gasPrice => [[bignumber]]
+The price (in wei) per unit of gas for //transaction//.
 
-_property: unsignedTransaction.data => [[byteslike]]
+_property: transaction.data => [[byteslike]]
+The data for //transaction//. In a contract this is the call data.
 
-_property: unsignedTransaction.value => [[bignumber]]
+_property: transaction.value => [[bignumber]]
+The value (in wei) for //transaction//.
 
-_property: unsignedTransaction.chainId => number
+_property: transaction.chainId => number
+The chain ID for //transaction//. This is used as part of
+[[link-eip-155]] to prevent replay attacks on different
+networks.
 
-_property: unsignedTransaction.r => [[byteslike]]
+For example, if a transaction was made on ropsten with an account
+also used on homestead, it would be possible for a transaction
+signed on ropsten to be executed on homestead, which is likely
+unintended.
 
-_property: unsignedTransaction.s => [[byteslike]]
+There are situations where replay may be desired, however these
+are very rare and it is almost always recommended to specify the
+chain ID.
 
-_property: unsignedTransaction.v => number
+_property: transaction.r => string<[[datahexstring]]<32>>
+The r portion of the elliptic curve signatures for //transaction//.
+This is more accurately, the x coordinate of the point r (from
+which the y can be computed, along with v).
+
+_property: transaction.s => string<[[datahexstring]]<32>>
+The s portion of the elliptic curve signatures for //transaction//.
+
+_property: transaction.v => number
+The v portion of the elliptic curve signatures for //transaction//.
+This is used to refine which of the two possible points a given
+x-coordinate can have, and in [[link-eip-155]] is additionally
+used to encode the chain ID into the serialized transaction.
 
 
 _subsection: Functions
@@ -64,9 +109,18 @@ Computes the address that signed //digest// to get //aSignatureLike// using the
 ecrecover algorithm.
 
 _property: ethers.utils.serialize(transaction [ , signature ]) => string<[[datahexstring]]>  @<utils-serialize> @SRC<transactions>
-Computes the serialized //transaction/, optionally signed with //signature//. If
-signature is not presented, the unsigned serialized transaction is returned, which can
-be used to compute the hash necessary to sign.
+Computes the serialized //transaction//, optionally serialized with
+the a //signature//. If //signature// is not present, the unsigned
+serialized transaction is returned, which can be used to compute the
+hash necessary to sign.
 
-This function uses EIP-155 if a chainId is provided, otherwise legacy serialization is
-used. It is **highly** recommended to always specify a //chainId//.
+This function uses [[link-eip-155]] if a chainId is provided,
+otherwise legacy serialization is used. It is **highly** recommended
+to always specify a //chainId//.
+
+If //signature// includes a chain ID (explicitly or implicitly by using an
+[[link-eip-155]] ``v`` or ``_vs``) it will be used to compute the
+chain ID.
+
+If there is a mismatch between the chain ID of //transaction// and //signature//
+an error is thrown.

docs.wrm/api/utils/web.wrm

@@ -0,0 +1,64 @@
+_section: Web Utilities
+
+
+_property: ethers.utils.fetchJson(urlOrConnectionInfo [, json [ , processFunc ] ]) => Promise<any> @<web-fetchjson>
+Fetch and parse the JSON content from //urlOrConnectionInfo//, with the
+optiona body //json// and optionally processing the result with //processFun//
+before returning it.
+
+_property: ethers.utils.poll(pollFunc [, options ]) => Promise<any> @<web-poll>
+Repeatedly call pollFunc using the [[web-polloptions]] until it returns a
+value other than undefined.
+
+
+_heading: Connection Info @<web-connectioninfo>
+
+_property: connection.url => string
+The URL to connect to.
+
+_property: connection.user => string
+The username to use for [[link-wiki-basicauth]].
+The default is null (i.e. do not use basic authentication)
+
+_property: connection.password => string
+The password to use for [[link-wiki-basicauth]].
+The default is null (i.e. do not use basic authentication)
+
+_property: connection.allowInsecureAuthentication => boolean
+Allow [[link-wiki-basicauth]] over non-secure HTTP. The default is false.
+
+_property: connection.timeout => number
+How long to wait before rejecting with a //timeout// error.
+
+_property: connection.headers => { [ key: string]: string }
+Additional headers to include in the connection.
+
+
+_heading: Poll Options @<web-polloptions>
+
+_property: options.timeout => number
+The amount of time allowed to ellapse before triggering a timeout
+error.
+
+_property: options.floor => number
+The minimum time limit to allow for [[link-wiki-backoff]].
+
+The default is 0s.
+
+_property: options.ceiling => number
+The maximum time limit to allow for [[link-wiki-backoff]].
+
+The default is 10s.
+
+_property: options.interval => number
+The interval used during [[link-wiki-backoff]] calculation.
+
+The default is 250ms.
+
+_property: options.retryLimit => number
+The number of times to retry in the event of an error or //undefined// is
+returned.
+
+_property: options.onceBlock => [[provider]]
+If this is specified, the polling will wait on new blocks from
+//provider// before attempting the //pollFunc// again.

docs.wrm/api/utils/wordlists.wrm

@@ -0,0 +1,58 @@
+_section: Wordlists @<wordlists>
+
+_subsection: Wordlist @<wordlist>
+
+_property: wordlist.locale => string
+The locale for this wordlist.
+
+_property: wordlist.getWord(index) => string
+Returns the word at //index//.
+
+_property: wordlist.getWordIndex(word) => number
+Returns the index of //word// within the wordlist.
+
+_property: wordlist.split(mnemonic) => Array<string>
+Returns the mnemonic split into each individual word, according to a
+locale's valid whitespace character set.
+
+_property: wordlist.join(words) => string
+Returns the mnemonic by joining //words// together using the
+whitespace that is standard for the locale.
+
+_property: Wordlist.check(wordlists) => string<[[datahexstring]]<32>>
+Checks that all words map both directions correctly and return the
+hash of the lists. Sub-classes should use this to validate the wordlist
+is correct against the official wordlist hash.
+
+_property: Wordlist.register(wordlist [ , name ]) => void
+Register a wordlist with the list of wordlists, optionally overriding
+the registered //name//.
+
+_subsection: Languages @<wordlist-languages>
+
+_property: ethers.wordlists.cz => Wordlist
+The Czech [[wordlist]].
+
+_property: ethers.wordlists.en => Wordlist
+The English [[wordlist]].
+
+_property: ethers.wordlists.es => Wordlist
+The Spanish [[wordlist]].
+
+_property: ethers.wordlists.fr => Wordlist
+The French [[wordlist]].
+
+_property: ethers.wordlists.it => Wordlist
+The Italian [[wordlist]].
+
+_property: ethers.wordlists.ja => Wordlist
+The Japanese [[wordlist]].
+
+_property: ethers.wordlists.ko => Wordlist
+The Korean [[wordlist]].
+
+_property: ethers.wordlists.zh_cn => Wordlist
+The Simplified Chinese [[wordlist]].
+
+_property: ethers.wordlists.zh_tw => Wordlist
+The Traditional Chinese [[wordlist]].

docs.wrm/cli/asm-examples-assemble.txt

@@ -0,0 +1,11 @@
+/home/ethers> ethers-asm SimpleStore.asm
+0x602a6000556044601160003960446000f334601e5760003560e01c80632096525514602457806355241077146030575b60006000fd5b60005460005260206000f35b6024361415601e5760043560005560006000f3
+
+# Piping in ASM source code
+/home/ethers> cat SimpleStore.asm | ethers-asm
+# Same as above
+
+# Setting a define which the ASM file checks and adds a checksum
+/home/ethers> ethers-asm --define checksum SimpleStore.asm
+0x602a6000556065601160003960656000f334601e5760003560e01c80632096525514602457806355241077146030575b60006000fd5b60005460005260206000f35b6024361415601e5760043560005560006000f37f10358310d664c9aeb4bf4ce7a10a6a03176bd23194c8ccbd3160a6dac90774d6
+

docs.wrm/cli/asm-examples-disassemble.txt

@@ -0,0 +1,57 @@
+/home/ethers> ethers-asm --disassemble SimpleStore.bin
+0000 : 0x2a                                                               ; #1 
+0002 : 0x00                                                               ; #1 
+0004 : SSTORE
+0005 : 0x44                                                               ; #1 
+0007 : 0x11                                                               ; #1 
+0009 : 0x00                                                               ; #1 
+000b : CODECOPY
+000c : 0x44                                                               ; #1 
+000e : 0x00                                                               ; #1 
+0010 : RETURN
+0011 : CALLVALUE
+0012 : 0x1e                                                               ; #1 
+0014 : JUMPI
+0015 : 0x00                                                               ; #1 
+0017 : CALLDATALOAD
+0018 : 0xe0                                                               ; #1 
+001a : SHR
+001b : DUP1
+001c : 0x20965255                                                         ; #4 
+0021 : EQ
+0022 : 0x24                                                               ; #1 
+0024 : JUMPI
+0025 : DUP1
+0026 : 0x55241077                                                         ; #4 
+002b : EQ
+002c : 0x30                                                               ; #1 
+002e : JUMPI
+002f*: JUMPDEST
+0030 : 0x00                                                               ; #1 
+0032 : 0x00                                                               ; #1 
+0034 : REVERT
+0035*: JUMPDEST
+0036 : 0x00                                                               ; #1 
+0038 : SLOAD
+0039 : 0x00                                                               ; #1 
+003b : MSTORE
+003c : 0x20                                                               ; #1 
+003e : 0x00                                                               ; #1 
+0040 : RETURN
+0041*: JUMPDEST
+0042 : 0x24                                                               ; #1 
+0044 : CALLDATASIZE
+0045 : EQ
+0046 : ISZERO
+0047 : 0x1e                                                               ; #1 
+0049 : JUMPI
+004a : 0x04                                                               ; #1 
+004c : CALLDATALOAD
+004d : 0x00                                                               ; #1 
+004f : SSTORE
+0050 : 0x00                                                               ; #1 
+0052 : 0x00                                                               ; #1 
+0054 : RETURN
+
+/home/ethers> cat SimpleStore.bin | ethers-asm --disassemble 
+# Same as above

docs.wrm/cli/asm-help.txt

@@ -2,8 +2,11 @@ Usage:
    ethers-asm [ FILENAME ] [ OPTIONS ]
 
 OPTIONS
-  --disassemble               Disassemble input bytecode
   --define KEY=VALUE          provide assembler defines
+  --disassemble               Disassemble input bytecode
+  --ignore-warnings           Ignore warnings
+  --pic                       generate position independent code
+  --target LABEL              output LABEL bytecode (default: _)
 
 OTHER OPTIONS
   --debug                     Show stack traces for errors

docs.wrm/cli/asm-simplestore-asm.txt

@@ -0,0 +1,48 @@
+; SimpleStore (uint)
+
+; Set the inital value of 42
+sstore(0, 42)
+
+; Init code to deploy myContract
+codecopy(0, $myContract, #myContract)
+return(0, #myContract)
+
+@myContract {
+    ; Non-payable
+    jumpi($error, callvalue)
+
+    ; Get the Sighash
+    shr({{= 256 - 32 }}, calldataload(0))
+
+    ; getValue()
+    dup1
+    {{= sighash("getValue()") }}
+    jumpi($getValue, eq)
+
+    ; setValue(uint)
+    dup1
+    {{= sighash("setValue(uint)") }}
+    jumpi($setValue, eq)
+
+    ; No matching signature
+    @error:
+        revert(0, 0)
+
+    @getValue:
+        mstore(0, sload(0))
+        return (0, 32)
+
+    @setValue:
+        ; Make sure we have exactly a uint
+        jumpi($error, iszero(eq(calldatasize, 36)))
+
+        ; Store the value
+        sstore(0, calldataload(4))
+        return (0, 0)
+
+    ; There is no *need* for the PUSH32, it just makes
+    ; decompiled code look nicer
+    @checksum[
+        {{= (defines.checksum ? concat([ Opcode.from("PUSH32"), id(myContract.source) ]): "0x") }}
+    ]
+}

docs.wrm/cli/asm-simplestore-bin.txt

@@ -0,0 +1,3 @@
+0x602a6000556044601160003960446000f334601e5760003560e01c8063209652
+0x5514602457806355241077146030575b60006000fd5b60005460005260206000
+0xf35b6024361415601e5760043560005560006000f3

docs.wrm/cli/asm.wrm

@@ -1,17 +1,81 @@
-_title: Assembler
+_section: Assembler @<cli-asm>
 
-_section: Assembler
+The assembler Command-Line utility allows you to assemble the
+[Ethers ASM Dialect](asm-dialect) into deployable EVM bytecode
+and disassemle EVM bytecode into human-readable mnemonics.
 
-The assembler Command-Line utility allows you to assemble EVM asm files
-into deployable bytecode and disassemle EVM bytecode into human-readable
-mnemonics.
 
 _subsection: Help
 
 _code: asm-help.txt
 
-_subsection: Examples
 
-TODO examples
+_subsection: Example Input Files
 
+_definition: **SimpleStore.asm**
+
+_code: asm-simplestore-asm.txt
+
+_definition: **SimpleStore.bin**
+
+_code: asm-simplestore-bin.txt
+
+_note: Note: Bytecode File Syntax
+A bin file may be made up of multiple blocks of bytecode, each may
+optionally begin with a ``0x`` prefix, all of which **must** be of
+even length (since bytes are required, with 2 nibbles per byte)
+
+All whitespace is ignored.
+
+_subsection: Assembler Examples
+
+The assembler converts an [Ethers ASM Dialect](asm-dialect) into
+bytecode by running multiple passes of an assemble stage, each pass
+more closely approximating the final result.
+
+This allows small portions of the bytecode to be massaged and tweaked
+until the bytecode stablizes. This allows for more compact jump
+destinations and for code to be include more advanced meta-programming
+techniques.
+
+_code: asm-examples-assemble.txt
+
+_heading: Options
+
+_definition: **-\-define KEY=VALUE** //or// **-\-define FLAG**
+This allows key/value pairs (where the value is a string) and
+flags (which the value is ``true``) to be passed along to the
+assembler, which can be accessed in
+[Scripting Blocks](asm-dialect-scripting), such as ``{{= defined.someKey }}``.
+
+_definition: **-\-ignore-warnings**
+By default any warning will be treated like an error. This enabled
+by-passing warnings.
+
+_definition: **-\-pic**
+When a program is assembled, the labels are usually given as an
+absolute byte position, which can be jumped to for loops and
+control flow. This means that a program must be installed at a specific
+location.
+
+Byt specifying the **Position Independent Code** flag, code
+will be generated in a way such that all offsets are relative, allowing
+the program to be moved without any impact to its logic.
+
+This does incur an additional gsas cost of 8 gas per offset access though.
+
+_definition: **-\-target LABEL**
+All programs have a root scope named ``_`` which is by default
+assembled. This option allows another labelled target (either a
+[[asm-dialect-scope]] or a [[asm-dialect-datasegment]] to be
+assembled instead. The entire program is still assembled per usual,
+so this only impacts which part of the program is output.
+
+_subsection: Disassembler Examples
+
+A disassembled program shows offsets and mnemonics for the given
+bytecode. This format may change in the future to be more
+human-readable.
+
+_code: asm-examples-disassemble.txt
 

docs.wrm/cli/ens.wrm

@@ -1,6 +1,4 @@
-_title: ENS
-
-_section: ENS
+_section: Ethereum Naming Service @NAV<ENS>
 
 _subsection: Help
 

docs.wrm/cli/ethers.wrm

@@ -1,5 +1,3 @@
-_title: Sandbox Utility
-
 _section: Sandbox Utility
 
 The sandbox utility provides a simple way to use the most common

docs.wrm/cli/index.wrm

@@ -1,5 +1,3 @@
-_title: Command Line Interfaces
-
 _section: Command Line Interfaces
 
 _toc:

docs.wrm/cli/plugin.wrm

@@ -1,6 +1,4 @@
-_title: Making Your Own
-
-_section: Making Your Own
+_section: Making Your Own @<cli-diy>
 
 The //cli// library is meant to make it easy to create command
 line utilities of your own.

docs.wrm/cli/typescript.wrm

@@ -1,5 +1,3 @@
-_title: TypeScript
-
 _section: TypeScript
 
 _subsection: Help

docs.wrm/concepts/events.wrm

@@ -1,5 +1,3 @@
-_title: Events
-
 _section: Events
 
 Explain how topics and such work

docs.wrm/concepts/gas.wrm

@@ -1,5 +1,3 @@
-_title: Gas
-
 _section: Gas @<gas>
 
 Explain attack vectors

docs.wrm/concepts/index.wrm

@@ -1,5 +1,3 @@
-_title: Concepts
-
 _section: Concepts
 
 This is a very breif overview of some aspects of //Ethereum//

docs.wrm/config.js

@@ -100,12 +100,11 @@ const getSourceUrl = (function(path, include, exclude) {
             if (!def.filename.match(pathCheck)) { return; }
             def.defs.forEach((d) => {
                 if (!d.name.match(match)) { return; }
-                result.push({ filename: def.filename, lineNo: d.lineNo });
+                result.push({ filename: def.filename, lineNo: d.lineNo, name: d.name });
             });
         });
-
         if (result.length > 1) {
-            throw new Error(`Amibguous TypeScript link: ${ key } in [ ${ result.map((r) => JSON.stringify(r.filename + ":" + r.lineNo)).join(", ") }]`);
+            throw new Error(`Ambiguous TypeScript link: ${ key } in [ ${ result.map((r) => JSON.stringify(r.filename + ":" + r.lineNo + "@" + r.name)).join(", ") }]`);
         } else if (result.length === 0) {
             throw new Error(`No matching TypeScript link: ${ key }`);
         }
@@ -142,6 +141,7 @@ module.exports = {
       "link-metamask": "https:/\/metamask.io/",
       "link-parity": "https:/\/www.parity.io",
       "link-rtd": "https:/\/github.com/readthedocs/sphinx_rtd_theme",
+      "link-solidity": { name: "Solidity" , url: "https:/\/solidity.readthedocs.io/en/v0.6.2/" },
       "link-sphinx": "https:/\/www.sphinx-doc.org/",
 
       "link-legacy-docs3": "https:/\/docs.ethers.io/ethers.js/v3.0/html/",
@@ -158,6 +158,7 @@ module.exports = {
       "link-jsonrpc": "https:/\/github.com/ethereum/wiki/wiki/JSON-RPC",
       "link-mit": "https:/\/en.m.wikipedia.org/wiki/MIT_License",
       "link-namehash": "https:/\/docs.ens.domains/contract-api-reference/name-processing#hashing-names",
+      "link-rlp": { name: "Recursive Length Prefix", url: "https:/\/github.com/ethereum/wiki/wiki/RLP" },
 
       "link-ethersio": "https:/\/ethers.io/",
       "link-ethers-docs": "https:/\/docs.ethers.io/",
@@ -165,18 +166,29 @@ module.exports = {
       "link-ethers-npm": "https:/\/www.npmjs.com/search?q=%40ethersproject%2F",
       "link-ethers-asm-grammar": "https:/\/github.com/ethers-io/ethers.js/blob/ethers-v5-beta/packages/asm/grammar.jison",
 
-      "link-eip-155": "https:/\/eips.ethereum.org/EIPS/eip-155",
+      "link-eip-155": { name: "EIP-155", url: "https:/\/eips.ethereum.org/EIPS/eip-155" },
+      "link-eip-191": { name: "EIP-191", url: "https:/\/eips.ethereum.org/EIPS/eip-191" },
       "link-eip-609": "https:/\/eips.ethereum.org/EIPS/eip-609",
       "link-eip-1014": "https:/\/eips.ethereum.org/EIPS/eip-1014",
       "link-eip-2098": "https:/\/eips.ethereum.org/EIPS/eip-2098",
+      "link-bip-39": "https://en.bitcoin.it/wiki/BIP_0039",
+      "link-bip-32": "https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki",
+
+      "link-npm-elliptic": { name: "elliptic", url: "https:/\/www.npmjs.com/package/elliptic" },
+      "link-npm-bnjs": { name: "BN.js", url: "https:/\/www.npmjs.com/package/bn.js" },
+      "link-npm-query-bignumber": "https:/\/www.npmjs.com/search?q=bignumber",
 
       "link-js-array": "https:/\/developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array",
       "link-js-bigint": "https:/\/developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt",
+      "link-js-normalize": { name: "String.normalize", url: "https:/\/developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/normalize" },
+      "link-js-maxsafe": "https:/\/developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/MAX_SAFE_INTEGER#Description",
       "link-js-typedarray": "https:/\/developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray",
 
       "link-ricmoo-humanreadableabi": "https:/\/blog.ricmoo.com/human-readable-contract-abis-in-ethers-js-141902f4d917",
 
-      "link-wiki-bloomfilter": "https:/\/en.wikipedia.org/wiki/Bloom_filter",
+      "link-wiki-basicauth": { name: "Basic Authentication", url: "https:/\/en.wikipedia.org/wiki/Basic_access_authentication" },
+      "link-wiki-backoff": { name: "Exponential Backoff", url: "https:/\/en.wikipedia.org/wiki/Exponential_backoff" },
+      "link-wiki-bloomfilter": { name: "Bloom Filter", url: "https:/\/en.wikipedia.org/wiki/Bloom_filter" },
       "link-wiki-cryptographichash": "https:/\/en.wikipedia.org/wiki/Cryptographic_hash_function",
       "link-wiki-homoglyph": "https:/\/en.wikipedia.org/wiki/IDN_homograph_attack",
       "link-wiki-hmac": "https:/\/en.wikipedia.org/wiki/HMAC",
@@ -190,6 +202,8 @@ module.exports = {
       "link-wiki-utf8-replacement": "https:/\/en.wikipedia.org/wiki/Specials_%28Unicode_block%29#Replacement_character",
       "link-wiki-scrypt": "https:/\/en.wikipedia.org/wiki/Scrypt",
       "link-wiki-sha3": "https:/\/en.wikipedia.org/wiki/SHA-3",
-      
+      "link-wiki-shuffle": { name: "Fisher-Yates Shuffle", url: "https:/\/en.wikipedia.org/wiki/Fisher-Yates_shuffle" },
+      "link-wiki-overflow": { name: "overflow", url: "https:/\/en.wikipedia.org/wiki/Integer_overflow" },
+      "link-wiki-underflow": { name: "arithmetic underflow", url: "https:/\/en.wikipedia.org/wiki/Arithmetic_underflow" },
   }
 };

docs.wrm/contributing.wrm

@@ -1,5 +1,3 @@
-_title: Contributing and Hacking
-
 _section: Contributing and Hacking
 
 The ethers.js library is something that I've written out of necessity,

docs.wrm/cookbook/index.wrm

@@ -1,5 +1,3 @@
-_title: Cookbook
-
 _section: Cookbook
 
 Cooking...

docs.wrm/documentation/index.wrm

@@ -1,5 +1,3 @@
-_title: Flatworm Docs
-
 _section: Flatworm Docs
 
 The //Flatworm Docs// rendering script is designed to be **very**
@@ -75,7 +73,7 @@ a //definition//, the bodies are indented, so a //null// can be
 used to reset the indentation.
 
 
-_heading: Examples
+_heading: Examples @<>
 
 _code: examples.txt
 
@@ -110,6 +108,16 @@ This extended directive function is available for:
 - _subsetion
 - _heading
 
+
+_heading: @NAV\<text>
+
+Sets the name in the breadcrumbs when not the current node.
+
+This extended directive function is available for:
+
+- _section
+
+
 _heading: @SRC\<text>
 
 Calls the configuration ``getSourceUrl(text, VALUE)`` to get a URL which

docs.wrm/getting-started.wrm

@@ -1,5 +1,3 @@
-_title: Getting Started
-
 _section: Getting Started
 
 

docs.wrm/hacking.wrm

@@ -1,5 +1,3 @@
-_title: Hacking
-
 _section: Hacking
 
 Things to keep in mind:

docs.wrm/index.wrm

@@ -1,6 +1,6 @@
-_title: Documentation
+_section: Documentation
 
-_section: What is ethers?
+_subsection: What is Ethers?
 
 The ethers.js library aims to be a complete and compact library for
 interacting with the Ethereum Blockchain and its ecosystem. It was

docs.wrm/license.wrm

@@ -1,7 +1,4 @@
-_title: License and Copyright
-
-
-_section: License and Copyright
+_section: License and Copyright  @<license>
 
 The ethers library (including all dependencies) are available
 under the [MIT License](link-mit), which permits a wide variety

docs.wrm/migration/ethers-v4/bignumber-creating.txt

@@ -0,0 +1,8 @@
+// v4
+new ethers.utils.BigNumber(someValue)
+ethers.utils.bigNumberify(someValue);
+
+// v5
+// - Constructor is private
+// - Removed `bigNumberify`
+ethers.BigNumber.from(someValue)

docs.wrm/migration/ethers-v4/bignumber-namespace.txt

@@ -0,0 +1,7 @@
+// v4
+ethers.utils.BigNumber
+ethers.utils.BigNumberish
+
+// v5
+ethers.BigNumber
+ethers.BigNumberish

docs.wrm/migration/ethers-v4/contracts.txt

@@ -0,0 +1 @@
+TODO

docs.wrm/migration/ethers-v4/errors.txt

@@ -0,0 +1,29 @@
+// v4
+ethers.errors.UNKNOWN_ERROR
+ethers.errors.*
+
+errors.setCensorship(censorship, permanent)
+errors.setLogLevel(logLevel)
+
+errors.checkArgumentCount(count, expectedCount, suffix)
+errors.checkNew(self, kind)
+errors.checkNormalize()
+errors.throwError(message, code, params)
+errors.warn(...)
+errors.info(...)
+
+// v5
+ethers.utils.Logger.errors.UNKNOWN_ERROR
+ethers.utils.Logger.errors.*
+
+Logger.setCensorship(censorship, permanent)
+Logger.setLogLevel(logLevel)
+
+const logger = new ethers.utils.Logger(version);
+logger.checkArgumentCount(count, expectedCount, suffix)
+logger.checkNew(self, kind)
+logger.checkNormalize()
+logger.throwError(message, code, params)
+logger.warn(...)
+logger.info(...)
+

docs.wrm/migration/ethers-v4/index.wrm

@@ -0,0 +1,62 @@
+_section: Migration: From Ethers v4  @<migration-v4>
+
+_subsection: BigNumber
+
+_heading: Namespace
+Since [[bignumber]] is used quite frequently, it has been moved to
+the top level of the umbrella package.
+_code: bignumber-namespace.txt
+
+_heading: Creating Instances
+The ``bigNumberify`` method was always preferred over the constructor
+since it could short-circuit an object instantiation for [[bignumber]
+objects (since they are immutable). This has been moved to a static
+``from`` class method.
+_code: bignumber-creating.txt
+
+
+_subsection: Contracts
+_code: contracts.txt
+
+_subsection: Errors
+
+_heading: Namespace
+All errors now belong to the [[logger]] class and the related functions
+have been moved to [[logger]] instances, which can include a per-package
+version string.
+
+Global error fucntions have been moved [[logger]] class methods.
+_code: errors.txt
+
+
+_subsection: Interface
+The [[abi-interface]] object has undergone the most dramatic changes.
+
+It is no longer a meta-class and now has methods that simplify handling
+contract interface operations without the need for object inspection and
+special edge cases.
+
+_heading: Functions
+_code: interface-functions.txt
+
+_heading: Events
+_code: interface-events.txt
+
+_heading: Inspection
+Interrogating properties about a function or event can now (mostly) be
+done directly on the [[abi-fragment]] object.
+_code: interface-inspection.txt
+
+
+_subsection: Utilities
+
+_heading: Renaming
+_code: utils.txt
+
+
+_subsection: Wallet
+
+_heading: Mnemonic Phrases
+The **mnemonic** phrase and related properties have been merged into
+a single ``mnemonic`` object, which also now includes the ``locale``.
+_code: wallet.txt

docs.wrm/migration/ethers-v4/interface-events.txt

@@ -0,0 +1,7 @@
+// v4 (example: Transfer(address indexed, address indexed, uint256)
+interface.events.Transfer.encodeTopics(values)
+interface.events.Transfer.decode(data, topics)
+
+// v5
+interface.encodeFilterTopics("Transfer", values)
+interface.encodeEventLog("Transfer", data, topics)

docs.wrm/migration/ethers-v4/interface-functions.txt

@@ -0,0 +1,14 @@
+// v4 (example: "transfer(address to, uint amount)")
+interface.functions.transfer.encode(to, amount)
+interface.functions.transfer.decode(callData)
+
+// v5
+interface.encodeData("transfer", [ to, amount ])
+interface.decodeResult("transfer", data)
+
+// Or you can use any compatible signature or Fragment objects.
+// Notice that signature normalization is performed for you,
+// e.g. "uint" and "uint256" will be automatically converted
+interface.encodeData("transfer(address,uint)", [ to, amount ])
+interface.decodeResult("transfer(address to, uint256 amount)", data)
+

docs.wrm/migration/ethers-v4/interface-inspection.txt

@@ -0,0 +1,48 @@
+// v4
+interface.functions.transfer.name
+interface.functions.transfer.inputs
+interface.functions.transfer.outputs
+interface.functions.transfer.payable
+interface.functions.transfer.gas
+
+// v5
+const functionFragment = interface.getFunction("transfer")
+functionFragment.name
+functionFragment.inputs
+functionFragment.outputs
+functionFragment.payable
+functionFragment.gas
+
+
+// v4; type is "call" or "transaction"
+interface.functions.transfer.type
+
+// v5; constant is true (i.e. "call") or false (i.e. "transaction")
+functionFragment.constant
+
+
+// v4
+interface.events.Transfer.anonymous
+interface.events.Transfer.inputs
+interface.events.Transfer.name
+
+// v5
+const eventFragment = interface.getEvent("Transfer");
+eventFragment.anonymous
+eventFragment.inputs
+eventFragment.name
+
+
+// v4
+const functionSig = interface.functions.transfer.signature
+const sighash = interface.functions.transfer.sighash
+
+const eventSig = interface.events.Transfer.signature
+const topic = interface.events.Transfer.topic
+
+// v5
+const functionSig = functionFragment.format()
+const sighash = interface.getSighash(functionFragment)
+
+const eventSig = eventFragment.format()
+const topic = interface.getTopic(eventFragment)

docs.wrm/migration/ethers-v4/utils.txt

@@ -0,0 +1 @@
+TODO

docs.wrm/migration/ethers-v4/wallet.txt

@@ -0,0 +1,9 @@
+// v4
+wallet.mnemonic
+wallet.path
+
+// v5
+// - Mnemonic phrase and path are a Mnemonic object
+// - Note: wallet.mnemonic is null if there is no mnemonic
+wallet.mnemonic.phrase
+wallet.mnemonic.path

docs.wrm/migration/index.wrm

@@ -1,13 +1,8 @@
-_title: Migration Guide
+_section: Migration Guide @<migration>
 
-_section: Migration Guide
+Here are some migration guides when upgrading from older versions
+of Ethers or other libraries.
 
-Migratimg...
-
-_subsection: From Web3
-
-test
-
-_subsection: From ethers v4
-
-test
+_toc:
+    web3
+    ethers-v4

docs.wrm/migration/web3/index.wrm

@@ -0,0 +1,13 @@
+_section: Migration: From Web3.js
+
+TODO
+
+_subsection: Contracts
+
+_subsection: Providers
+
+_subsection: Numbers
+
+_subsection: Utilities
+
+

docs.wrm/testing/index.wrm

@@ -1,5 +1,3 @@
-_title: Testing
-
 _section: Testing
 
 Here goes info about testing

docs/README.md

@@ -4,14 +4,18 @@ Documentation: [html](https://docs-beta.ethers.io/)
 
 -----
 
+Documentation
+=============
 
-What is ethers?
-===============
+
+
+What is Ethers?
+---------------
 
 
 The ethers.js library aims to be a complete and compact library for
 interacting with the Ethereum Blockchain and its ecosystem. It was
-originally designed for use with [ethers.io](https://ethers.io/) and
+originally designed for use with [ethers.io](Users/ricmoo/Development/ethers/ethers.js-v5/https:/ethers.io) and
 has since expanded into a much more general-purpose library.
 
 
@@ -25,11 +29,11 @@ Features
 * Import and export **JSON wallets** (Geth, Parity and crowdsale)
 * Import and export BIP 39 **mnemonic phrases** (12 word backup phrases) and HD Wallets (English, Italian, Japanese, Korean, Simplified Chinese, Traditional Chinese; more coming soon)
 * Meta-classes create JavaScript objects from any contract ABI, including **ABIv2** and **Human-Readable ABI**
-* Connect to Ethereum nodes over [JSON-RPC](https://github.com/ethereum/wiki/wiki/JSON-RPC), [INFURA](https://infura.io/), [Etherscan](https://etherscan.io/), [Nodesmith](https://nodesmith.io), [Alchemy](https://alchemyapi.io), or [MetaMask](https://metamask.io/).
+* Connect to Ethereum nodes over [JSON-RPC](Users/ricmoo/Development/ethers/ethers.js-v5/https:/github.com/ethereum/wiki/wiki/JSON-RPC), [INFURA](Users/ricmoo/Development/ethers/ethers.js-v5/https:/infura.io), [Etherscan](Users/ricmoo/Development/ethers/ethers.js-v5/https:/etherscan.io), [Alchemy](Users/ricmoo/Development/ethers/ethers.js-v5/https:/alchemyapi.io), [Cloudflare](Users/ricmoo/Development/ethers/ethers.js-v5/https:/developers.cloudflare.com/distributed-web/ethereum-gateway) or [MetaMask](Users/ricmoo/Development/ethers/ethers.js-v5/https:/metamask.io).
 * **ENS names** are first-class citizens; they can be used anywhere an Ethereum addresses can be used
 * **Tiny** (~88kb compressed; 284kb uncompressed)
 * **Complete** functionality for all your Ethereum needs
-* Extensive [documentation](https://docs.ethers.io/)
+* Extensive [documentation](Users/ricmoo/Development/ethers/ethers.js-v5/https:/docs.ethers.io)
 * Large collection of **test cases** which are maintained and added to
 * Fully **TypeScript** ready, with definition files and full TypeScript source
 * **MIT License** (including *ALL* dependencies); completely open source to do with as you please
@@ -50,8 +54,19 @@ Developer Documentation
     * [Gas Price](concepts/gas)
     * [Gas Limit](concepts/gas)
 * [Application Programming Interface](api)
-  * [Contracts](api/contract)
-    * [Buckets](api/contract)
+  * [Contract Interaction](api/contract)
+    * [Contract](api/contract/contract)
+      * [Properties](api/contract/contract)
+      * [Methods](api/contract/contract)
+      * [Events](api/contract/contract)
+      * [Meta-Class](api/contract/contract)
+    * [Example: ERC-20 Contract](api/contract/example)
+      * [Connecting to a Contract](api/contract/example)
+      * [Properties ^^//(inheritted from [[contract]])//^^](api/contract/example)
+      * [Methods ^^//(inheritted from [[contract]])//^^](api/contract/example)
+      * [Events ^^//(inheritted from Contract)//^^](api/contract/example)
+      * [Meta-Class Methods ^^//(added at Runtime)//^^](api/contract/example)
+      * [Meta-Class Filters ^^//(added at Runtime)//^^](api/contract/example)
   * [Signers](api/signer)
     * [Signer](api/signer)
     * [Wallet](api/signer)
@@ -81,21 +96,34 @@ Developer Documentation
       * [UrlJsonRpcProvider](api/providers/other)
       * [Web3Provider](api/providers/other)
     * [Types](api/providers/types)
+      * [BlockTag](api/providers/types)
       * [Network](api/providers/types)
       * [Block](api/providers/types)
       * [Events and Logs](api/providers/types)
       * [Transactions](api/providers/types)
   * [Utilities](api/utils)
+    * [Application Binary Interface](api/utils/abi)
+      * [Interface](api/utils/abi/interface)
+        * [Creating Instances](api/utils/abi/interface)
+        * [Properties](api/utils/abi/interface)
+        * [Formatting](api/utils/abi/interface)
+        * [Fragment Access](api/utils/abi/interface)
+        * [Signature and Topic Hashes](api/utils/abi/interface)
+        * [Encoding Data](api/utils/abi/interface)
+        * [Decoding Data](api/utils/abi/interface)
+        * [Parsing](api/utils/abi/interface)
+        * [Types](api/utils/abi/interface)
+        * [Specifying Fragments](api/utils/abi/interface)
+      * [Fragments](api/utils/abi/fragments)
+        * [Formats](api/utils/abi/fragments)
+        * [Fragment](api/utils/abi/fragments)
+        * [ConstructorFragment](api/utils/abi/fragments)
+        * [EventFragment](api/utils/abi/fragments)
+        * [FunctionFragment](api/utils/abi/fragments)
+        * [ParamType](api/utils/abi/fragments)
     * [Addresses](api/utils/address)
       * [Address Formats](api/utils/address)
       * [Functions](api/utils/address)
-    * [Application Binary Interface](api/utils/abi)
-      * [Formats](api/utils/abi)
-      * [Fragment](api/utils/abi)
-      * [ConstructorFragment](api/utils/abi)
-      * [EventFragment](api/utils/abi)
-      * [FunctionFragment](api/utils/abi)
-      * [ParamType](api/utils/abi)
     * [BigNumber](api/utils/bignumber)
       * [Types](api/utils/bignumber)
       * [Creating Instances](api/utils/bignumber)
@@ -108,6 +136,7 @@ Developer Documentation
       * [Array Manipulation](api/utils/bytes)
       * [Hexstring Manipulation](api/utils/bytes)
       * [Signature Conversion](api/utils/bytes)
+      * [Random Bytes](api/utils/bytes)
     * [Constants](api/utils/constants)
       * [Bytes](api/utils/constants)
       * [Strings](api/utils/constants)
@@ -115,15 +144,30 @@ Developer Documentation
     * [Display Logic and Input](api/utils/display-logic)
       * [Units](api/utils/display-logic)
       * [Functions](api/utils/display-logic)
+    * [Encoding Utilities](api/utils/encoding)
+      * [Base58](api/utils/encoding)
+      * [Base64](api/utils/encoding)
+      * [Recursive-Length Prefix](api/utils/encoding)
     * [FixedNumber](api/utils/fixednumber)
-      * [FixedFormat](api/utils/fixednumber)
       * [Creating Instances](api/utils/fixednumber)
       * [Properties](api/utils/fixednumber)
       * [Methods](api/utils/fixednumber)
+      * [FixedFormat](api/utils/fixednumber)
     * [Hashing Algorithms](api/utils/hashing)
       * [Cryptographic Hashing](api/utils/hashing)
       * [Common Hashing Helpers](api/utils/hashing)
       * [Solidity Hashing Algorithms](api/utils/hashing)
+    * [HD Wallet](api/utils/hdnode)
+      * [Types](api/utils/hdnode)
+      * [HDNode](api/utils/hdnode)
+      * [Other Functions](api/utils/hdnode)
+    * [Logging](api/utils/logger)
+      * [Logger](api/utils/logger)
+      * [Errors](api/utils/logger)
+      * [Log Levels](api/utils/logger)
+    * [Property Utilities](api/utils/properties)
+    * [Signing Key](api/utils/signing-key)
+      * [Other Functions](api/utils/signing-key)
     * [Strings](api/utils/strings)
       * [Bytes32String](api/utils/strings)
       * [UTF-8 Strings](api/utils/strings)
@@ -132,7 +176,29 @@ Developer Documentation
     * [Transactions](api/utils/transactions)
       * [Types](api/utils/transactions)
       * [Functions](api/utils/transactions)
+    * [Web Utilities](api/utils/web)
+    * [Wordlists](api/utils/wordlists)
+      * [Wordlist](api/utils/wordlists)
+      * [Languages](api/utils/wordlists)
   * [Other Libraries](api/other)
+    * [Assembly](api/other/assembly)
+      * [Ethers ASM Dialect](api/other/assembly/dialect)
+        * [Opcodes](api/other/assembly/dialect)
+        * [Labels](api/other/assembly/dialect)
+        * [Literals](api/other/assembly/dialect)
+        * [Comments](api/other/assembly/dialect)
+        * [Scopes](api/other/assembly/dialect)
+        * [Data Segment](api/other/assembly/dialect)
+        * [Links](api/other/assembly/dialect)
+        * [Stack Placeholders](api/other/assembly/dialect)
+        * [Evaluation and Excution](api/other/assembly/dialect)
+      * [Utilities](api/other/assembly/api)
+        * [Assembler](api/other/assembly/api)
+        * [Disassembler](api/other/assembly/api)
+        * [Opcode](api/other/assembly/api)
+      * [Abstract Syntax Tree](api/other/assembly/ast)
+        * [Types](api/other/assembly/ast)
+        * [Nodes](api/other/assembly/ast)
     * [Hardware Wallets](api/other/hardware)
       * [LedgerSigner](api/other/hardware)
 * [Command Line Interfaces](cli)
@@ -141,8 +207,10 @@ Developer Documentation
     * [Examples](cli/ethers)
   * [Assembler](cli/asm)
     * [Help](cli/asm)
-    * [Examples](cli/asm)
-  * [ENS](cli/ens)
+    * [Example Input Files](cli/asm)
+    * [Assembler Examples](cli/asm)
+    * [Disassembler Examples](cli/asm)
+  * [Ethereum Naming Service](cli/ens)
     * [Help](cli/ens)
     * [Examples](cli/ens)
   * [TypeScript](cli/typescript)
@@ -154,8 +222,18 @@ Developer Documentation
     * [ArgParser](cli/plugin)
 * [Cookbook](cookbook)
 * [Migration Guide](migration)
-  * [From Web3](migration)
-  * [From ethers v4](migration)
+  * [Migration: From Web3.js](migration/web3)
+    * [Contracts](migration/web3)
+    * [Providers](migration/web3)
+    * [Numbers](migration/web3)
+    * [Utilities](migration/web3)
+  * [Migration: From Ethers v4](migration/ethers-v4)
+    * [BigNumber](migration/ethers-v4)
+    * [Contracts](migration/ethers-v4)
+    * [Errors](migration/ethers-v4)
+    * [Interface](migration/ethers-v4)
+    * [Utilities](migration/ethers-v4)
+    * [Wallet](migration/ethers-v4)
 * [Testing](testing)
 * [Contributing and Hacking](contributing)
   * [Building](contributing)
@@ -176,10 +254,10 @@ older versions of the library.
 
 
 
-* [version 4.0](https://docs.ethers.io/ethers.js)
-* [version 3.0](https://docs.ethers.io/ethers.js/v3.0/html/)
+* [version 4.0](Users/ricmoo/Development/ethers/ethers.js-v5/https:/docs.ethers.io/ethers.js)
+* [version 3.0](Users/ricmoo/Development/ethers/ethers.js-v5/https:/docs.ethers.io/ethers.js/v3.0/html)
 
 
 
 -----
-**Content Hash:** bf4f628855f6f4c54ceca8c845e7ec93498135aa2d045f582d7c98e3a05294d7
+**Content Hash:** 1ccc27c4ba6e59efa2be69cc0fb345ea9c397f1f4444d08ec13780d0d1a46b60

docs/api/README.md

@@ -4,16 +4,26 @@ Documentation: [html](https://docs-beta.ethers.io/)
 
 -----
 
-
-Application Programming Interface (API)
-=======================================
+Application Programming Interface
+=================================
 
 
 Here...
 
 
-* [Contracts](contract)
-  * [Buckets](contract)
+* [Contract Interaction](contract)
+  * [Contract](contract/contract)
+    * [Properties](contract/contract)
+    * [Methods](contract/contract)
+    * [Events](contract/contract)
+    * [Meta-Class](contract/contract)
+  * [Example: ERC-20 Contract](contract/example)
+    * [Connecting to a Contract](contract/example)
+    * [Properties ^^//(inheritted from [[contract]])//^^](contract/example)
+    * [Methods ^^//(inheritted from [[contract]])//^^](contract/example)
+    * [Events ^^//(inheritted from Contract)//^^](contract/example)
+    * [Meta-Class Methods ^^//(added at Runtime)//^^](contract/example)
+    * [Meta-Class Filters ^^//(added at Runtime)//^^](contract/example)
 * [Signers](signer)
   * [Signer](signer)
   * [Wallet](signer)
@@ -43,21 +53,34 @@ Here...
     * [UrlJsonRpcProvider](providers/other)
     * [Web3Provider](providers/other)
   * [Types](providers/types)
+    * [BlockTag](providers/types)
     * [Network](providers/types)
     * [Block](providers/types)
     * [Events and Logs](providers/types)
     * [Transactions](providers/types)
 * [Utilities](utils)
+  * [Application Binary Interface](utils/abi)
+    * [Interface](utils/abi/interface)
+      * [Creating Instances](utils/abi/interface)
+      * [Properties](utils/abi/interface)
+      * [Formatting](utils/abi/interface)
+      * [Fragment Access](utils/abi/interface)
+      * [Signature and Topic Hashes](utils/abi/interface)
+      * [Encoding Data](utils/abi/interface)
+      * [Decoding Data](utils/abi/interface)
+      * [Parsing](utils/abi/interface)
+      * [Types](utils/abi/interface)
+      * [Specifying Fragments](utils/abi/interface)
+    * [Fragments](utils/abi/fragments)
+      * [Formats](utils/abi/fragments)
+      * [Fragment](utils/abi/fragments)
+      * [ConstructorFragment](utils/abi/fragments)
+      * [EventFragment](utils/abi/fragments)
+      * [FunctionFragment](utils/abi/fragments)
+      * [ParamType](utils/abi/fragments)
   * [Addresses](utils/address)
     * [Address Formats](utils/address)
     * [Functions](utils/address)
-  * [Application Binary Interface](utils/abi)
-    * [Formats](utils/abi)
-    * [Fragment](utils/abi)
-    * [ConstructorFragment](utils/abi)
-    * [EventFragment](utils/abi)
-    * [FunctionFragment](utils/abi)
-    * [ParamType](utils/abi)
   * [BigNumber](utils/bignumber)
     * [Types](utils/bignumber)
     * [Creating Instances](utils/bignumber)
@@ -70,6 +93,7 @@ Here...
     * [Array Manipulation](utils/bytes)
     * [Hexstring Manipulation](utils/bytes)
     * [Signature Conversion](utils/bytes)
+    * [Random Bytes](utils/bytes)
   * [Constants](utils/constants)
     * [Bytes](utils/constants)
     * [Strings](utils/constants)
@@ -77,15 +101,30 @@ Here...
   * [Display Logic and Input](utils/display-logic)
     * [Units](utils/display-logic)
     * [Functions](utils/display-logic)
+  * [Encoding Utilities](utils/encoding)
+    * [Base58](utils/encoding)
+    * [Base64](utils/encoding)
+    * [Recursive-Length Prefix](utils/encoding)
   * [FixedNumber](utils/fixednumber)
-    * [FixedFormat](utils/fixednumber)
     * [Creating Instances](utils/fixednumber)
     * [Properties](utils/fixednumber)
     * [Methods](utils/fixednumber)
+    * [FixedFormat](utils/fixednumber)
   * [Hashing Algorithms](utils/hashing)
     * [Cryptographic Hashing](utils/hashing)
     * [Common Hashing Helpers](utils/hashing)
     * [Solidity Hashing Algorithms](utils/hashing)
+  * [HD Wallet](utils/hdnode)
+    * [Types](utils/hdnode)
+    * [HDNode](utils/hdnode)
+    * [Other Functions](utils/hdnode)
+  * [Logging](utils/logger)
+    * [Logger](utils/logger)
+    * [Errors](utils/logger)
+    * [Log Levels](utils/logger)
+  * [Property Utilities](utils/properties)
+  * [Signing Key](utils/signing-key)
+    * [Other Functions](utils/signing-key)
   * [Strings](utils/strings)
     * [Bytes32String](utils/strings)
     * [UTF-8 Strings](utils/strings)
@@ -94,11 +133,33 @@ Here...
   * [Transactions](utils/transactions)
     * [Types](utils/transactions)
     * [Functions](utils/transactions)
+  * [Web Utilities](utils/web)
+  * [Wordlists](utils/wordlists)
+    * [Wordlist](utils/wordlists)
+    * [Languages](utils/wordlists)
 * [Other Libraries](other)
+  * [Assembly](other/assembly)
+    * [Ethers ASM Dialect](other/assembly/dialect)
+      * [Opcodes](other/assembly/dialect)
+      * [Labels](other/assembly/dialect)
+      * [Literals](other/assembly/dialect)
+      * [Comments](other/assembly/dialect)
+      * [Scopes](other/assembly/dialect)
+      * [Data Segment](other/assembly/dialect)
+      * [Links](other/assembly/dialect)
+      * [Stack Placeholders](other/assembly/dialect)
+      * [Evaluation and Excution](other/assembly/dialect)
+    * [Utilities](other/assembly/api)
+      * [Assembler](other/assembly/api)
+      * [Disassembler](other/assembly/api)
+      * [Opcode](other/assembly/api)
+    * [Abstract Syntax Tree](other/assembly/ast)
+      * [Types](other/assembly/ast)
+      * [Nodes](other/assembly/ast)
   * [Hardware Wallets](other/hardware)
     * [LedgerSigner](other/hardware)
 
 
 
 -----
-**Content Hash:** 9efeac06691d2415dcc248d1567676602f7df029abd5f844480b12bb844588a7
+**Content Hash:** 792936ddc8c609e435d356c2bfde1adacf9f0b5b708481720f22081f1a61f73d

docs/api/contract/README.md

@@ -4,20 +4,27 @@ Documentation: [html](https://docs-beta.ethers.io/)
 
 -----
 
-
-
-Contracts
-=========
+Contract Interaction
+====================
 
 
 Explain what contracts are...
 
 
-Buckets
--------
-
+* [Contract](contract)
+  * [Properties](contract)
+  * [Methods](contract)
+  * [Events](contract)
+  * [Meta-Class](contract)
+* [Example: ERC-20 Contract](example)
+  * [Connecting to a Contract](example)
+  * [Properties ^^//(inheritted from [[contract]])//^^](example)
+  * [Methods ^^//(inheritted from [[contract]])//^^](example)
+  * [Events ^^//(inheritted from Contract)//^^](example)
+  * [Meta-Class Methods ^^//(added at Runtime)//^^](example)
+  * [Meta-Class Filters ^^//(added at Runtime)//^^](example)
 
 
 
 -----
-**Content Hash:** 190c93691014eae64ffcb66549f127aa73f4645fc7a4b3a2be9ae00216c79cf6
+**Content Hash:** f1a5079be018a7b2e6ce8b86a5a191f7a1352b976434766ea16cec21d0ce3b80

docs/api/contract/contract/README.md

@@ -0,0 +1,284 @@
+-----
+
+Documentation: [html](https://docs-beta.ethers.io/)
+
+-----
+
+Contract
+========
+
+
+
+Properties
+----------
+
+
+
+#### *contract* . **address** **=>** *string< [Address](../../utils/address) >*
+
+This is the address (or ENS name) the contract was constructed with.
+
+
+
+
+#### *contract* . **addressPromise** **=>** *string< [Address](../../utils/address) >*
+
+This is a promise that will resolve to the address the **Contract**
+object is attached to. If an [Address](../../utils/address) was provided to the constructor,
+it will be equal to this; if an ENS name was provided, this will be the
+resolved address.
+
+
+
+
+#### *contract* . **deployTransaction** **=>** *[TransactionResponse](../../providers/types)*
+
+If the **Contract** object is the result of a ContractFactory deployment,
+this is the transaction which was used to deploy the contract.
+
+
+
+
+#### *contract* . **interface** **=>** *[Interface](../../utils/abi/interface)*
+
+This is the ABI as an [Interface](../../utils/abi/interface).
+
+
+
+
+#### *contract* . **provider** **=>** *[Provider](../../providers/provider)*
+
+If a provider was provided to the constructor, this is that provider. If
+a signer was provided that had a [Provider](../../providers/provider), this is that provider.
+
+
+
+
+#### *contract* . **signer** **=>** *[Signer](../../signer)*
+
+If a signer was provided to the constructor, this is that signer.
+
+
+
+
+Methods
+-------
+
+
+
+#### *contract* . **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.
+
+
+
+
+#### *contract* . **connect** ( providerOrSigner )  **=>** *[Contract](./)*
+
+Returns a new instance of the Contract, but connected to
+*providerOrSigner*.
+
+By passing in a [Provider](../../providers/provider), this will return a downgraded
+**Contract** which only has read-only access (i.e. constant calls).
+
+By passing in a [Signer](../../signer). the will return a **Contract** which
+will act on behalf of that signer.
+
+
+
+
+#### *contract* . **deployed** (  )  **=>** *Promise< [Contract](./) >*
+
+
+
+
+
+
+#### *Contract* . **isIndexed** ( value )  **=>** *boolean*
+
+
+
+
+
+
+Events
+------
+
+
+
+#### *contract* . **queryFilter** ( event [  , fromBlockOrBlockHash [  , toBlock ]  )  **=>** *Promise< Array< Event > >*
+
+Return Events that match the *event*.
+
+
+
+
+#### *contract* . **listenerCount** (  [ event ]  )  **=>** *number*
+
+Return the number of listeners that are subscribed to *event*. If
+no event is provided, returns the total count of all events.
+
+
+
+
+#### *contract* . **listeners** ( event )  **=>** *Array< Listener >*
+
+Return a list of listeners that are subscribed to *event*.
+
+
+
+
+#### *contract* . **off** ( event , listener )  **=>** *this*
+
+Unsubscribe *listener* to *event*.
+
+
+
+
+#### *contract* . **on** ( event , listener )  **=>** *this*
+
+Subscribe to *event* calling *listener* when the event occurs.
+
+
+
+
+#### *contract* . **once** ( event , listener )  **=>** *this*
+
+Subscribe once to *event* calling *listener* when the event
+occurs.
+
+
+
+
+#### *contract* . **removeAllListeners** (  [ event ]  )  **=>** *this*
+
+Unsubscribe all listeners for *event*. If no event is provided,
+all events are unsubscribed.
+
+
+
+
+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
+determine what methods are available, so the following sections
+describe the generic ways to interact with the properties added
+at run-time during the **Contract** constructor.
+
+
+### 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
+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..
+
+
+#### *contract* . **METHOD_NAME** ( ...args [ overrides ]  )  **=>** *Promise< any >*
+
+The type of the result depends on the ABI.
+
+For values that have a simple meaning in JavaScript, the types are fairly
+straight forward; strings and booleans are returned as JavaScript strings
+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](../../utils/bignumber) is returned.
+
+For bytes (both fixed length and dynamic), a [DataHexstring](../../utils/bytes) is returned.
+
+
+
+
+### 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
+will be verified by every node on the entire network as well by the
+miner who will compute the new state of the blockchain after executing
+it against the current state.
+
+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.
+
+
+#### *contract* . **METHOD_NAME** ( ...args [  , overrides ]  )  **=>** *Promise< [TransactionResponse](../../providers/types) >*
+
+Returns a [TransactionResponse](../../providers/types) for the transaction after
+it is sent to the network. This requires the **Contract** has a
+signer.
+
+
+
+
+### Write Methods Analysis
+
+
+There are secveral options to analyze properties and results of a
+write method without actually executing it.
+
+
+#### *contract* . *estimate* . **METHOD_NAME** ( ...args [  , overrides ]  )  **=>** *Promise< [BigNumber](../../utils/bignumber) >*
+
+Returns the estimate units of gas that would be required to
+execute the *METHOD_NAME* with *args* and *overrides*.
+
+
+
+
+#### *contract* . *populateTransaction* . **METHOD_NAME** ( ...args [  , overrides ]  )  **=>** *Promise< [UnsignedTx](../../utils/transactions) >*
+
+Returns an [UnsignedTransaction](../../utils/transactions) which represents the transaction
+that would need to be signed and submitted to the network to execute
+*METHOD_NAME* with *args/ and *overrides//.
+
+
+
+
+#### *contract* . *staticCall* . **METHOD_NAME** ( ...args [  , overrides ]  )  **=>** *Promise< any >*
+
+Rather than executing the state-change of a transaction, it is possible
+to ask a node to *pretend* that a call is not state-changing and
+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](./).
+
+
+
+
+### Event Filters
+
+
+An event filter is made up of topics, which are values logged in a
+[Bloom Filter](../../../Users/ricmoo/Development/ethers/ethers.js-v5/https:/en.wikipedia.org/wiki/Bloom_filter), allowing efficient searching for entries
+which match a filter.
+
+
+#### *contract* . *filters* . **EVENT_NAME** ( ...args )  **=>** *Filter*
+
+Return a filter for *EVENT_NAME*, optionally filtering by additional
+constraints.
+
+Only `indexed` event parameters may be filtered. If a parameter is
+null (or not provided) then any value in that field matches.
+
+
+
+
+
+-----
+**Content Hash:** 8f1f64a28b2501d01dcf4b55c405c43096f3a9daca7169a96022000a315b2ef2

docs/api/contract/example/README.md

@@ -0,0 +1,323 @@
+-----
+
+Documentation: [html](https://docs-beta.ethers.io/)
+
+-----
+
+Example: ERC-20 Contract
+========================
+
+
+
+Connecting to a Contract
+------------------------
+
+
+
+```
+// A Human-Readable ABI; any supported ABI format could be used
+const abi = [
+    // Read-Only Functions
+    "function balanceOf(address owner) view returns (uint256)",
+    "function decimals() view returns (uint8)",
+    "function symbol() view returns (string)",
+
+    // Authenticated Functions
+    "function transfer(address to, uint amount) returns (boolean)",
+
+    // Events
+    "event Transfer(address indexed from, address indexed to, uint amount)"
+];
+
+// This can be an address or an ENS name
+const address = "demotoken.ethers.eth";
+
+// An example Provider (connceted to testnet)
+const provider = ethers.getDefaultProvider("ropsten");
+
+// An example Signer
+const signer = ethers.Wallet.createRandom(provider);
+
+// Read-Only; By connecting to a Provider, allows:
+// - Any constant function
+// - Querying Filters
+// - Populating Unsigned Transactions for non-constant methods
+// - Estimating Gas for non-constant (as an anonymous sender)
+// - Static Calling non-constant methods (as anonymous sender)
+const erc20 = new ethers.Contract(address, abi, provider);
+
+// Read-Write; By connecting to a Signer, allows:
+// - Everything from Read-Only (except as Signer, not anonymous)
+// - Sending transactions for non-constant functions
+const erc20_rw = new ethers.Contract(address, abi, signer)
+```
+
+
+
+### ERC20Contract
+
+
+
+#### **new** *ethers* . **Contract** ( address , abi , providerOrSigner ) 
+
+See the above code example for creating an Instance which will
+(in addition to the Contact methods and properties) automatically
+add the additional properties defined in *abi* to a **Contract**
+connected to *address* using the *providerOrSigner*.
+
+
+
+
+Properties ^(*(inheritted from [Contract](../contract))*)
+---------------------------------------------------------
+
+
+
+#### *erc20* . **address** **=>** *string< [Address](../../utils/address) >*
+
+This is the address (or ENS name) the contract was constructed with.
+
+
+
+
+#### *erc20* . **addressPromise** **=>** *string< [Address](../../utils/address) >*
+
+This is a promise that will resolve to the address the **Contract**
+object is attached to. If an [Address](../../utils/address) was provided to the constructor,
+it will be equal to this; if an ENS name was provided, this will be the
+resolved address.
+
+
+
+
+#### *erc20* . **deployTransaction** **=>** *[TransactionResponse](../../providers/types)*
+
+If the **Contract** object is the result of a ContractFactory deployment,
+this is the transaction which was used to deploy the contract.
+
+
+
+
+#### *erc20* . **interface** **=>** *[Interface](../../utils/abi/interface)*
+
+This is the ABI as an [Interface](../../utils/abi/interface).
+
+
+
+
+#### *erc20* . **provider** **=>** *[Provider](../../providers/provider)*
+
+If a provider was provided to the constructor, this is that provider. If
+a signer was provided that had a [Provider](../../providers/provider), this is that provider.
+
+
+
+
+#### *erc20* . **signer** **=>** *[Signer](../../signer)*
+
+If a signer was provided to the constructor, this is that signer.
+
+
+
+
+Methods ^(*(inheritted from [Contract](../contract))*)
+------------------------------------------------------
+
+
+
+#### *erc20* . **attach** ( addressOrName )  **=>** *[Contract](../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.
+
+
+
+
+#### *erc20* . **connect** ( providerOrSigner )  **=>** *[Contract](../contract)*
+
+Returns a new instance of the Contract, but connected to
+*providerOrSigner*.
+
+By passing in a [Provider](../../providers/provider), this will return a downgraded
+**Contract** which only has read-only access (i.e. constant calls).
+
+By passing in a [Signer](../../signer). the will return a **Contract** which
+will act on behalf of that signer.
+
+
+
+
+#### *erc20* . **deployed** (  )  **=>** *Promise< Contract >*
+
+
+
+
+
+
+#### *Contract* . **isIndexed** ( value )  **=>** *boolean*
+
+
+
+
+
+
+Events ^(*(inheritted from Contract)*)
+--------------------------------------
+
+
+
+#### *erc20* . **queryFilter** ( event [  , fromBlockOrBlockHash [  , toBlock ]  )  **=>** *Promise< Array< Event > >*
+
+Return Events that match the *event*.
+
+
+
+
+#### *erc20* . **listenerCount** (  [ event ]  )  **=>** *number*
+
+Return the number of listeners that are subscribed to *event*. If
+no event is provided, returns the total count of all events.
+
+
+
+
+#### *erc20* . **listeners** ( event )  **=>** *Array< Listener >*
+
+Return a list of listeners that are subscribed to *event*.
+
+
+
+
+#### *erc20* . **off** ( event , listener )  **=>** *this*
+
+Unsubscribe *listener* to *event*.
+
+
+
+
+#### *erc20* . **on** ( event , listener )  **=>** *this*
+
+Subscribe to *event* calling *listener* when the event occurs.
+
+
+
+
+#### *erc20* . **once** ( event , listener )  **=>** *this*
+
+Subscribe once to *event* calling *listener* when the event
+occurs.
+
+
+
+
+#### *erc20* . **removeAllListeners** (  [ event ]  )  **=>** *this*
+
+Unsubscribe all listeners for *event*. If no event is provided,
+all events are unsubscribed.
+
+
+
+
+Meta-Class Methods ^(*(added at Runtime)*)
+------------------------------------------
+
+
+Since the Contract is a Meta-Class, the methods available here depend
+on the ABI which was passed into the **Contract**.
+
+
+#### *erc20* . **decimals** (  [ overrides ]  )  **=>** *Promise< number >*
+
+Returns the number of decimal places used by this ERC-20 token. This can be
+used with [parseUnits](../../utils/display-logic) when taking input from the user or
+[formatUnits](utils-formatunits] when displaying the token amounts in the UI.
+
+
+
+
+#### *erc20* . **getBalance** ( owner [  , overrides ]  )  **=>** *Promise< [BigNumber](../../utils/bignumber) >*
+
+Returns the balance of *owner* for this ERC-20 token.
+
+
+
+
+#### *erc20* . **symbol** (  [ overrides ]  )  **=>** *Promise< string >*
+
+Returns the symbol of the token.
+
+
+
+
+#### *erc20_rw* . **transfer** ( target , amount [  , overrides ]  )  **=>** *Promise< [TransactionResponse](../../providers/types) >*
+
+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
+if this value is required. On-chain contracts calling the `transfer`
+function have access to this result, which is why it is possible.
+
+
+
+
+#### *erc20* . *callStatic* . **transfer** ( target , amount [  , overrides ]  )  **=>** *Promise< boolean >*
+
+Performs a dry-run of transferring *amount* tokens to *target* from
+the current signer, without actually signing or sending a transaction.
+
+This can be used to preflight check that a transaction will be successful.
+
+
+
+
+#### *erc20* . *estimate* . **transfer** ( target , amount [  , overrides ]  )  **=>** *Promise< [BigNumber](../../utils/bignumber) >*
+
+Returns an estimate for how many units of gas would be required
+to transfer *amount* tokens to *target*.
+
+
+
+
+#### *erc20* . *populateTransaction* . **transfer** ( target , amount [  , overrides ]  )  **=>** *Promise< [UnsignedTx](../../utils/transactions) >*
+
+Returns an [UnsignedTransaction](../../utils/transactions) which could be signed and submitted
+to the network to transaction *amount* tokens to *target*.
+
+
+
+
+#### Note on Estimating and Static Calling
+
+When you perform a static call, the current state is taken into account as
+best as Ethereum can determine. There are many cases where this can provide
+false positives and false negatives. The eventually consistent model of the
+blockchain also means there are certain consistency modes that cannot be
+known until an actual transaction is attempted.
+
+
+
+
+Meta-Class Filters ^(*(added at Runtime)*)
+------------------------------------------
+
+
+Since the Contract is a Meta-Class, the methods available here depend
+on the ABI which was passed into the **Contract**.
+
+
+#### *erc20* . *filters* . **Transafer** (  [ fromAddress [  , toAddress ]  ]  )  **=>** *Filter*
+
+Returns a new Filter which can be used to [query](./) or
+to [subscribe/unsubscribe to events](./).
+
+If *fromAddress* is null or not provided, then any from address matches.
+If *toAddress* is null or not provided, then any to address matches.
+
+
+
+
+
+-----
+**Content Hash:** a3d2ad294a2b4b4500d3f80c7a1cdc76420fee234ad271d90f5c609b040e93fa

docs/api/other/README.md

@@ -4,7 +4,6 @@ Documentation: [html](https://docs-beta.ethers.io/)
 
 -----
 
-
 Other Libraries
 ===============
 
@@ -14,10 +13,28 @@ ancillary packages, which are not part of the core but optionally
 add functionality only needed in certain situations.
 
 
+* [Assembly](assembly)
+  * [Ethers ASM Dialect](assembly/dialect)
+    * [Opcodes](assembly/dialect)
+    * [Labels](assembly/dialect)
+    * [Literals](assembly/dialect)
+    * [Comments](assembly/dialect)
+    * [Scopes](assembly/dialect)
+    * [Data Segment](assembly/dialect)
+    * [Links](assembly/dialect)
+    * [Stack Placeholders](assembly/dialect)
+    * [Evaluation and Excution](assembly/dialect)
+  * [Utilities](assembly/api)
+    * [Assembler](assembly/api)
+    * [Disassembler](assembly/api)
+    * [Opcode](assembly/api)
+  * [Abstract Syntax Tree](assembly/ast)
+    * [Types](assembly/ast)
+    * [Nodes](assembly/ast)
 * [Hardware Wallets](hardware)
   * [LedgerSigner](hardware)
 
 
 
 -----
-**Content Hash:** bafa126f115321049791ba83b99acf79f82f222eb246124c601983ad8cb4b73a
+**Content Hash:** 90507a9035452f2463c81dc6ce204622750f4781dd52673cf666afae6e607577

docs/api/other/assembly/README.md

@@ -0,0 +1,33 @@
+-----
+
+Documentation: [html](https://docs-beta.ethers.io/)
+
+-----
+
+Assembly
+========
+
+
+
+* [Ethers ASM Dialect](dialect)
+  * [Opcodes](dialect)
+  * [Labels](dialect)
+  * [Literals](dialect)
+  * [Comments](dialect)
+  * [Scopes](dialect)
+  * [Data Segment](dialect)
+  * [Links](dialect)
+  * [Stack Placeholders](dialect)
+  * [Evaluation and Excution](dialect)
+* [Utilities](api)
+  * [Assembler](api)
+  * [Disassembler](api)
+  * [Opcode](api)
+* [Abstract Syntax Tree](ast)
+  * [Types](ast)
+  * [Nodes](ast)
+
+
+
+-----
+**Content Hash:** c29497e2f7fe90669ffd6c67b0231649074fcb869470caa58750ddbc39905727

docs/api/other/assembly/api/README.md

@@ -0,0 +1,184 @@
+-----
+
+Documentation: [html](https://docs-beta.ethers.io/)
+
+-----
+
+Utilities
+=========
+
+
+
+Assembler
+---------
+
+
+The assembler utilities allow parsing and assembling an
+[Ethers ASM Dialect](../dialect) source file.
+
+
+#### *asm* . **parse** ( code )  **=>** *[Node](../ast)*
+
+Parse an ethers-format assembly file and return the [Abstract Syntax Tree](../ast).
+
+
+
+
+#### *asm* . **assemble** ( node )  **=>** *string< [DataHexstring](../../../utils/bytes) >*
+
+Performs assembly of the [Abstract Syntax Tree](../ast) *node* and return the
+resulting bytecode representation.
+
+
+
+
+Disassembler
+------------
+
+
+The **Disassembler** utilities make it easy to convert bytecode
+into an object which can easily be examined for program structure.
+
+
+#### *asm* . **disassemble** ( bytecode )  **=>** *[Bytecode](./)*
+
+Returns an array of Operations given *bytecode*.
+
+
+
+
+#### *asm* . **formatBytecode** ( operations )  **=>** *string*
+
+Create a formatted output of an array of [Operation](./).
+
+
+
+
+### Bytecode
+
+
+Each arary index represents an operation, collapsing multi-byte operations
+(i.e. `PUSH`) into a single operation.
+
+
+#### *bytecode* . **getOperation** ( offset )  **=>** *[Operation](./)*
+
+Get the operation at a given *offset* into the bytecode. This ensures that
+the byte at *offset* is an operation and not data contained within a `PUSH`,
+in which case null it returned.
+
+
+
+
+### Operation
+
+
+An **Operation** is a single command from a disassembled bytecode
+stream.
+
+
+#### *operation* . **opcode** **=>** *[Opcode](./)*
+
+The opcode for this Operation.
+
+
+
+
+#### *operation* . **offset** **=>** *number*
+
+The offset into the bytecode for this Operation.
+
+
+
+
+#### *operation* . **pushValue** **=>** *string< [DataHexstring](../../../utils/bytes) >*
+
+If the opcode is a `PUSH`, this is the value of that push
+
+
+
+
+Opcode
+------
+
+
+
+#### *asm* . *Opcode* . **from** ( valueOrMnemonic )  **=>** *[Opcode](./)*
+
+Create a new instnace of an Opcode for a given numeric value
+(e.g. 0x60 is PUSH1) or mnemonic string (e.g. "PUSH1").
+
+
+
+
+### Properties
+
+
+
+#### *opcode* . **value** **=>** *number*
+
+The value (bytecode as a number) of this opcode.
+
+
+
+
+#### *opcode* . **mnemonic** **=>** *string*
+
+The mnemonic string of this opcode.
+
+
+
+
+#### *opcode* . **delta** **=>** *number*
+
+The number of items this opcode will consume from the stack.
+
+
+
+
+#### *opcode* . **alpha** **=>** *number*
+
+The number of items this opcode will push onto the stack.
+
+
+
+
+#### *opcode* . **doc** **=>** *string*
+
+A short description of what this opcode does.
+
+
+
+
+#### *opcode* . **isMemory** (  )  **=>** *"read"|"write"|"full"*
+
+Returns true if the opcode accesses memory.
+
+
+
+
+#### *opcode* . **isStatic** (  )  **=>** *boolean*
+
+Returns true if the opcode cannot change state.
+
+
+
+
+#### *opcode* . **isJump** (  )  **=>** *boolean*
+
+Returns true if the opcode is a jumper operation.
+
+
+
+
+#### *opcode* . **isPush** (  )  **=>** *number*
+
+Returns 0 if the opcode is not a `PUSH*`, or the number
+of bytes this opcode will push if it is.
+
+
+
+
+
+-----
+**Content Hash:** d71fdeafad470effc353664c161dec6982a9c29b1015a5726fd2a3f576f8e377

docs/api/other/assembly/ast/README.md

@@ -0,0 +1,251 @@
+-----
+
+Documentation: [html](https://docs-beta.ethers.io/)
+
+-----
+
+Abstract Syntax Tree
+====================
+
+
+Parsing a file using the [Ethers ASM Dialect](../dialect) will
+generate an Abstract Syntax Tree. The root node will always
+be a [ScopeNode](./) whose name is `_`.
+
+To parse a file into an Abstract Syntax tree, use the [parse](../api)
+function.
+
+
+Types
+-----
+
+
+
+### Location
+
+
+
+#### **offset** **=>** *number*
+
+The offset into the source code to the start of this node.
+
+
+
+
+#### **length** **=>** *number*
+
+The length of characters in the source code to the end of this node.
+
+
+
+
+#### **source** **=>** *string*
+
+The source code of this node.
+
+
+
+
+Nodes
+-----
+
+
+@TODO: Place a diagram here showing the hierarchy
+
+
+### Node
+
+
+
+#### *node* . **tag** **=>** *string*
+
+A unique tag for this node for the lifetime of the process.
+
+
+
+
+#### *node* . **location** **=>** *[Location](./)*
+
+The source code and location within the source code that this
+node represents.
+
+
+
+
+### ValueNode
+
+
+A **ValueNode** is a node which may manipulate the stack.
+
+
+### LiteralNode
+
+
+
+#### *literalNode* . **value** **=>** *string*
+
+The literal value of this node, which may be a [DataHexstring](../../../utils/bytes) or
+string of a decimal number.
+
+
+
+
+#### *literalNode* . **verbatim** **=>** *boolean*
+
+This is true in a [DataNode](./) context, since in that case the
+value should be taken verbatim and no `PUSH` operation shoud be
+added, otherwise false.
+
+
+
+
+### PopNode
+
+
+A **PopNode** is used to store a place-holder for an implicit pop from the
+stack. It represents the code for an implicit place-holder (i.e. `$$`) or an
+explicit place-holder (e.g. `$1`), which indicates the expect stack position
+to consume.
+
+
+#### *literalNode* . **index** **=>** *number*
+
+The index this **PopNode** is representing. For an implicit place-holder
+this is `0`.
+
+
+
+
+### LinkNode
+
+
+A **LinkNode** represents a link to another [Node](./)'s data,
+for example `$foo` or `#bar`.
+
+
+#### *linkNode* . **label** **=>** *string*
+
+Te name of the target node.
+
+
+
+
+#### *linkNode* . **type** **=>** *"offset"|"length"*
+
+Whether this node is for an offset or a length value of the
+target node.
+
+
+
+
+### OpcodeNode
+
+
+
+#### *opcodeNode* . **opcode** **=>** *[Opcode](../api)*
+
+The opcode for this Node.
+
+
+
+
+#### *opcodeNode* . **operands** **=>** *Array< [ValueNode](./) >*
+
+A list of all operands passed into this Node.
+
+
+
+
+### EvaluationNode
+
+
+An **EvaluationNode** is used to execute code and insert the results
+but does not generate
+any output assembly, using the `{{! code here }}` syntax.
+
+
+#### *literalNode* . **verbatim** **=>** *boolean*
+
+This is true in a [DataNode](./) context, since in that case the
+value should be taken verbatim and no `PUSH` operation shoud be
+added, otherwise false.
+
+
+
+
+#### *evaluationNode* . **script** **=>** *string*
+
+The code to evaluate and produce the result to use as a literal.
+
+
+
+
+### ExecutionNode
+
+
+An **ExecutionNode** is used to execute code but does not generate
+any output assembly, using the `{{! code here }}` syntax.
+
+
+#### *evaluationNode* . **script** **=>** *string*
+
+The code to execute. Any result is ignored.
+
+
+
+
+### LabelledNode
+
+
+A **LabelledNode** is used for any Node that has a name, and can therefore
+be targetted by a [LinkNode](./).
+
+
+#### *labelledNode* . **name** **=>** *string*
+
+The name of this node.
+
+
+
+
+### LabelNode
+
+
+A **LabelNode** is used as a place to `JUMP` to by referencing it
+name, using `@myLabel:`. A `JUMPDEST` is automatically inserted
+at the bytecode offset.
+
+
+### DataNode
+
+
+A **DataNode** allows for data to be inserted directly into the output
+assembly, using `@myData[ ... ]`. The data is padded if needed to ensure
+values that would otherwise be regarded as a `PUSH` value does not impact
+anything past the data.
+
+
+#### *dataNode* . **data** **=>** *Array< [ValueNode](./) >*
+
+The child nodes, which each represent a verbatim piece of data in insert.
+
+
+
+
+### ScopeNode
+
+
+A **ScopeNode** allows a new frame of reference that all [LinkNode](./)'s
+will use when resolving offset locations, using `@myScope{ ... }`.
+
+
+#### *scopeNode* . **statements** **=>** *Array< [Node](./) >*
+
+The list of child nodes for this scope.
+
+
+
+
+
+-----
+**Content Hash:** 27350094145eafe8e3b166698c29705f2edee81f6126de4e45d957a7c35a7109

docs/api/other/assembly/dialect/README.md

@@ -0,0 +1,145 @@
+-----
+
+Documentation: [html](https://docs-beta.ethers.io/)
+
+-----
+
+Ethers ASM Dialect
+==================
+
+
+This provides a quick, high-level overcview of the **Ethers ASM Dialect**
+for EVM, which is defined by the [Ethers ASM Dialect Grammar](../../../../Users/ricmoo/Development/ethers/ethers.js-v5/https:/github.com/ethers-io/ethers.js/blob/ethers-v5-beta/packages/asm/grammar.jison)
+
+Once a program is compiled by a higher level langauge into ASM (assembly),
+or hand-coded directly in ASM, it needs to be assembled into bytecode.
+
+The assembly process performs a very small set of operations and is
+intentionally simple and closely related to the underlying EVM bytecode.
+
+Operations include embedding programs within programs (for example the
+deployment bootstrap has the runtime embedded in it) and computing the
+necessary offsets for jump operations.
+
+The [Command-Line Assembler](../../../../cli/asm) can be used to assemble an
+*Ethers ASM Dialect* file or to disassemble bytecode into its
+human-readable (ish) opcodes and literals.
+
+
+Opcodes
+-------
+
+
+An **Opcode** may be provided in either a *functional* or
+*instructional* syntax. For Opcodes that require parameters,
+the *functional* syntax is recommended and the *instructional*
+syntax will raise a warning.
+
+@TODO: Examples
+
+
+Labels
+------
+
+
+A **Label** is a position in the program which can be jumped to. A
+`JUMPDEST` is automatically added to this point in the assembled
+output.
+
+@TODO: Exmaples
+
+
+Literals
+--------
+
+
+A **Literal** puts data on the stack when executed using a `PUSH`
+operation.
+
+A **Literal** can be provided using a [DataHexstring](../../../utils/bytes) or a decimal
+byte value.
+
+@TODO: exmples
+
+
+Comments
+--------
+
+
+To enter a comment in the **Ethers ASM Dialect**, any text following
+a semi-colon (i.e. `;`) is ignored by the assembler.
+
+
+Scopes
+------
+
+
+A common case in Ethereum is to have one program embedded in another.
+
+The most common use of this is embedding a Contract **runtime bytecode**
+within a **deployment bytecode**, which can be used as **init code**.
+
+When deploying a program to Ethereum, an **init transaction** is used. An
+*init transaction* has a null `to` address and contains bytecode in
+the `data`. This `data` bytecode is a program, that when executed
+returns some other bytecode as a result, this restul is the bytecode
+to be installed.
+
+Therefore it is important that embedded code uses jumps relative to itself,
+not the entire program it is embedded in, which also means that a jump
+can **only** target its own scope, no parent or child scopes. This is
+enforced by the assembler.
+
+A scope may access the offset of any child [Data Segment](./) or
+child [Scopes](./) (with respect to itself) and may access the length
+of any [Data Segment](./) or [Scopes](./) anywhere in the program.
+
+Every program in the **Ethers ASM Dialect** has a top-leve scope named `_`.
+
+
+Data Segment
+------------
+
+
+A **Data Segment** allows arbitrary data to be embedded into a program,
+which can be useful for lookup tables or deploy-time constants.
+
+An emtpty **Data Segment** can also be used when a labelled location is
+required, but without the `JUMPDEST` which a [Labels](./) adds.
+
+@TODO: Example
+
+
+Links
+-----
+
+
+A **Link** allows access to a [Scopes](./), [Data Segment](./) or [Labels](./).
+
+To access the byte offset of a labelled item, use `$foobar`.
+
+For a [Labels](./), the target must be directly reachable within this scope. For
+a [Data Segment](./) or a [Scopes](./), it can be inside the same scope or any
+child scope.
+
+For a [Data Segment](./) or a [Labels](./), there is an additional type of
+**Link**, which provides the length of the data or bytecode respectively. A
+**Length Link** is accessed by `#foobar` and is pushed on the stack as a
+literal.
+
+
+Stack Placeholders
+------------------
+
+
+@TODO: exampl
+
+
+Evaluation and Excution
+-----------------------
+
+
+
+
+-----
+**Content Hash:** b8f100efb0bd6c794cc6d4ae97c0243e10e6c2fe471cf16ba4e751ed43722bba

docs/api/other/hardware/README.md

@@ -4,7 +4,6 @@ Documentation: [html](https://docs-beta.ethers.io/)
 
 -----
 
-
 Hardware Wallets
 ================
 
@@ -14,7 +13,7 @@ LedgerSigner
 ------------
 
 
-The [Ledger Hardware Wallets](https://www.ledger.com) are a fairly
+The [Ledger Hardware Wallets](../../../Users/ricmoo/Development/ethers/ethers.js-v5/https:/www.ledger.com) are a fairly
 popular brand.
 
 TODO: importing
@@ -35,4 +34,4 @@ determined by the environment; in node the default is "hid" and in the browser
 
 
 -----
-**Content Hash:** 240366cd9757f396d08ed65ebfceafa51f82bfc44c04695ab68e3560e7a0016b
+**Content Hash:** 04412211499f34796f91e7112977e6f84607638be72dc600e488df07c4465805