Updated dist files (remove from beta).

.circleci/config.yml

@@ -1,147 +0,0 @@
-version: 2.1
-
-executors:
-  machine_executor:
-    machine: true
-    working_directory: ~/repo
-
-commands:
-  build-and-test:
-    parameters:
-      node-version:
-        type: string
-        default: "10.16.3"
-      test-script:
-        type: string
-        default: "test-node"
-      upgrade-chrome:
-        type: string
-        default: ""
-
-    steps:
-      - checkout
-
-      - when:
-          condition: << parameters.upgrade-chrome >>
-          steps:
-            - run:
-                name: Upgrade chrome
-                command: |
-                  sudo apt-get purge chromium-browser
-                  sudo apt-get update
-                  sudo apt-get install -y libappindicator1 fonts-liberation
-                  wget https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb
-                  sudo dpkg -i google-chrome*.deb
-                  google-chrome --version
-
-      - run:
-          name: Update C build environment
-          command: |
-            sudo add-apt-repository ppa:ubuntu-toolchain-r/test
-            sudo apt update
-            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: 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: Run << parameters.test-script >> with node version << parameters.node-version >>
-          command: |
-           [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"  # This loads nvm
-           [ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"
-           nvm install << parameters.node-version >>
-           node -v
-           npm -v
-           gcc --version
-           npm ci
-           npm run bootstrap
-           npm run << parameters.test-script >>
-
-jobs:
-  node-v8:
-    description: "test with node version 8"
-    executor: machine_executor
-    steps:
-      - build-and-test:
-          node-version: "8.16.1"
-          test-script: "test-node"
-
-  node-v10:
-    description: "test with node version 10"
-    executor: machine_executor
-    steps:
-      - build-and-test:
-          node-version: "10.16.3"
-          test-script: "test-node"
-
-  node-v12:
-    description: "test with node version 12"
-    executor: machine_executor
-    steps:
-      - build-and-test:
-          node-version: "12.13.1"
-          test-script: "test-node"
-
-  browser-esm:
-    description: "test browser with es6 module"
-    executor: machine_executor
-    steps:
-      - build-and-test:
-          node-version: "12.13.1"
-          test-script: "test-browser-esm"
-          upgrade-chrome: "true"
-
-  browser-umd:
-    description: "test browser with es3 module"
-    executor: machine_executor
-    steps:
-      - build-and-test:
-          node-version: "12.13.1"
-          test-script: "test-browser-umd"
-
-
-workflows:
-  version: 2
-  all:
-    jobs:
-      - node-v8
-      - node-v10
-      - node-v12
-      - browser-esm
-      - browser-umd

.github/workflows/nodejs.yml

@@ -0,0 +1,43 @@
+name: Node.js CI
+
+on:
+  push:
+    branches:
+      - ethers-v5-beta
+
+jobs:
+  test-node:
+
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        node-version: [8.x, 10.x, 12.x, 13.x]
+
+    steps:
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v1
+        with:
+          node-version: ${{ matrix.node-version }}
+      - uses: actions/checkout@v2
+      - run: npm ci
+      - run: npm run bootstrap
+      - run: npm run test-node
+
+  test-browser:
+
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        module: [ 'esm', 'umd' ]
+
+    steps:
+      - uses: actions/setup-node@v1
+        with:
+          node-version: 12.x
+      - uses: actions/checkout@v2
+      - run: npm ci
+      - run: npm run bootstrap
+      - run: npm run test-browser-${{ matrix.module }}
+

CHANGELOG.md

@@ -3,6 +3,135 @@ Changelog
 
 This change log is managed by `scripts/cmds/update-versions` but may be manually updated.
 
+ethers/v5.0.0 (2020-06-12 19:58)
+--------------------------------
+
+  - Preserve config canary string. ([7157816](https://github.com/ethers-io/ethers.js/commit/7157816fa53f660d750811b293e3b1d5a2f70bd4))
+  - Updated docs. ([9e4c7e6](https://github.com/ethers-io/ethers.js/commit/9e4c7e609d9eeb5f2a11d6a90bfa9d32ee696431))
+
+ethers/v5.0.0-beta.192 (2020-06-12 04:51)
+-----------------------------------------
+
+  - Support nonpayable Solidity modifier in ABI. ([adc8d3d](https://github.com/ethers-io/ethers.js/commit/adc8d3d9aec2f5ee8e207f8bc77d99052e473d16))
+  - More debug information in timeout and fetch errors. ([#678](https://github.com/ethers-io/ethers.js/issues/678); [693094e](https://github.com/ethers-io/ethers.js/commit/693094e97ce4f0dc0cd49b9cf6b1557bd7dc517d))
+  - Use URL parse instead of constructor for react compatibility. ([#874](https://github.com/ethers-io/ethers.js/issues/874); [5e7d28b](https://github.com/ethers-io/ethers.js/commit/5e7d28b19b18aa1bbb4b851f74f6d7865725be02))
+
+ethers/v5.0.0-beta.191 (2020-06-03 03:41)
+-----------------------------------------
+
+  - Allow undefined properties in transaction object and fix stray this. ([#860](https://github.com/ethers-io/ethers.js/issues/860); [98bb589](https://github.com/ethers-io/ethers.js/commit/98bb58964bec7dff0ccf481d474354ec1ca6f376), [d2406c4](https://github.com/ethers-io/ethers.js/commit/d2406c42a18c123205918eb46bf24de0ff97ee23))
+  - Allow JsonRpcSigner to override from if it matches Signer. ([#862](https://github.com/ethers-io/ethers.js/issues/862); [1a89c59](https://github.com/ethers-io/ethers.js/commit/1a89c591c26a7fcc2031d0df90137d8a096c5c01))
+  - Added initial support for spontaneous network changes. ([#495](https://github.com/ethers-io/ethers.js/issues/495), [#861](https://github.com/ethers-io/ethers.js/issues/861); [2bc7bb6](https://github.com/ethers-io/ethers.js/commit/2bc7bb6e61219a40cfe2acd95c115c2195c21223), [d2ca4fb](https://github.com/ethers-io/ethers.js/commit/d2ca4fb443b2653063ca5aa349b52ecd0ff79e2f))
+
+ethers/v5.0.0-beta.190 (2020-06-01 05:02)
+-----------------------------------------
+
+  - Re-enable tests removed to fix slow CI. ([cd7a0b3](https://github.com/ethers-io/ethers.js/commit/cd7a0b36cd77df5d5951a97cdb6b6be1c9387f51))
+  - Major Contract refactor for overrides. ([#819](https://github.com/ethers-io/ethers.js/issues/819), [#845](https://github.com/ethers-io/ethers.js/issues/845), [#847](https://github.com/ethers-io/ethers.js/issues/847), [#860](https://github.com/ethers-io/ethers.js/issues/860); [42dee67](https://github.com/ethers-io/ethers.js/commit/42dee67187adb04d0b88f420b24cb3e73301d609))
+  - Remove legacy Circle CI tasks. ([c445232](https://github.com/ethers-io/ethers.js/commit/c445232980007d3474bc036ff59fb37638f93820))
+  - Fixing GitHub actions. ([#853](https://github.com/ethers-io/ethers.js/issues/853); [6b8f0f3](https://github.com/ethers-io/ethers.js/commit/6b8f0f3cb38295cd5d693f9b71f629b591206f1e))
+
+ethers/v5.0.0-beta.189 (2020-05-29 21:25)
+-----------------------------------------
+
+  - Simplify typing for properties module. ([41e66ab](https://github.com/ethers-io/ethers.js/commit/41e66ab834e9835807481658a7956207edfef3d7))
+  - Refactor Contract away from monolithic runMethod. ([e5a1b4d](https://github.com/ethers-io/ethers.js/commit/e5a1b4d5cbbaa0a8ce64c72e13d0d12fa2b856e3))
+  - Correctly set last emitted block for WebSocketProvider. ([#856](https://github.com/ethers-io/ethers.js/issues/856); [1b0ad5a](https://github.com/ethers-io/ethers.js/commit/1b0ad5aa69327f80c7814069142965914673dc06))
+  - Fixed delayed network detection attempting to overwrite read-only value. ([#854](https://github.com/ethers-io/ethers.js/issues/854); [8efd8d2](https://github.com/ethers-io/ethers.js/commit/8efd8d203158ebdef040ec759c3b423312a86e7c))
+  - Better WebSocket compatibilities with Parity. ([#849](https://github.com/ethers-io/ethers.js/issues/849); [180a1af](https://github.com/ethers-io/ethers.js/commit/180a1aff3adc5b4af3a1349b52666ca5942c92a2))
+
+ethers/v5.0.0-beta.188 (2020-05-21 00:02)
+-----------------------------------------
+
+  - Make filter blockHash property name match EIP-234. ([b03c4ed](https://github.com/ethers-io/ethers.js/commit/b03c4edd31a1929b411d0559d17eee7e3d6b11c8), [ed29fac](https://github.com/ethers-io/ethers.js/commit/ed29fac376c1a0aa210bf75979bb2ab62d0cf46b))
+  - Fixed FallbackProvider sync-stalling for backends. ([#841](https://github.com/ethers-io/ethers.js/issues/841); [f963589](https://github.com/ethers-io/ethers.js/commit/f96358940043123aa7a8fe97a1af7af293ce9740))
+  - Add correct tag to release on publish. ([#828](https://github.com/ethers-io/ethers.js/issues/828); [8516076](https://github.com/ethers-io/ethers.js/commit/85160766cdcd031f226382901ebadee9d7f40200))
+
+ethers/v5.0.0-beta.187 (2020-05-12 23:29)
+-----------------------------------------
+
+  - Add sub-error to gas estimate error for Ganache users. ([#829](https://github.com/ethers-io/ethers.js/issues/829); [647fbd8](https://github.com/ethers-io/ethers.js/commit/647fbd8cbfa0f94f72db6faadd528e61c49b1dd6))
+  - Moved ABI check for unique names to coding time and only if ambiguous. ([#816](https://github.com/ethers-io/ethers.js/issues/816); [fa87417](https://github.com/ethers-io/ethers.js/commit/fa87417e9416d99a37d9a2668a1e54feb7e342fc))
+  - Added missing Interface exports to umbrella utils. ([82a9326](https://github.com/ethers-io/ethers.js/commit/82a93263fae330ae39a7212e74d973fa9f820f64))
+  - Fixed FallbackProvider ESM super-this out-of-order issue. ([#822](https://github.com/ethers-io/ethers.js/issues/822); [fde102b](https://github.com/ethers-io/ethers.js/commit/fde102b7eda304403dcc677cd6d3b48339cd3a81))
+  - Fixed node hanging on unnecessary timeout when fetchJson fails. ([fdf2253](https://github.com/ethers-io/ethers.js/commit/fdf2253218cf379043acc32dea8c95c284a82cec))
+
+ethers/v5.0.0-beta.186 (2020-05-08 15:27)
+-----------------------------------------
+
+  - Fix JsonRpcProvider out-of-order super call. ([#822](https://github.com/ethers-io/ethers.js/issues/822); [963197d](https://github.com/ethers-io/ethers.js/commit/963197d70c96e5970b431173c2cc782cb496674c))
+
+ethers/v5.0.0-beta.185 (2020-05-04 22:54)
+-----------------------------------------
+
+  - More robust FallbackProvider on clean exits. ([8eeda23](https://github.com/ethers-io/ethers.js/commit/8eeda23e989fcb0126bd20b17c67f62466d19259))
+  - Safer test suite reporter timer. ([657a039](https://github.com/ethers-io/ethers.js/commit/657a0394f56b51a13c691477c2b0dcf74678fd7c))
+  - Added goerli to AlchemyProvider tests. ([ab7c781](https://github.com/ethers-io/ethers.js/commit/ab7c78118ab80990a3e3368749599a1cf6e9d4ae))
+  - Added more robust poll event to Provider. ([dc48bfb](https://github.com/ethers-io/ethers.js/commit/dc48bfb7adb9334848c93173ba2c634f22a9a72f))
+  - Added goerli to AlchemyProvider. ([86670eb](https://github.com/ethers-io/ethers.js/commit/86670eb80e96fc4ba4e3664c9389f8130bbfea73))
+  - Removed Cloudflare from test suite; it is down again. ([17dc022](https://github.com/ethers-io/ethers.js/commit/17dc022603afdfe4147638ab4b2704bcef09533f))
+  - Prevent forceOutput in test reporter from crashing. ([cafd344](https://github.com/ethers-io/ethers.js/commit/cafd34460b194d78092021f1d7e0307130340b68))
+  - Stall FallbackProvider backends from requests if not in-sync. ([fa6904f](https://github.com/ethers-io/ethers.js/commit/fa6904fef35e7ab888221f3a0613bfe7e6df3594))
+  - Allow providers to detect their network after instantiation. ([#814](https://github.com/ethers-io/ethers.js/issues/814); [99ae946](https://github.com/ethers-io/ethers.js/commit/99ae946476a317a9d89e5d8f57cf37f8680bfa2b))
+  - Better messaging on low-level network errors. ([#814](https://github.com/ethers-io/ethers.js/issues/814); [0e3a66c](https://github.com/ethers-io/ethers.js/commit/0e3a66c82959a08f3f4e4ffbca3ae3792ff2548f))
+  - Manage FallbackProvider stalling without unref. ([#815](https://github.com/ethers-io/ethers.js/issues/815); [7b1a7c7](https://github.com/ethers-io/ethers.js/commit/7b1a7c7f31a3631e12c2a341b562983360e670e9))
+  - Only error on duplicate signatures in Contract ABI. ([#499](https://github.com/ethers-io/ethers.js/issues/499); [098d7ef](https://github.com/ethers-io/ethers.js/commit/098d7efb21bd648c2660342297d2419904a10925))
+  - Added getWebSocketProvider static method to InfuraProvider. ([a6c1174](https://github.com/ethers-io/ethers.js/commit/a6c1174dffe6dca1a3a64d1d472cec6e12372117))
+  - Fix WebSocketProvider responses when message result is null. ([#813](https://github.com/ethers-io/ethers.js/issues/813); [472e5b0](https://github.com/ethers-io/ethers.js/commit/472e5b07eab180baa12185c8f00e5079ce4c671f))
+  - Allow modifiers on Human-Readable ABI for tuples and arrays. ([83fba3d](https://github.com/ethers-io/ethers.js/commit/83fba3de25b524cc48975b1952f4319d63874205))
+  - Added initial renew support to ENS CLI. ([54dfb75](https://github.com/ethers-io/ethers.js/commit/54dfb757c4c88e4bcada1890c4016fadfb25581a))
+  - Allow contract filters to include OR-ed values. ([#437](https://github.com/ethers-io/ethers.js/issues/437); [28800d7](https://github.com/ethers-io/ethers.js/commit/28800d7681f3bab08f6d30a22f0813e04feee18a))
+
+ethers/v5.0.0-beta.184 (2020-04-28 04:58)
+-----------------------------------------
+
+  - Removed old EIP-1193 experimental provider; it can now be supported by Web3Provider as EIP-1193 is now backwards compatible. ([84c68ac](https://github.com/ethers-io/ethers.js/commit/84c68ac5c17b10897ade966d6c8fac1f1f66a4af))
+  - Fixed getLogs filter deserialization. ([#805](https://github.com/ethers-io/ethers.js/issues/805); [393c0c7](https://github.com/ethers-io/ethers.js/commit/393c0c74a91175adca2e25026dcdb9e6445afd8f))
+  - Added EIP-1193 support to Web3Provider. ([56af441](https://github.com/ethers-io/ethers.js/commit/56af4413b1dd1787db68985e0b612b63d86fdf7c))
+  - Minor typing-detected fixes. ([d1f3a42](https://github.com/ethers-io/ethers.js/commit/d1f3a42c119d5588eab667ec7bb6e71042cfb656))
+  - Added initial support for recoverable coding erros. ([#800](https://github.com/ethers-io/ethers.js/issues/800); [bda6623](https://github.com/ethers-io/ethers.js/commit/bda66230916e58e25a522e8430ce4de25091eb6b))
+  - More draconian Typing. ([14e6811](https://github.com/ethers-io/ethers.js/commit/14e6811bf7d7c38a3b5714dededcc883c185d814))
+  - Omit HID libraries for hardware-wallets package on unsupported environments. ([#798](https://github.com/ethers-io/ethers.js/issues/798); [2e24920](https://github.com/ethers-io/ethers.js/commit/2e24920d028d42908d0764ad4ca0b56b55f852d1), [5aefb43](https://github.com/ethers-io/ethers.js/commit/5aefb4303d2fdda62e7e5ddb644919f613d6016a))
+  - Make default constructor non-payable. ([#684](https://github.com/ethers-io/ethers.js/issues/684); [017ea0d](https://github.com/ethers-io/ethers.js/commit/017ea0d6bd22833e9d399ae6b818443786f17884))
+
+ethers/v5.0.0-beta.183 (2020-04-23 23:28)
+-----------------------------------------
+
+  - Fixed inconsistent log format in WebSocketProvider. ([#795](https://github.com/ethers-io/ethers.js/issues/795); [8e7751f](https://github.com/ethers-io/ethers.js/commit/8e7751f7dfb41e58f81c7918cf36c152c3209ae2))
+  - Added WebSocketProvider support for ENS names in filters. ([6707754](https://github.com/ethers-io/ethers.js/commit/6707754580490c5a801d6205af0841794d20b3c9))
+  - Fixed provider filtering by ENS name. ([aeeb75f](https://github.com/ethers-io/ethers.js/commit/aeeb75f74c3be11b9b3b2925fd73349070542e54))
+  - Fixed ContractFactory.deploy ignoring overrides. ([#796](https://github.com/ethers-io/ethers.js/issues/796); [8bb2a0f](https://github.com/ethers-io/ethers.js/commit/8bb2a0fd08f6f128a80444e3fd90c29e4cd7edfb))
+  - Fix median calculation for large block number deltas across FallbackProvider backends. ([fca5ccb](https://github.com/ethers-io/ethers.js/commit/fca5ccbc2052569e700a96dbb1de1c9cef7c966f))
+  - Work-around for Cloudflare not offering eth_blockNumber. ([8cf4b3c](https://github.com/ethers-io/ethers.js/commit/8cf4b3cf4598f4f3643d5ebe9c366466d398cb83))
+  - Added string spell-checking to library and fixed discovered typos. ([71d03c6](https://github.com/ethers-io/ethers.js/commit/71d03c6e3cab1aacb3e4e74d3966fbaa7db2ee06))
+  - Fixed getUrl for node 8. ([560adea](https://github.com/ethers-io/ethers.js/commit/560adeabb06a2ab483bcad162f02ccef41ebc245))
+  - Dependency security updates. ([da3b0bf](https://github.com/ethers-io/ethers.js/commit/da3b0bf0786fe8a95c68485d130ca59c597ffe4d))
+  - Fixes for dist builds without injected XMLHttpRequest. ([#789](https://github.com/ethers-io/ethers.js/issues/789), [#506](https://github.com/ethers-io/ethers.js/issues/506); [9ae6b70](https://github.com/ethers-io/ethers.js/commit/9ae6b70efb9f3d3251820403597085cfa30ace05))
+
+ethers/v5.0.0-beta.182 (2020-04-16 21:53)
+-----------------------------------------
+
+  - Added support for Contract event parsing error recovery. ([cc72f76](https://github.com/ethers-io/ethers.js/commit/cc72f76695572d235d7f5a5ad4dc1838a5fe884a))
+  - Fix provider log filters with zero topics. ([#785](https://github.com/ethers-io/ethers.js/issues/785); [4ef0e4f](https://github.com/ethers-io/ethers.js/commit/4ef0e4f7653226bf8cca86e065ad614e7288af96))
+
+ethers/v5.0.0-beta.181 (2020-04-15 18:23)
+-----------------------------------------
+
+  - Temporarily remove CloudflareProvider tests; it is down and breaking the tests. ([797abb7](https://github.com/ethers-io/ethers.js/commit/797abb726711499d96bf1c12c61e3bb1a7b4925d))
+  - Better error reporting for Fragments. ([7dcefcb](https://github.com/ethers-io/ethers.js/commit/7dcefcbf71ef337103639bbe3f4ad2625565651a))
+  - Fixed Contract filter unsubscribing. ([2eb3823](https://github.com/ethers-io/ethers.js/commit/2eb3823de4ba111cc0c746a0715fe6dd3d1b16da), [39c78f3](https://github.com/ethers-io/ethers.js/commit/39c78f37ceff9b8ec08329903dcba7bd53bd8661))
+  - Fixed WebSocketProvider filter events. ([#784](https://github.com/ethers-io/ethers.js/issues/784); [69f7077](https://github.com/ethers-io/ethers.js/commit/69f707762ed5939c5f52bf6dce5c5513aaf6fa1d))
+  - Added bitwise operations to BigNumber. ([#781](https://github.com/ethers-io/ethers.js/issues/781); [7498c18](https://github.com/ethers-io/ethers.js/commit/7498c18235c7566b2f652cddba991f55e0943da8), [284771e](https://github.com/ethers-io/ethers.js/commit/284771ea39b6f4ee9cdf75ce5feea9e6aa9a65c5))
+
+ethers/v5.0.0-beta.180 (2020-04-03 22:10)
+-----------------------------------------
+
+  - Correctly return the Provider in NonceManager. ([6caf7c2](https://github.com/ethers-io/ethers.js/commit/6caf7c292cd5f03741cd6b30053c3325c4f30a81))
+  - Fail earlier when resolving an ENS name that is not a string. ([2882546](https://github.com/ethers-io/ethers.js/commit/28825463517f8821392464ec2283ee59c431d928))
+  - Fixed mutabilityState calculation for function fragments. ([#762](https://github.com/ethers-io/ethers.js/issues/762); [6526de0](https://github.com/ethers-io/ethers.js/commit/6526de016fda5403474dad61ee59acc62ee25ebc), [d7c8b35](https://github.com/ethers-io/ethers.js/commit/d7c8b355a049b36068b0525a357c6278639a8d58))
+  - Force Log properties to be non-optional. ([#415](https://github.com/ethers-io/ethers.js/issues/415); [da412f6](https://github.com/ethers-io/ethers.js/commit/da412f660723d1c411484e74970ce4eb166374c2), [8ad26f0](https://github.com/ethers-io/ethers.js/commit/8ad26f0ff42614a6c40e735cb6fffd36874da1a0))
+  - Fixed Signer call not forwarding blockTag. ([#768](https://github.com/ethers-io/ethers.js/issues/768); [053a2d7](https://github.com/ethers-io/ethers.js/commit/053a2d7fcdb4ca4c9bfd0bee0f42e0187d3db477))
+
 ethers/v5.0.0-beta.179 (2020-03-31 23:40)
 -----------------------------------------
 
@@ -168,8 +297,8 @@ ethers/v5.0.0-beta.163 (2020-01-06 18:57)
   - Add circleci and parity test files ([fdf0980](https://github.com/ethers-io/ethers.js/commit/fdf0980663ffead0faf3e9b7b233b22ca1574e21))
   - Fixed typo in package test dist scripts. ([9c78c7f](https://github.com/ethers-io/ethers.js/commit/9c78c7fee69d07733048d898d58205ae7f5c82d7))
 
-ethers/v5.0.0-beta.162 (2019-11-25 0:02)
-----------------------------------------
+ethers/v5.0.0-beta.162 (2019-11-25 00:02)
+-----------------------------------------
 
   - Update elliptic package to protect from Minerva timing attack. ([#666](https://github.com/ethers-io/ethers.js/issues/666); [cf036e1](https://github.com/ethers-io/ethers.js/commit/cf036e1ffad3340fcf1c7559d0032493ccc08e6e))
   - Browser and node testing works again. ([4470477](https://github.com/ethers-io/ethers.js/commit/4470477d7fd3031f2f3a1fbd9c538468c33c7350))

README.md

@@ -1,17 +1,35 @@
 The Ethers Project
 ==================
 
-**EXPERIMENTAL**
+[![npm (tag)](https://img.shields.io/npm/v/ethers/next)](https://www.npmjs.com/package/ethers/v/next)
+[![Node.js CI](https://github.com/ethers-io/ethers.js/workflows/Node.js%20CI/badge.svg?branch=ethers-v5-beta)](https://github.com/ethers-io/ethers.js/actions?query=workflow%3A%22Node.js+CI%22)
 
-This branch is the next release of ethers.js, which should
-be promoted to the official release shortly.
+A complete Ethereum wallet implementation and utilities in JavaScript (and TypeScript).
 
-I would recommend it for most new projects and personally use
-it for my own projects.
+**Features:**
 
-The [new documentation](https://docs-beta.ethers.io) is still a
-bit sparse, but is coming along as well and will be complete
-before the promotion to master.
+- Keep your private keys in your client, **safe** and sound
+- Import and export **JSON wallets** (Geth, Parity and crowdsale)
+- Import and export BIP 39 **mnemonic phrases** (12 word backup phrases) and **HD Wallets** (English as well as Czech, French, Italian, Japanese, Korean, Simplified Chinese, Spanish, Traditional Chinese)
+- 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), [Alchemy](https://alchemyapi.io) or [MetaMask](https://metamask.io)
+- **ENS names** are first-class citizens; they can be used anywhere an Ethereum addresses can be used
+- **Tiny** (~104kb compressed; 322kb uncompressed)
+- **Modular** packages; include only what you need
+- **Complete** functionality for all your Ethereum desires
+- Extensive [documentation](https://docs.ethers.io/ethers.js/html/)
+- 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
+
+
+Keep Updated
+------------
+
+For the latest news and advisories, please follow the [@ethersproject](https://twitter.com/ethersproject)
+on Twitter (low-traffic, non-marketting, important information only) as well as watch this GitHub project.
+
+For the latest changes, see the [CHANGELOG](https://github.com/ethers-io/ethers.js/blob/master/CHANGELOG.md).
 
 
 Installing
@@ -39,10 +57,22 @@ Installing
 ```
 
 
+Documentation
+-------------
+
+Browse the documentation online:
+
+- [Getting Started](https://docs.ethers.io/)
+- [Full API Documentation](https://docs.ethers.io/)
+- [Various Ethereum Articles](https://blog.ricmoo.com/)
+
+Or browser the entire documentations as a [single page](https://docs.ethers.io/single-page/).
+
+
 Ancillary Packages
 ------------------
 
-These are a number of packages not included in the umbrella `ethers ` npm package, and
+These are a number of packages not included in the umbrella `ethers` npm package, and
 additional packages are always being added. Often these packages are for specific
 use-cases, so rather than adding them to the umbrella package, they are added as
 ancillary packaged, which can be included by those who need them, while not bloating
@@ -50,46 +80,9 @@ everyone else with packages they do not need.
 
 We will keep a list of useful pacakges here.
 
-- `@ethersproject/experimental`
-- `@ethersproject/cli`
-- `@ethersproject/ens`
-- `@ethersproject/ledger`
-- `@ethersproject/trezor`
-
-
-Hacking
--------
-
-This project uses a combination of Lerna and the ./admin scripts to manage
-itself as a package of packages.
-
-The umbrella package can be found in `packages/ethers`, and all packages in general
-can be found in the `packages/` folder.
-
-If you add new dependencies to any package (incuding internal dependencies), you will
-need to re-create the internal links and re-build teh dependency graph::
-
-```
-/home/ethers> npm run bootstrap
-```
-
-To run a continuous build (with incremental TypeScript compilation):
-
-```
-/home/ethers> npm run auto-build
-```
-
-Finally, once you have made all your changes, you will need to bump the version
-of packages that changed their NPM tarballs, as well as update the _version.*
-and distribution builds (which is what we host on the CDN for browser-based
-apps). To do this, run:
-
-
-```
-/home/ethers> npm run update-versions
-```
-
-Which will also list all packages that have changed along with the specifc files.
+- `@ethersproject/experimental` ([documentation](https://docs.ethers.io))
+- `@ethersproject/cli` ([documentation](https://docs.ethers.io))
+- `@ethersproject/hardware-wallets` ([documentation](https://docs.ethers.io))
 
 
 License

admin/build.js

@@ -49,13 +49,6 @@ function run(progname, args, ignoreErrorStream) {
 }
 
 function setupConfig(outDir, moduleType, targetType) {
-    function update(value) {
-        let comps = value.split("/");
-        if (comps.length >= 3 && comps[0] === "." && comps[1].match(/^lib(\.esm)?$/)) {
-            return outDir + comps.slice(2).join("/");
-        }
-        return value;
-    }
 
     // Configure the tsconfit.package.json...
     const path = resolve(__dirname, "../tsconfig.package.json");
@@ -64,22 +57,24 @@ function setupConfig(outDir, moduleType, targetType) {
     content.compilerOptions.target = targetType;
     saveJson(path, content);
 
+    // Configure the browser field for every pacakge, copying the
+    // browser.umd filed for UMD and browser.esm for ESM
     dirnames.forEach((dirname) => {
         let info = loadPackage(dirname);
 
         if (info._ethers_nobuild) { return; }
 
-        [ "browser", "_browser" ].forEach((key) => {
-            if (info[key]) {
-                if (typeof(info[key]) === "string") {
-                    info[key] = update(info[key]);
-                } else {
-                    for (let k in info[key]) {
-                        info[key][k] = update(info[key][k]);
-                    }
-                }
+        if (targetType === "es2015") {
+            if (info["browser.esm"]) {
+                info.browser = info["browser.esm"];
             }
-        });
+        } else if (targetType === "es5") {
+            if (info["browser.umd"]) {
+                info.browser = info["browser.umd"];
+            }
+        } else {
+            throw new Error("unsupported target");
+        }
         savePackage(dirname, info);
 
         let path = resolve(__dirname, "../packages", dirname, "tsconfig.json");

admin/cmds/publish.js

@@ -2,8 +2,9 @@
 
 const config = require("../config");
 
-const { latestChange } = require("../changelog");
+const { ChangelogPath, latestChange } = require("../changelog");
 const { getOrdered, loadPackage } = require("../depgraph");
+const { getGitTag } = require("../git");
 const { createRelease } = require("../github");
 const { getPackageVersion, publish } = require("../npm");
 const { log } = require("../log");
@@ -35,6 +36,8 @@ if (process.argv.length > 2) {
 (async function() {
     let token = null;
 
+    const gitCommit = await getGitTag(ChangelogPath);
+
     let includeEthers = false;
 
     // @TODO: Fail if there are any untracked files or unchecked in files
@@ -107,8 +110,8 @@ if (process.argv.length > 2) {
         const change = latestChange();
 
         // Publish the release
-        const link = await createRelease(username, password, change.version, change.title, change.content, beta);
-        log(`<bold:Published Release:> ${ link }...`);
+        const link = await createRelease(username, password, change.version, change.title, change.content, beta, gitCommit);
+        log(`<bold:Published Release:> ${ link }`);
     }
 
 })();

admin/cmds/set-option.js

@@ -4,39 +4,32 @@ const { loadPackage, savePackage } = require("../local");
 const arg = process.argv[2];
 
 (async function() {
-    switch(arg) {
-        case "esm":
-            setupBuild(true);
-            break;
+    process.argv.slice(2).forEach((arg) => {
+        console.log("Setting Option:", arg);
+        switch(arg) {
+            case "esm":
+                setupBuild(true);
+                break;
 
-        case "cjs":
-            setupBuild(false);
-            break;
+            case "cjs":
+                setupBuild(false);
+                break;
 
-        case "browser-lang-en": {
-            const info = loadPackage("wordlists");
-            if (info._browser) {
-                info.browser = info._browser;
-                delete info._browser;
-                savePackage("wordlists", info);
-            }
-            break;
-        }
-
-        case "browser-lang-all": {
-            const info = loadPackage("wordlists");
-            if (info.browser) {
-                info._browser = info.browser;
+            // This will remove the browser field entirely, so make sure
+            // to set esm of cjs first as they will restore the browser
+            // field
+            case "browser-lang-all": {
+                const info = loadPackage("wordlists");
                 delete info.browser;
                 savePackage("wordlists", info);
+                break;
             }
-            break;
-        }
 
-        default:
-            console.log("unknown option");
-            return 1;
-    }
+            default:
+                console.log("Unknown option:", arg);
+                return 1;
+      }
+    });
     return 0;
 
 })().then((result) => {

admin/cmds/spell-check.js

@@ -0,0 +1,210 @@
+"use strict";
+
+const { resolve } = require("path");
+const fs = require("fs");
+
+const Words = fs.readFileSync("/usr/share/dict/words").toString().split("\n").reduce((accum, word) => {
+    accum[word.toLowerCase()] = true;
+    return accum;
+}, { });
+
+`
+// Words missing from the dictionary
+accessing addresses aligned autofill called cancelled changed censored
+compiled computed configured consumed creating decoded decoding
+decrypt decrypted decrypting deployed deploying deprecated detected
+discontinued earliest email enabled encoded encoding encrypt
+encrypted encrypting entries euro exceeded existing expected
+expired failed fetches formatted formatting funding generated
+has ignoring implemented implementer imported including instantiate
+keyword labelled larger lookup matches mined modified modifies multi
+named needed nested neutered numeric offline optimizer overriding owned packed
+padded parsed parsing passed placeholder processing reached
+recommended recovered redacted remaining replaced required
+serializes shared signed signing skipped stored supported tagging targetted
+transactions uninstall unstake unsubscribe using verifies website
+
+// Overly Specific Words
+BIP BIP39 BIP44 crypto eip hashes hmac icap
+keccak namehash ripemd RLP scrypt secp sha
+
+blockhash
+
+bitcoin ethereum finney gwei kwei mwei satoshi szabo wei weth
+
+crowdsale hexlify hd hdnode underpriced
+
+boolean int struct tuple uint
+nonpayable
+jumpdest mstore shr shl xor
+
+// Classes
+ABIEncoder testcase numberish Wordlist
+
+// Common Code Strings
+abi addr api app arg arrayify asm basex bigint bn byte bytecode
+callback calldata checksum ciphertext cli codepoint config
+contenthash ctr ctrl debug dd dklen eexist encseed eof ethaddr
+ethseed ethers eval exec filename func gz hid http https hw iv
+info init ipc json kdf kdfparams labelhash lang lib mm multihash nfc
+nfkc nfd nfkd nodehash nullish oob opcode pbkdf pc plugin pragma pre prf
+repl rpc sighash topichash solc stdin stdout subclasses subnode
+timeout todo txt ufixed utc utf util url uuid vm vs websocket
+wikipedia wx xe yyyy zlib
+
+// AbiV2
+abiv
+
+// Query parameters
+apikey asc endblock startblock
+
+Cloudflare Etherscan INFURA IPFS MetaMask Nodesmith Trezor ledgerhq
+axic bitcoinjs browserify easyseed ethereumjs
+goerli homestead kotti kovan mainnet morden mordor rinkeby ropsten testnet
+
+// Demo words
+args foo eth foo foobar ll localhost passwd ricmoo tx xxx yna
+
+// nameprep tags
+ALCat BiDi LCat nameprep
+
+// Lanauge Codes (and short binary data)
+cn cz en es fr it ja tw zh zh_cn zh_tw
+OYAa IJBEJqXZJ
+
+`.split("\n").filter((l) => (l.substring(0, 2) != "/\/")).join("\n").split(/\s+/g,).forEach((word) => {
+    word = word.trim();
+    if (word === "") { return; }
+    Words[word.toLowerCase()] = true;
+});
+
+const ts = require("typescript");
+
+function getStrings(source) {
+    const sourceFile = ts.createSourceFile("filename.ts", source);
+
+    const result = [ ];
+
+    function add(value, pos) {
+        const lineNo = sourceFile.getLineAndCharacterOfPosition(pos).line + 1;
+        result.push({ value, lineNo });
+    }
+
+    let lastClass = null, lastEnum = null;
+    function visit(node, depth) {
+        switch (node.kind) {
+            //case ts.SyntaxKind.TemplateExpression:
+            //    if (node.head) { visit(node.head); }
+            //    console.dir(node, { depth: null });
+            //    break;
+            case ts.SyntaxKind.TemplateHead:
+            case ts.SyntaxKind.TemplateMiddle:
+            case ts.SyntaxKind.TemplateTail:
+            case ts.SyntaxKind.StringLiteral:
+            case ts.SyntaxKind.NoSubstitutionTemplateLiteral:
+                add(node.text, node.pos);
+                break;
+        }
+
+        ts.forEachChild(node, (node) => { return visit(node, depth + 1); });
+    }
+
+    visit(sourceFile, 0);
+
+    return result;
+}
+
+const Include = new RegExp("packages/.*/src.ts/.*\.ts$");
+const Exclude = new RegExp("/node_modules/|src.ts/.*browser.*");
+
+function getAllStrings(path) {
+    const Root = resolve(__dirname, path);
+
+    const readdir = function(path) {
+        if (path.match(Exclude)) { return [ ]; }
+
+        const stat = fs.statSync(path);
+        if (stat.isDirectory()) {
+            return fs.readdirSync(path).reduce((result, filename) => {
+                readdir(resolve(path, filename)).forEach((file) => {
+                    result.push(file);
+                });
+                return result;
+            }, [ ]);
+        }
+
+        if (path.match(Include)) {
+            const source = fs.readFileSync(path).toString();
+            return [ { filename: path.substring(Root.length), values: getStrings(source) } ]
+        }
+
+        return [ ];
+    }
+
+    return readdir(Root);
+}
+
+function checkWord(word) {
+    word = word.toLowerCase();
+
+    // A word
+    if (Words[word]) { return true; }
+
+    // Simple Plural
+    if (word.match(/.*s$/) && Words[word.substring(0, word.length - 1)]) { return true; }
+
+    // Hex string
+    if (word.match(/^(0x)?[0-9a-f]*$/i)) { return true; }
+}
+
+function starts(text, prefix) {
+    return (text.substring(0, prefix.length) === prefix);
+}
+
+(async function() {
+    let count = 0;
+    getAllStrings(resolve(__dirname, "../../packages")).forEach((file) => {
+        if (starts(file.filename, "/testcases/src.ts/generation-scripts")) { return; }
+        if (starts(file.filename, "/asm/src.ts/opcodes.ts")) { return; }
+
+        file.values.forEach((entry) => {
+            function problem(word) {
+                count++;
+                console.log({
+                    filename: file.filename,
+                    word: JSON.stringify(word),
+                    sentence: JSON.stringify(entry.value.substring(0, 80)),
+                    line: entry.lineNo
+                });
+            }
+
+            const value = entry.value.trim();
+
+            // Emptry space
+            if (value === "") { return; }
+
+            // Prolly a require
+            if (value.match(/^@ethersproject\/[a-z0-9-]+$/)) { return; }
+            if (value.substring(0, 2) === "./") { return; }
+
+            // Prolly encoded binary data
+            if (value.indexOf(" ") === -1 && value.length > 20) { return; }
+
+            if (checkWord(value)) { return; }
+
+            value.replace(/([a-z+])([A-Z])/g, (all, first, secondLetter) => {
+                return first + " " + secondLetter;
+            }).replace(/((?:0x)?[A-Za-z]+)/gi, (all, word) => {
+                if (checkWord(word)) { return; }
+                problem(word);
+                return "";
+            });;
+        });
+    });
+    if (count) {
+        console.log(`Found ${ count } typos.`);
+        process.exit(1)
+    }
+    process.exit(0)
+})();
+

admin/cmds/upload-docs.js

@@ -3,13 +3,12 @@
 const crypto = require('crypto');
 const fs = require('fs');
 const path = require('path');
-
 const AWS = require('aws-sdk');
 
 const config = require("../config");
 
 
-const Bucket = "docs-beta.ethers.io";
+const Bucket = "docs.ethers.io";
 
 
 function _getKeys(s3, result, nextToken, callback) {
@@ -86,7 +85,7 @@ function putObject(s3, name, content) {
             if (error) {
                 reject(error);
             } else {
-                console.log('Uplodaed:', name)
+                console.log("  Done.")
                 resolve({
                     name: name,
                     hash: data.ETag.replace(/"/g, '')
@@ -118,12 +117,18 @@ function _getFiles(result, root) {
     });
 }
 
-function getFiles(dirs) {
-    const result = { } //"index.html": hash("index.html") };
-    dirs.forEach(function(dir) {
-        _getFiles(result, dir);
-    })
-    return result;
+function getFiles(basedir) {
+    // Make sure we have a trailing slash
+    if (!basedir.match(/\/$/)) { basedir += "/"; }
+
+    // Fetch all the file hashes
+    const hashes = { };
+    _getFiles(hashes, basedir);
+
+    return Object.keys(hashes).reduce((accum, key) => {
+        accum[key.substring(basedir.length)] = hashes[key];
+        return accum;
+    }, { });
 }
 
 (async function() {
@@ -138,7 +143,9 @@ function getFiles(dirs) {
 
     const added = [], removed = [], changed = [], upload = [];
 
-    const local = await getFiles([ "docs" ]);
+    const basedir = path.resolve(__dirname, "../../docs");
+
+    const local = await getFiles(basedir);
     const remote = await getKeys(s3);
 
     Object.keys(local).forEach((filename) => {
@@ -166,7 +173,8 @@ function getFiles(dirs) {
 
     for (let i = 0; i < upload.length; i++) {
         const filename = upload[i];
-        console.log("Uploading:", filename);
-        await putObject(s3, filename, fs.readFileSync(filename));
+        const content = fs.readFileSync(path.resolve(basedir, filename));
+        console.log(`Uploading: ${ filename } (${ content.length } bytes)`);
+        await putObject(s3, filename, content);
     }
 })();

admin/config.js

@@ -22,6 +22,7 @@ function Config(filename) {
     this.salt = null;
     this.dkey = null;
     this.values = { };
+    this.canary = "";
     this.filename = filename;
 }
 
@@ -37,6 +38,8 @@ Config.prototype.load = async function() {
         };
     }
 
+    this.canary = data.canary || "";
+
     this.salt = data.salt;
 
     const password = await prompt.getPassword(colorify("Password (config-store): ", "bold"));
@@ -77,7 +80,8 @@ Config.prototype.save = function() {
         ciphertext: ciphertext.toString("base64"),
         iv: iv.toString("base64"),
         salt: this.salt,
-        hmac: hmac
+        hmac: hmac,
+        canary: this.canary
     };
 
     fs.writeFileSync(this.filename, JSON.stringify(data, null, 2));

admin/github.js

@@ -107,7 +107,7 @@ async function fetchGitHub(user, password, url, cacheOnly) {
 async function _getIssues(user, password) {
     const cacheOnly = (user == null);
 
-    let issues = await fetchGitHub(user, password, "https://api.github.com/repos/ethers-io/ethers.js/issues?state=all&per_page=100", cacheOnly)
+    let issues = await fetchGitHub(user, password, "https:/\/api.github.com/repos/ethers-io/ethers.js/issues?state=all&per_page=100", cacheOnly)
     if (!cacheOnly) { console.log(`Found ${ issues.length } issues`); }
     const result = [ ];
     for (let i = 0; i < issues.length; i++) {

docs.wrm/.gitignore

@@ -0,0 +1 @@
+**.bak

docs.wrm/README.md

@@ -11,6 +11,13 @@ Building
 --------
 
 ```
-/home/ricmoo/ethers.js> npm run build-docs 
+/home/ricmoo/ethers.js> npm run build-docs
 ```
 
+
+License
+-------
+
+All documentation for ethers.js and Flatworm is released under the
+[Creative Commons Attribution 4.0 International License](https://choosealicense.com/licenses/cc-by-4.0/)
+license.

docs.wrm/api/contract/contract-factory.wrm

@@ -0,0 +1,78 @@
+_section: ContractFactory @<ContractFactory> @SRC<contracts:class.ContractFactory>
+
+@TODO: Fill this in, including @SRC links
+
+_subsection: Creating Instances  @<ContractFactory--creating>
+
+_property: new ethers.ContractFactory(interface, bydecode [ , signer ]) @SRC<contracts:constructor.ContractFactory>
+
+_property: ContractFactory.fromSolidity(compilerOutput [ , signer ]) => [[ContractFactory]]
+
+_property: contractFactory.connect(signer) => [[Contract]] @<ContractFactory-connect>
+
+
+_subsection: Properties  @<ContractFactory--properties>
+
+_property: contractFactory.interface => [[Interface]]
+
+_property: contractFactory.bytecode => string<[[DataHexString]]>
+
+_property: contractFactory.signer => [[Signer]]
+
+
+_subsection: Methods  @<ContractFactory--methods>
+
+_property: contractFactory.attach(address) => [[Contract]] @<ContractFactory-attach>
+
+Return an instance of a [[Contract]] attched to //address//. This is the
+same as using the [Contract constructor](Contract--creating) with
+//address// and this the the //interface// and //signerOrProvider// passed
+in when creating the ContractFactory.
+
+_property: contractFactory.getDeployTransaction(...args) => [[UnsignedTransaction]]
+
+Returns the unsigned transaction which would deploy this Contract with //args// passed
+to the Contract's constructor.
+
+_property: contractFactory.deploy(...args) => Promise<[[Contract]]> @<ContractFactory-deploy>
+
+Uses the signer to deploy the Contract with //args// passed into tgee constructor and
+retruns a Contract which is attached to  the address where this contract **will** be
+deployed once the transction is mined.
+
+The transction can be found at ``contract.deployTransaction``, and no interactions
+should be made until the transaction is mined.
+
+_code: Deploying a Contract
+
+// <hide>
+const signer = ethers.LocalSigner();
+const ContractFactory = ethers.ContractFactory;
+// </hide>
+
+// If your contract constructor requires parameters, the ABI
+// must include the constructor
+const abi = [
+  "constructor(address owner, uint256 initialValue)"
+];
+
+const factory = new ContractFactory(abi, bytecode, signer)
+
+const contract = await factory.deploy("ricmoo.eth", 42);
+
+// The address is available immediately, but the contract
+// is NOT deployed yet
+contract.address
+//!
+
+// The transaction that the signer sent to deploy
+contract.deployTransaction
+//!
+
+// Wait until the transaction is mined
+contract.deployTransaction.wait()
+//!
+
+// Now the contract is safe to ineract with
+contract.value()
+//!

docs.wrm/api/contract/contract.wrm

@@ -1,82 +1,89 @@
-_section: Contract @<contract> @SRC<contracts:class.Contract>
+_section: Contract @<Contract> @SRC<contracts:class.Contract>
 
-_subsection: Properties
+Explain contract here...
 
-_property: contract.address => string<[[address]]>
-This is the address (or ENS name) the contract was constructed with.
+_subsection: Creating Instances @<Contract--creating>
 
-_property: contract.addressPromise => string<[[address]]>
-This is a promise that will resolve to the address the **Contract**
-object is attached to. If an [[address]] was provided to the constructor,
-it will be equal to this; if an ENS name was provided, this will be the
-resolved address.
+_property: new ethers.Contract(address, abi, signerOrProvider) @src<contracts:constructor.Contract>
 
-_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>
+_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>
+_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
+By passing in a [[Provider]], this will return a downgraded
 **Contract** which only has read-only access (i.e. constant calls).
 
-By passing in a [[signer]]. the will return a **Contract** which
+By passing in a [[Signer]]. the will return a **Contract** which
 will act on behalf of that signer.
 
-_property: contract.deployed() => Promise<[[contract]]>  @<contract-deployed> @SRC<contracts>
 
-_property: Contract.isIndexed(value) => boolean  @<contract-isIndexed> @SRC<contracts>
+_subsection: Properties  @<Contract--properties>
+
+_property: contract.address => string<[[address]]>
+This is the address (or ENS name) the contract was constructed with.
+
+_property: contract.resolvedAddress => string<[[address]]>
+This is a promise that will resolve to the address the **Contract**
+object is attached to. If an [[address]] was provided to the constructor,
+it will be equal to this; if an ENS name was provided, this will be the
+resolved address.
+
+_property: contract.deployTransaction => [[providers-TransactionResponse]]
+If the **Contract** object is the result of a ContractFactory deployment,
+this is the transaction which was used to deploy the contract.
+
+_property: contract.interface => [[Interface]]
+This is the ABI as an [[Interface]].
+
+_property: contract.provider => [[Provider]]
+If a provider was provided to the constructor, this is that provider. If
+a signer was provided that had a [[Provider]], this is that provider.
+
+_property: contract.signer => [[Signer]]
+If a signer was provided to the constructor, this is that signer.
 
 
-_subsection: Events
+_subsection: Methods @<Contract--methods>
 
-_property: contract.queryFilter(event [ , fromBlockOrBlockHash [ , toBlock ]) => Promise<Array<Event>> @<contract-queryfilter> @SRC<contracts>
+_property: contract.deployed() => Promise<[[Contract]]>  @<Contract-deployed> @SRC<contracts>
+
+_property: Contract.isIndexed(value) => boolean  @<Contract-isIndexed> @SRC<contracts>
+
+
+_subsection: Events @<Contract--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>
+_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>
+_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>
+_property: contract.off(event, listener) => this  @<Contract-off> @SRC<contracts>
 Unsubscribe //listener// to //event//.
 
-_property: contract.on(event, listener) => this  @<contract-on> @SRC<contracts>
+_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>
+_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>
+_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>
+_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
@@ -85,7 +92,7 @@ describe the generic ways to interact with the properties added
 at run-time during the **Contract** constructor.
 
 
-_heading: Read-Only Methods (constant)  @<contract-readonly>
+_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
@@ -93,7 +100,7 @@ asking a single node, which can return a result. It is therefore
 free and does not require any ether, but **cannot make changes** to
 the blockchain state..
 
-_property: contract.METHOD_NAME(...args [ overrides ]) => Promise<any>  @<contract-call>
+_property: contract.METHOD_NAME(...args [, overrides ]) => Promise<any>  @<Contract-functionsCall>
 The type of the result depends on the ABI.
 
 For values that have a simple meaning in JavaScript, the types are fairly
@@ -102,12 +109,28 @@ and booleans.
 
 For numbers, if the **type** is in the JavaSsript safe range (i.e. less
 than 53 bits, such as an ``int24`` or ``uint48``) a normal JavaScript
-number is used. Otherwise a [[bignumber]] is returned.
+number is used. Otherwise a [[BigNumber]] is returned.
 
-For bytes (both fixed length and dynamic), a [[datahexstring]] is returned.
+For bytes (both fixed length and dynamic), a [[DataHexString]] is returned.
 
+_property: contract.functions.METHOD_NAME(...args [, overrides ]) => Promise<[[Result]]>
 
-_heading: Write Methods (non-constant) @<contract-write>
+The result will always be a [[Result]], even if there is only a single
+return value type.
+
+This simplifies frameworks which wish to use the [[Contract]] object,
+since they do not need to inspect the return types to unwrap simplified
+functions.
+
+Another use for this method is for error recovery. For example, if a
+function result is an invalid UTF-8 string, the normal call using the
+above meta-class function will throw an exception. This allows using the
+Result access error to access the low-level bytes and reason for the error
+allowing an alternate UTF-8 error strategy to be used.
+
+Most developers should not require this.
+
+_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
@@ -119,25 +142,25 @@ 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
+_property: contract.METHOD_NAME(...args [ , overrides ]) => Promise<[[providers-TransactionResponse]]>  @<contract-functionsSend>
+Returns a [[providers-TransactionResponse]] for the transaction after
 it is sent to the network. This requires the **Contract** has a
 signer.
 
 
-_heading: Write Methods Analysis @<contract-write-check>
+_heading: Write Methods Analysis @<Contract--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>
+_property: contract.estimateGas.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
+_property: contract.populateTransaction.METHOD_NAME(...args [ , overrides ]) => Promise<[UnsignedTx](UnsignedTransaction)>  @<contract-populateTransaction>
+Returns an [[UnsignedTransaction]] which represents the transaction
 that would need to be signed and submitted to the network to execute
-//METHOD_NAME// with //args/ and //overrides//.
+//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
@@ -147,9 +170,9 @@ return the result.
 This does not actually chagne any state, but is free. This in some cases
 can be used to determine if a transaction will fail or succeed.
 
-This otherwise functions the same as a [Read-Only Method](contract-readonly).
+This otherwise functions the same as a [Read-Only Method](Contract--readonly).
 
-_heading: Event Filters @<contract-filter>
+_heading: Event Filters @<Contract--filters>
 An event filter is made up of topics, which are values logged in a
 [[link-wiki-bloomfilter]], allowing efficient searching for entries
 which match a filter.

docs.wrm/api/contract/example.wrm

@@ -2,10 +2,46 @@ _section: Example: ERC-20 Contract
 
 _subsection: Connecting to a Contract
 
-_code: token.txt
+_code: A simple ERC-20 contract @lang<javascript>
+
+// 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 = "dai.tokens.ethers.eth";
+
+// An example Provider
+const provider = ethers.getDefaultProvider();
+
+// An example Signer
+const signer = ethers.Wallet.createRandom().connect(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)
 
 
-_heading: ERC20Contract @INHERIT<[[contract]]>
+_heading: ERC20Contract @INHERIT<[[Contract]]>
 
 _property: new ethers.Contract(address, abi, providerOrSigner)
 See the above code example for creating an Instance which will
@@ -14,48 +50,48 @@ add the additional properties defined in //abi// to a **Contract**
 connected to //address// using the //providerOrSigner//.
 
 
-_subsection: Properties ^^//(inheritted from [[contract]])//^^
+_subsection: Properties @NOTE<(inheritted from [[Contract]])>
 
 _property: erc20.address => string<[[address]]>
 This is the address (or ENS name) the contract was constructed with.
 
-_property: erc20.addressPromise => string<[[address]]>
+_property: erc20.resolvedAddress => string<[[address]]>
 This is a promise that will resolve to the address the **Contract**
 object is attached to. If an [[address]] was provided to the constructor,
 it will be equal to this; if an ENS name was provided, this will be the
 resolved address.
 
-_property: erc20.deployTransaction => [[provider-transactionresponse]]
+_property: erc20.deployTransaction => [[providers-TransactionResponse]]
 If the **Contract** object is the result of a ContractFactory deployment,
 this is the transaction which was used to deploy the contract.
 
-_property: erc20.interface => [[abi-interface]]
-This is the ABI as an [[abi-interface]].
+_property: erc20.interface => [[Interface]]
+This is the ABI as an [[Interface]].
 
-_property: erc20.provider => [[provider]]
+_property: erc20.provider => [[Provider]]
 If a provider was provided to the constructor, this is that provider. If
-a signer was provided that had a [[provider]], this is that provider.
+a signer was provided that had a [[Provider]], this is that provider.
 
-_property: erc20.signer => [[signer]]
+_property: erc20.signer => [[Signer]]
 If a signer was provided to the constructor, this is that signer.
 
 
-_subsection: Methods ^^//(inheritted from [[contract]])//^^
+_subsection: Methods @NOTE<(inheritted from [[Contract]])>
 
-_property: erc20.attach(addressOrName) => [[contract]]
+_property: erc20.attach(addressOrName) => [[Contract]]
 Returns a new instance of the **Contract** attached to a new
 address. This is useful if there are multiple similar or identical
 copies of a Contract on the network and you wish to interact with
 each of them.
 
-_property: erc20.connect(providerOrSigner) => [[contract]]
+_property: erc20.connect(providerOrSigner) => [[Contract]]
 Returns a new instance of the Contract, but connected to
 //providerOrSigner//.
 
-By passing in a [[provider]], this will return a downgraded
+By passing in a [[Provider]], this will return a downgraded
 **Contract** which only has read-only access (i.e. constant calls).
 
-By passing in a [[signer]]. the will return a **Contract** which
+By passing in a [[Signer]]. the will return a **Contract** which
 will act on behalf of that signer.
 
 _property: erc20.deployed() => Promise<Contract>
@@ -63,7 +99,7 @@ _property: erc20.deployed() => Promise<Contract>
 _property: Contract.isIndexed(value) => boolean
 
 
-_subsection: Events ^^//(inheritted from Contract)//^^ @<erc20-events>
+_subsection: Events @NOTE<(inheritted from [[Contract]])> @<erc20-events>
 
 _property: erc20.queryFilter(event [ , fromBlockOrBlockHash [ , toBlock ]) => Promise<Array<Event>> @<erc20-queryfilter>
 Return Events that match the //event//.
@@ -90,23 +126,23 @@ Unsubscribe all listeners for //event//. If no event is provided,
 all events are unsubscribed.
 
 
-_subsection: Meta-Class Methods ^^//(added at Runtime)//^^
+_subsection: Meta-Class Methods @NOTE<(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
+used with [parseUnits](utils-parseUnits) when taking input from the user or
 [formatUnits](utils-formatunits] when displaying the token amounts in the UI.
 
-_property: erc20.getBalance(owner [, overrides ]) => Promise<[[bignumber]]>
+_property: erc20.getBalance(owner [, overrides ]) => Promise<[[BigNumber]]>
 Returns the balance of //owner// for this ERC-20 token.
 
 _property: erc20.symbol([ overrides ]) => Promise<string>
 Returns the symbol of the token.
 
-_property: erc20_rw.transfer(target, amount [, overrides ]) => Promise<[[provider-transactionresponse]]>
+_property: erc20_rw.transfer(target, amount [, overrides ]) => Promise<[[providers-TransactionResponse]]>
 Transfers //amount// tokens to //target// from the current signer.
 The return value (a boolean) is inaccessible during a write operation
 using a transaction. Other techniques (such as events) are required
@@ -119,12 +155,12 @@ the current signer, without actually signing or sending a transaction.
 
 This can be used to preflight check that a transaction will be successful.
 
-_property: erc20.estimate.transfer(target, amount [, overrides ]) => Promise<[[bignumber]]>
+_property: erc20.estimateGas.transfer(target, amount [, overrides ]) => Promise<[[BigNumber]]>
 Returns an estimate for how many units of gas would be required
 to transfer //amount// tokens to //target//.
 
-_property: erc20.populateTransaction.transfer(target, amount [, overrides ]) => Promise<[UnsignedTx](types-unsignedtransaction)>
-Returns an [[types-unsignedtransaction]] which could be signed and submitted
+_property: erc20.populateTransaction.transfer(target, amount [, overrides ]) => Promise<[UnsignedTx](UnsignedTransaction)>
+Returns an [[UnsignedTransaction]] which could be signed and submitted
 to the network to transaction //amount// tokens to //target//.
 
 
@@ -137,7 +173,7 @@ 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)//^^
+_subsection: Meta-Class Filters @NOTE<(added at Runtime)>
 
 Since the Contract is a Meta-Class, the methods available here depend
 on the ABI which was passed into the **Contract**.

docs.wrm/api/contract/index.wrm

@@ -1,8 +1,14 @@
 _section: Contract Interaction @<contracts>
 
-Explain what contracts are...
+A **Contract** object is an abstraction of a contract (EVM bytecode)
+deployed on the Ethereum network. It allows for a simple way to
+serialize calls and transaxtions to an on-chain contract and
+deserialize their results and emitted logs.
 
+A **ContractFactory** is an abstraction a contract's //bytecode//
+and facilitates deploying a contract.
 
 _toc:
     contract
+    contract-factory
     example

docs.wrm/api/contract/token.txt

@@ -1,35 +0,0 @@
-// 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/experimental.wrm

@@ -0,0 +1,65 @@
+_section: Experimental
+
+The **Experimental** package is used for features that are not ready
+to be included in the base library. The API should not be considered
+stable and does not follow [[link-semver]] versioning, so applications
+requiring it should specify the //exact version// needed.
+
+_subsection: BrainWallet @<experimental-brainwallet> @INHERIT<[[Wallet]]>
+
+Ethers removed support for BrainWallets in v4, since they are unsafe and
+many can be easily guessed, allowing attackers to steal the funds. This
+class is offered to ensure older systems which used brain wallets can
+still recover their funds and assets.
+
+_property: BrainWallet.generate(username, password [ , progressCallback ]) => [[experimental-brainwallet]]
+Generates a brain wallet, with a slightly improved experience, in which
+the generated wallet has a mnemonic.
+
+_property: BrainWallet.generateLegacy(username, password [ , progressCallback ]) => [[experimental-brainwallet]]
+Generate a brain wallet which is compatibile with the ethers v3 and earlier.
+
+
+_subsection: EIP1193Bridge @<experimental-eip1193bridge> @INHERIT<[[link-npm-events]]>
+
+The **EIP1193Bridge** allows a normal Ethers [[Signer]] and [[Provider]] to be
+exposed in as a standard [EIP-1193 Provider](link-eip-1193), which may be useful
+when interacting with other libraries.
+
+
+_subsection: NonceManager @<experimental-noncemanager> @INHERIT<[[Signer]]>
+
+The **NonceManager** is designed to manage the nonce for a Signer,
+automatically increasing it as it sends transactions.
+
+Currently the NonceManager does not handle re-broadcast. If you attempt
+to send a lot of transactions to the network on a node that does not
+control that account, the transaction pool may drop your transactions.
+
+In the future, it'd be nice if the **NonceManager** remembered transactions
+and watched for them on the network, rebroadcasting transactions that
+appear to have been dropped.
+
+Another future feature will be some sort of failure mode. For example, often
+a transaction is dependent on another transaction being mined first.
+
+_property: new NonceManager(signer)
+Create a new NonceManager.
+
+_property: nonceManager.signer => [[Signer]]
+The signer whose nonce is being managed.
+
+_property: nonceManager.provider => [[Provider]]
+The provider associated with the signer.
+
+_property: nonceManager.setTransactionCount(count) => void
+Set the current transaction count (nonce) for the signer.
+
+This may be useful it interacting with the signer outside of using
+this class.
+
+_property: nonceManager.increaseTransactionCount( [ count = 1 ]) => void
+Bump the current transaction count (nonce) by //count//.
+
+This may be useful it interacting with the signer outside of using
+this class.

docs.wrm/api/index.wrm

@@ -1,6 +1,7 @@
-_section: Application Programming Interface @NAV<API>
+_section: Application Programming Interface  @<api> @NAV<API>
 
-Here...
+An Application Programming Interface (API) is the formal
+specification of the library.
 
 _toc:
     contract
@@ -8,3 +9,4 @@ _toc:
     providers
     utils
     other
+    experimental

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

@@ -8,7 +8,7 @@ The assembler utilities allow parsing and assembling an
 _property: asm.parse(code) => [[asm-node]] @<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>
+_property: asm.assemble(node) => string<[[DataHexString]]> @SRC<asm/assembler:function.assemble>
 Performs assembly of the [[asm-ast]] //node// and return the
 resulting bytecode representation.
 
@@ -45,7 +45,7 @@ The opcode for this Operation.
 _property: operation.offset => number
 The offset into the bytecode for this Operation.
 
-_property: operation.pushValue => string<[[datahexstring]]>
+_property: operation.pushValue => string<[[DataHexString]]>
 If the opcode is a ``PUSH``, this is the value of that push
 
 

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

@@ -44,7 +44,7 @@ A **ValueNode** is a node which may manipulate the stack.
 _heading: LiteralNode @<asm-literalnode> @INHERIT<[[asm-valuenode]]> @SRC<asm:class.LiteralNode>
 
 _property: literalNode.value => string
-The literal value of this node, which may be a [[datahexstring]] or
+The literal value of this node, which may be a [[DataHexString]] or
 string of a decimal number.
 
 _property: literalNode.verbatim => boolean

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

@@ -42,7 +42,7 @@ _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
+A **Literal** can be provided using a [[DataHexString]] or a decimal
 byte value.
 
 @TODO: exmples

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

@@ -1,5 +1,7 @@
 _section: Assembly
 
+This module should still be considered fairly experimental.
+
 _toc:
     dialect
     api

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

@@ -1,11 +1,16 @@
 _section: Hardware Wallets
 
-_subsection: LedgerSigner @<hw-ledger> @INHERIT<[[signer]]> @SRC<hardware-wallets:class.LedgerSigner>
+
+_subsection: LedgerSigner @<hw-ledger> @INHERIT<[[Signer]]> @SRC<hardware-wallets:class.LedgerSigner>
 
 The [Ledger Hardware Wallets](link-ledger) are a fairly
 popular brand.
 
-TODO: importing
+
+_code: Importing in ES6 or TypeScript @lang<script>
+
+import { LedgerSigner } from "@ethersproject/hardware-wallets";
+
 
 _heading: API
 

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

@@ -1,4 +1,4 @@
-_section: API Providers
+_section: API Providers @<api-providers>
 
 There are many services which offer a web API for accessing
 the Ethereum Blockchain. These Providers allow connecting
@@ -8,17 +8,34 @@ to run your own instance or cluster of Ethereum nodes.
 However, this reliance on third-party services can reduce
 resiliance, security and increase the amount of required trust.
 To mitigate these issues, it is recommended you use a
-[Default Provider](get-default-provider).
+[Default Provider](providers-getDefaultProvider).
 
 
-_subsection: EtherscanProvider @INHERIT<[[provider]]>
+_subsection: EtherscanProvider @<EtherscanProvider> @inherit<[[Provider]]> @src<providers:class.EtherscanProvider>
 
 The **EtherscanProvider** is backed by a combination of the various
 [Etherscan APIs](link-etherscan-api).
 
-_property: provider.getHistory(address) => Array<History>
+_property: new ethers.providers.EtherscanProvider([ network = "homestead", [ apiKey ] ])
+Create a new **EtherscanProvider** connected to //network// with the
+optional //apiKey//.
+
+The //network// may be specified as **string** for a common
+network name, a **number** for a common chain ID or a
+[Network Object]provider-(network).
+
+If no //apiKey// is provided, a shared API key will be used,
+which may result in reduced performance and throttled requests.
+It is highly recommended for production, you register with
+[Etherscan](link-etherscan) for your own API key.
+
+_note: Note: Default API keys
+If no //apiKey// is provided, a shared API key will be used,
+which may result in reduced performance and throttled requests.
+
+It is highly recommended for production, you register with
+[Etherscan](link-etherscan) for your own API key.
 
-@TODO... Explain
 
 _definition: **Supported Networks**
 
@@ -28,24 +45,63 @@ _definition: **Supported Networks**
 - G&ouml;rli (clique testnet)
 - Kovan (proof-of-authority testnet)
 
+_code: Etherscan Examples @lang<javascript>
 
-_subsection: InfuraProvider @INHERIT<[[provider-urljsonrpc]]>
+// <hide>
+const EtherscanProvider = ethers.providers.EtherscanProvider;
+const apiKey = "...";
+// </hide>
+
+// Connect to mainnet (homestead)
+provider = new EtherscanProvider();
+
+// Connect to rinkeby testnet (these are equivalent)
+provider = new EtherscanProvider("rinkeby");
+provider = new EtherscanProvider(4);
+
+const network = ethers.providers.getNetwork("rinkeby");
+// <hide>
+delete network._defaultProvider;
+network
+// </hide>
+//!
+
+provider = new EtherscanProvider(network);
+
+// Connect to mainnet (homestead) with an API key
+provider = new EtherscanProvider(null, apiKey);
+provider = new EtherscanProvider("homestead", apiKey);
+
+
+_property: provider.getHistory(address) => Array<History> @src<providers>
+@TODO... Explain
+
+
+_subsection: InfuraProvider @<InfuraProvider> @INHERIT<[[UrlJsonRpcProvider]]> @src<providers:class.InfuraProvider>
 
 The **InfuraProvider** is backed by the popular [INFURA](link-infura)
 Ethereum service.
 
-_definition: **Supported Networks**
+_property: new ethers.providers.InfuraProvider([ network = "homestead", [ apiKey ] ])
+Create a new **InfuraProvider** connected to //network// with
+the optional //apiKey//.
 
-- Homestead (Mainnet)
-- Ropsten (proof-of-work testnet)
-- Rinkeby (proof-of-authority testnet)
-- G&ouml;rli (clique testnet)
-- Kovan (proof-of-authority testnet)
+The //network// may be specified as **string** for a common
+network name, a **number** for a common chain ID or a
+[Network Object]provider-(network).
 
+The //apiKey// can be a **string** Project ID or an **object**
+with the properties ``projectId`` and ``projectSecret`` to
+specify a [Project Secret](link-infura-secret) which can be used
+on non-public sources (like on a server) to further secure your
+API access and quotas.
 
-_subsection: AlchemyProvider @INHERIT<[[provider-urljsonrpc]]>
+_note: Note: Default API keys
+If no //apiKey// is provided, a shared API key will be used,
+which may result in reduced performance and throttled requests.
 
-The **AlchemtProvider** is backed by [Alchemy](link-alchemy).
+It is highly recommended for production, you register with
+[INFURA](link-infura) for your own API key.
 
 _definition: **Supported Networks**
 
@@ -55,11 +111,94 @@ _definition: **Supported Networks**
 - G&ouml;rli (clique testnet)
 - Kovan (proof-of-authority testnet)
 
+_code: INFURA Examples @lang<javascript>
 
-_subsection: CloudfrontProvider @INHERIT<[[provider-urljsonrpc]]>
+// <hide>
+const InfuraProvider = ethers.providers.InfuraProvider;
+const projectId = "...";
+const projectSecret = "...";
+// </hide>
 
-The CloudfrontProvider is backed by the [Cloudflare Ethereum Gateway](link-cloudflare).
+// Connect to mainnet (homestead)
+provider = new InfuraProvider();
+
+// Connect to the ropsten testnet
+// (see EtherscanProvider above for other network examples)
+provider = new InfuraProvider("ropsten");
+
+// Connect to mainnet with a Project ID (these are equivalent)
+provider = new InfuraProvider(null, projectId);
+provider = new InfuraProvider("homestead", projectId);
+
+// Connect to mainnet with a Project ID and Project Secret
+provider = new InfuraProvider("homestead", {
+    projectId: projectId,
+    projectSecret: projectSecret
+});
+
+
+_subsection: AlchemyProvider @<AlchemyProvider> @inherit<[[UrlJsonRpcProvider]]> @src<providers:class.AlchemyProvider>
+
+The **AlchemyProvider** is backed by [Alchemy](link-alchemy).
+
+_property: new ethers.providers.AlchemyProvider([ network = "homestead", [ apiKey ] ])
+Create a new **AlchemyProvider** connected to //network// with
+the optional //apiKey//.
+
+The //network// may be specified as **string** for a common
+network name, a **number** for a common chain ID or a
+[Network Object](providers-Network).
+
+_note: Note: Default API keys
+If no //apiKey// is provided, a shared API key will be used,
+which may result in reduced performance and throttled requests.
+
+It is highly recommended for production, you register with
+[Alchemy](link-alchemy) for your own API key.
 
 _definition: **Supported Networks**
 
 - Homestead (Mainnet)
+- Ropsten (proof-of-work testnet)
+- Rinkeby (proof-of-authority testnet)
+- G&ouml;rli (clique testnet)
+- Kovan (proof-of-authority testnet)
+
+_code: Alchemy Examples @lang<javascript>
+
+// <hide>
+const AlchemyProvider = ethers.providers.AlchemyProvider;
+const apiKey = "...";
+// </hide>
+
+// Connect to mainnet (homestead)
+provider = new AlchemyProvider();
+
+// Connect to the ropsten testnet
+// (see EtherscanProvider above for other network examples)
+provider = new AlchemyProvider("ropsten");
+
+// Connect to mainnet with an API key (these are equivalent)
+provider = new AlchemyProvider(null, apiKey);
+provider = new AlchemyProvider("homestead", apiKey);
+
+
+_subsection: CloudflareProvider @<CloudflareProvider> @inherit<[[UrlJsonRpcProvider]]> @src<providers:class.CloudflareProvider>
+
+The CloudflareProvider is backed by the [Cloudflare Ethereum Gateway](link-cloudflare).
+
+_property: new ethers.providers.CloudflareProvider()
+Create a new **CloudflareProvider** connected to mainnet (i.e. "homestead").
+
+_definition: **Supported Networks**
+
+- Homestead (Mainnet)
+
+_code: Cloudflare Examples @lang<javascript>
+
+// <hide>
+const CloudflareProvider = ethers.providers.CloudflareProvider;
+// </hide>
+
+// Connect to mainnet (homestead)
+provider = new CloudflareProvider();

docs.wrm/api/providers/example-account.js

@@ -1,29 +0,0 @@
-// <hide>
-
-const { ethers } = require("./packages/ethers");
-const provider = ethers.getDefaultProvider()
-
-function _inspect(result) {
-    if (ethers.BigNumber.isBigNumber(result)) {
-        return `{ BigNumber: ${ JSON.stringify(result.toString()) } }`;
-    }
-    return JSON.stringify(result);
-}
-
-// </hide>
-
-// Get the balance for an account...
-provider.getBalance("ricmoo.firefly.eth");
-//!
-
-// Get the code for a contract...
-provider.getCode("registrar.firefly.eth");
-//!
-
-// Get the storage value at position 0...
-provider.getStorageAt("registrar.firefly.eth", 0)
-//!
-
-// Get transaction count of an account...
-provider.getTransactionCount("ricmoo.firefly.eth");
-//!

docs.wrm/api/providers/example-ens.js

@@ -1,15 +0,0 @@
-// <hide>
-
-const { ethers } = require("./packages/ethers");
-const provider = ethers.getDefaultProvider()
-
-// </hide>
-
-// Reverse lookup of an ENS by address...
-provider.lookupAddress("0x6fC21092DA55B392b045eD78F4732bff3C580e2c");
-//!
-
-// Lookup an address of an ENS name...
-provider.resolveName("ricmoo.firefly.eth");
-//!
-

docs.wrm/api/providers/index.wrm

@@ -1,4 +1,4 @@
-_section: Providers
+_section: Providers @<providers>
 
 A **Provider** is an abstraction of a connection to the
 Ethereum network, providing a concise, consistent interface
@@ -9,16 +9,16 @@ cover the vast majority of use-cases, but also includes the
 necessary functions and classes for sub-classing if a more
 custom configuration is necessary.
 
-Most users should be able to simply use the [[get-default-provider]].
+Most users should be able to simply use the [[providers-getDefaultProvider]].
 
 
-_subsection: Default Provider @<get-default-provider>
+_subsection: Default Provider @<providers-getDefaultProvider>
 
 The default provider is the safest, easiest way to begin
 developing on //Ethereum//, and it is also robust enough
 for use in production.
 
-It creates a [[provider-fallback]] connected to as many backend
+It creates a [[FallbackProvider]] connected to as many backend
 services as possible. When a request is made, it is sent to
 multiple backends simulatenously. As responses from each backend
 are returned, they are checked that they agree. Once a quorum
@@ -29,11 +29,45 @@ This ensures that if a backend has become out-of-sync, or if it
 has been compromised that its responses are dropped in favor of
 responses that match the majority.
 
-_property: ethers.getDefaultProvider([ network ]) => [[provider]]
+_property: ethers.getDefaultProvider([ network, [ options ] ]) => [[Provider]]
 Returns a new Provider, backed by multiple services, connected
 to //network//. Is no //network// is provided, **homestead**
 (i.e. mainnet) is used.
 
+The //options// is an object, with the following properties:
+
+_table: Option Properties
+
+$Alchemy:     [[link-alchemy]] API Token
+$Etherscan:   [[link-etherscan]] API Token
+$Infura:      [[link-infura]] Project ID or ProjectID and Project Secret
+$Quorum:      The number of backends that must agree
+              //(default: 2 for mainnet, 1 for testnets)//
+    
+|    **Property**    |  **Description**  |
+|    //alchemy//     | $Alchemy          |
+|   //etherscan//    | $Etherscan        |
+|    //infura//      | $Infura           |
+|    //quorum//      | $Quorum           |
+
+_note: Note: API Keys
+
+It is highly recommended for production services that to acquire
+and specify an API Key for each sercice.
+
+The deafult API Keys used by ethers are shared across all users,
+so services may throttle all services that are using the default
+API Keys during periods of load without realizing it.
+
+Many services also have monitoring and usage metrics, which are
+only available if an API Key is specifie. This allows tracking
+how many requests are being sent and which methods are being
+used the most.
+
+Some services also provide additional paid features, whichare only
+available when specifying an API Key.
+
+
 _subsection: Provider Documentation
 
 _toc:

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

@@ -1,73 +1,92 @@
-_section: JsonRpcProvider  @<provider-jsonrpc> @INHERIT<[[provider]]>
+_section: JsonRpcProvider  @<JsonRpcProvider> @INHERIT<[[Provider]]> @SRC<providers:class.JsonRpcProvider>
 
-The [JSON-RPC API](link-jsonrpc) is a
-very popular method for interacting with Ethereum and is available in all
-major Ethereum node implementations (e.g. [Geth](link-geth)
-and [Parity](link-parity)) as well as many third-party web
-services (e.g. [INFURA](link-infura))
+The [JSON-RPC API](link-jsonrpc) is a very popular method for interacting
+with Ethereum and is available in all major Ethereum node implementations
+(e.g. [[link-geth]] and [[link-parity]]) as well as many
+third-party web services (e.g. [[link-infura]])
 
-_property: new ethers.providers.JsonRpcProvider([ url [ , aNetworkish ] ])
-Connect to a JSON-RPC API located at //url// using the /aNetworkish// network.
-If //url// is not specified, the default (i.e. ``http://localhost:8545``) is used
+_property: new ethers.providers.JsonRpcProvider([ url [ , aNetworkish ] ])  @SRC<providers:constructor.JsonRpcProvider>
+Connect to a JSON-RPC API located at //url// using the //aNetworkish// network.
+If //url// is not specified, the default (i.e. ``http:/\/localhost:8545``) is used
 and if no network is specified, it will be determined automatically by
 querying the node.
 
 _note: Note: Connecting to a Local Node
-Each node implementation is slightly different and may require specific command-line
-flags or changes in their Settings UI to enable JSON-RPC, unlock accounrs
-or expose specific APIs. Please consult theit documentation.
+Each node implementation is slightly different and may require specific
+command-line flags, configuration or settings in their UI to enable
+JSON-RPC, unlock accounrs or expose specific APIs. Please consult
+their documentation.
 
-_property: jsonRpcProvider.getSigner([ addressOrIndex ]) => [[signer-jsonrpc]]  @<provider-jsonrpc-getsigner> @SRC<providers/json-rpc-provider>
-Returns a [[signer-jsonrpc]] which is managed by this Ethereum node, at
+_property: jsonRpcProvider.getSigner([ addressOrIndex ]) => [[JsonRpcSigner]]  @<JsonRpcProvider-getSigner> @SRC<providers/json-rpc-provider>
+Returns a [[JsonRpcSigner]] which is managed by this Ethereum node, at
 //addressOrIndex//. If no //addressOrIndex// is provided, the first
 account (account #0) is used.
 
-_property: jsonRpcProvider.getUncheckedSigner([ addressOrIndex ]) => [[provider-jsonrpc-uncheckedsigner]]  @<provider-jsonrpc-getuncheckedsigner> @SRC<providers/json-rpc-provider>
+_property: jsonRpcProvider.getUncheckedSigner([ addressOrIndex ]) => [[UncheckedJsonRpcSigner]]  @<JsonRpcProvider-getUncheckedSigner> @SRC<providers/json-rpc-provider>
 
-_property: jsonRpcProvider.listAccounts() => Array<string>  @<provider-jsonrpc-listaccounts> @SRC<providers/json-rpc-provider>
+_property: jsonRpcProvider.listAccounts() => Array<string>  @<JsonRpcProvider-listAccounts> @SRC<providers/json-rpc-provider>
 Returns a list of all account addresses managed by this provider.
 
-_property: jsonRpcProvider.send(method, params) => Promise<any>  @<provider-jsonrpc-send> @SRC<providers/json-rpc-provider>
+_property: jsonRpcProvider.send(method, params) => Promise<any>  @<JsonRpcProvider-send> @SRC<providers/json-rpc-provider>
 Allows sending raw messages to the provider.
 
 This can be used for backend-specific calls, such as for debugging or
 specific account management.
 
 
-_subsection: JsonRpcSigner @<signer-jsonrpc> @INHERIT<[[signer]]>
+_subsection: JsonRpcSigner  @<JsonRpcSigner> @INHERIT<[[Signer]]> @SRC<providers:class.JsonRpcSigner>
 A **JsonRpcSigner** is a simple Signer which is backed by a connected
-[[provider-jsonrpc]].
+[[JsonRpcProvider]].
 
-_property: signer.provider => [[provider-jsonrpc]]
+_property: signer.provider => [[JsonRpcProvider]]
 The provider this signer was established from.
 
-_property: signer.connectUnchecked() => [[provider-jsonrpc-uncheckedsigner]]
+_property: signer.connectUnchecked() => [[UncheckedJsonRpcSigner]]  @<JsonRpcSigner-connectUnchecked> @SRC<providers>
 Returns a new Signer object which does not perform addtional checks when
-sending a transaction. See [[provider-jsonrpc-uncheckedsigner]] for more details.
+sending a transaction. See [getUncheckedSigner](JsonRpcProvider-getUncheckedSigner) for more details.
 
-_property: signer.sendUncheckedTransaction(transaction) => Promise<string<[[datahexstring]]<32>>>
+_property: signer.sendUncheckedTransaction(transaction) => Promise<string<[[DataHexString]]\<32>\>>  @<JsonRpcSigner-sendUncheckedTransaction> @SRC<providers>
 Sends the //transaction// and returns a Promise which resolves to the
 opacque transaction hash.
 
-_property: signer.unlock(password) => Promise<boolean>
+_property: signer.unlock(password) => Promise<boolean>  @<JsonRpcSigner-unlock> @SRC<providers>
 Request the node unlock the account (if locked) using //password//.
 
 
-_subsection: JsonRpcUncheckedSigner @<provider-jsonrpc-uncheckedsigner> @INHERIT<[[signer]]>
+_subsection: JsonRpcUncheckedSigner  @<UncheckedJsonRpcSigner> @INHERIT<[[Signer]]> @SRC<providers:class.UncheckedJsonRpcSigner>
 The JSON-RPC API only provides a transaction hash as the response when a
 transaction is sent, but the ethers Provider requires populating all details
 of a transaction before returning it. For example, the gas price and gas limit
 may be adjusted by the node or the nonce automatically included, in which case
 the opaque transaction hash has discarded this.
 
-To remedy this, the [[signer-jsonrpc]] immeidately queries the provider for
-the details using the returned transaction hash to populate the [[provider-transactionresponse]]
+To remedy this, the [[JsonRpcSigner]] immeidately queries the provider for
+the details using the returned transaction hash to populate the [[providers-TransactionResponse]]
 object.
 
 Some backends do not respond immediately and instead defer releasing the
 details of a transaction it was responsible for signing until it is mined.
 
 The **UncheckedSigner** does not populate any additional information and will
-immediately return the result as a mock [[provider-transactionresponse]]-like
+immediately return the result as a mock [[providers-TransactionResponse]]-like
 object, with most of the properties set to null, but allows access to the
 transaction hash quickly, if that is all that is required.
+
+
+_subsection: Node-Specific Methods @<JsonRpcProvider--other>
+
+Many methods are less common or specific to certain Ethereum Node implementations
+(e.g. [Parity](link-parity) vs [Geth](link-geth). These include account and admin management,
+debugging, deeper block and transaction exploration and other services (such as
+Swarm and Whisper).
+
+The [jsonRpcProvider.send](JsonRpcProvider-send) method can be used to access these.
+
+- [All JSON-RPC methods](link-json-rpc) (including the less common methods) which most
+  Ethereum Nodes support.
+- [Parity's Trace Module](link-parity-trace) can be used to trace and debug EVM
+  execcution of a transaction (requires custom configuration)
+- [Geth's Debug Module](link-geth-debug) can be used to debug transactions and
+  internal cache state, etc.
+- [Additional Geth Methods](link-geth-rpc)
+- [Additional Parity Methods](link-parity-rpc)

docs.wrm/api/providers/other.wrm

@@ -2,12 +2,12 @@ _section: Other Providers
 
 Others...
 
-_subsection: FallbackProvider  @<provider-fallback> @INHERIT<[[provider]]> @SRC<providers/fallback-provider:class.FallbackProvider>
+_subsection: FallbackProvider  @<FallbackProvider> @INHERIT<[[Provider]]> @SRC<providers/fallback-provider:class.FallbackProvider>
 
-The **FallbackProvider** is the most advanced [[provider]] available in
+The **FallbackProvider** is the most advanced [[Provider]] available in
 ethers.
 
-It uses a quorum and connects to multiple [Providers](provider) as backends,
+It uses a quorum and connects to multiple [Providers](Provider) as backends,
 each configured with a //priority// and a //weight// .
 
 When a request is made, the request is dispatched to multiple backends, randomly
@@ -23,10 +23,10 @@ Creates a new instance of a FallbackProvider connected to //providers//. If
 quorum is not specified, half of the total sum of the provider weights is
 used.
 
-The //providers// can be either an array of [[provider]] or [[provider-fallback-config]].
-If a [[provider]] is provided, the defaults are a priority of 1 and a weight of 1.
+The //providers// can be either an array of [[Provider]] or [[FallbackProviderConfig]].
+If a [[Provider]] is provided, the defaults are a priority of 1 and a weight of 1.
 
-_property: provider.providerConfigs => Array<[[provider-fallback-config]]>
+_property: provider.providerConfigs => Array<[[FallbackProviderConfig]]>
 The list of Provider Configurations that describe the backends.
 
 _property: provider.quorum => number
@@ -34,9 +34,9 @@ The quorum the backend responses must agree upon before a result will be
 resolved. By default this is //half the sum of the weights//.
 
 
-_heading: FallbackProviderConfig  @<provider-fallback-config>
+_heading: FallbackProviderConfig  @<FallbackProviderConfig>
 
-_property: fallbackProviderConfig.provider => [[provider]]
+_property: fallbackProviderConfig.provider => [[Provider]]
 The provider for this configuration.
 
 _property: fallbackProviderConfig.priority => number
@@ -45,7 +45,7 @@ priorities. If multiple providers share the same prioirty, they are choosen
 at random.
 
 _property: fallbackProviderConfig.stallTimeout => number
-The timeout (in ms) after which another [[provider]] will be attempted. This
+The timeout (in ms) after which another [[Provider]] will be attempted. This
 does not affect the current Provider; if it returns a result it is counted
 as part of the quorum.
 
@@ -54,10 +54,10 @@ time of requests.
 
 _property: fallbackProviderConfig.weight => number
 The weight a response from this provider provides. This can be used if a given
-[[provider]] is more trusted, for example.
+[[Provider]] is more trusted, for example.
 
 
-_subsection: IpcProvider  @<provider-ipc> @INHERIT<[[provider-jsonrpc]]> @SRC<providers:class.IpcProvider>
+_subsection: IpcProvider  @<IpcProvider> @INHERIT<[[JsonRpcProvider]]> @SRC<providers:class.IpcProvider>
 
 The **IpcProvider** allows the JSON-RPC API to be used over a local
 filename on the file system, exposed by Geth, Parity and other nodes.
@@ -67,13 +67,13 @@ and may have additional complications due to file permissions. See any
 related notes on the documentation for the actual node implementation websites.
 
 _property: ipcProvider.path => string
-The path this [[provider]] is connected to.
+The path this [[Provider]] is connected to.
 
 
-_subsection: UrlJsonRpcProvider @<provider-urljsonrpc> @INHERIT<[[provider-jsonrpc]]> @SRC<providers:class.UrlJsonRpcProvider>
+_subsection: UrlJsonRpcProvider @<UrlJsonRpcProvider> @INHERIT<[[JsonRpcProvider]]> @SRC<providers:class.UrlJsonRpcProvider>
 
 This class is intended to be sub-classed and not used directly. It
-simplifies creating a [[provider]] where a normal [[provider-jsonrpc]]
+simplifies creating a [[Provider]] where a normal [[JsonRpcProvider]]
 would suffice, with a little extra effort needed to generate the JSON-RPC
 URL.
 
@@ -93,18 +93,54 @@ The URL to use for the JsonRpcProvider instance.
 
 
 
-_subsection: Web3Provider @<provider-web3> @INHERIT<[[provider-jsonrpc]]>
+_subsection: Web3Provider @<Web3Provider> @INHERIT<[[JsonRpcProvider]]>
 
 The Web3Provider is meant to ease moving from a [web3.js based](link-web3)
 application to ethers by wraping an existing Web3-compatible (such as a
-[Web3HttpProvider](link-web3-http)[Web3IpcProvider](link-web3-ipc) or
-[Web3WsProvider](link-web3-ws)) and exposing it as an ethers.js [[provider]]
+[Web3HttpProvider](link-web3-http), [Web3IpcProvider](link-web3-ipc) or
+[Web3WsProvider](link-web3-ws)) and exposing it as an ethers.js [[Provider]]
 which can then be used with the rest of the library.
 
-_property: new ethers.providers.Web3Provider(web3Provider [, network ])
-Create a new **Web3Provider**, which wraps an [EIP-1193 Provider]() or
+This may also be used to wrap a standard [EIP-1193 Provider](link-eip-1193].
+
+_property: new ethers.providers.Web3Provider(externalProvider [, network ])
+Create a new **Web3Provider**, which wraps an [EIP-1193 Provider](link-eip-1193) or
 Web3Provider-compatible Provider.
 
 _property: web3Provider.provider => Web3CompatibleProvider
 The provider used to create this instance.
 
+_heading: ExternalProvider @<Web3Provider--ExternalProvider>
+
+An **ExternalProvider** can be either one for the above mentioned Web3
+Providers (or otherwise compatible) or an [[link-eip-1193]] provider.
+
+An ExternalProvider must offer one of the following signatures, and the
+first matching is used:
+
+_property: externalProvider.request(request) => Promise<any>
+
+This follows the [[link-eip-1193]] API signature.
+
+The //request// should be a standard JSON-RPC payload, which should at
+a minimum specify the ``method`` and ``params``.
+
+The result should be the actual result, which differs from the Web3.js
+response, which is a wrapped JSON-RPC response.
+
+_property: externalProvider.sendAsync(request, callback) => void
+
+This follows the [Web3.js Provider Signature](link-web3-send).
+
+The //request// should be a standard JSON-RPC payload, which should at
+a minimum specify the ``method`` and ``params``.
+
+The //callback// should use the error-first calling semantics, so
+``(error, result)`` where the result is a JSON-RPC wrapped result.
+
+_property: externalProvider.send(request, callback) => void
+
+This is identical to ``sendAsync``. Historically, this used a synchronous
+web request, but no current browsers support this, so its use this way
+was deprecated quite a long time ago
+

docs.wrm/api/providers/provider.wrm

@@ -1,89 +1,154 @@
-_section: Provider @<provider>
+_section: Provider @<Provider>
 
 Explain what a provider is...
 
 
-_subsection: Accounts Methods
+_subsection: Accounts Methods  @<Provider--account-methods>
 
-_property: provider.getBalance(address [ , blockTag = "latest" ]) => Promise<[[bignumber]]>  @<provider-getbalance> @SRC<providers/base-provider>
+_property: provider.getBalance(address [ , blockTag = latest ]) => Promise<[[BigNumber]]>  @<Provider-getBalance> @SRC<providers/base-provider>
 Returns the balance of //address// as of the //blockTag// block height.
 
-_property: provider.getCode(address [ , blockTag = "latest" ]) => Promise<string<[[datahexstring]]>>  @<providers-getcode> @SRC<providers/base-provider>
+_property: provider.getCode(address [ , blockTag = latest ]) => Promise<string<[[DataHexString]]>>  @<Provider-getCode> @SRC<providers/base-provider>
 Returns the contract code of //address// as of the //blockTag// block height. If there is
 no contract currently deployed, the result is ``0x``.
 
-_property: provider.getStorageAt(addr, pos [ , blockTag = "latest" ]) => Promise<string<[[datahexstring]]>>  @<providers-getstorageat> @SRC<providers/base-provider>
+_property: provider.getStorageAt(addr, pos [ , blockTag = latest ]) => Promise<string<[[DataHexString]]>>  @<Provider-getStorageAt> @SRC<providers/base-provider>
 Returns the ``Bytes32`` value of the position //pos// at address //addr//, as of the //blockTag//.
 
-_property: provider.getTransactionCount(address [ , blockTag = "latest" ]) => Promise<number>  @<providers-gettransactioncount> @SRC<providers/base-provider>
+_property: provider.getTransactionCount(address [ , blockTag = latest ]) => Promise<number>  @<Provider-getTransactionCount> @SRC<providers/base-provider>
 Returns the number of transactions //address// has ever **sent**, as of //blockTag//.
 This value is required to be the nonce for the next transaction from //address//
 sent to the network.
 
-_heading: Examples
+_code: Account Examples @lang<javascript>
 
-_code: example-account.js
+// Get the balance for an account...
+provider.getBalance("ricmoo.firefly.eth");
+//!
+
+// Get the code for a contract...
+provider.getCode("registrar.firefly.eth");
+//!
+
+// Get the storage value at position 0...
+provider.getStorageAt("registrar.firefly.eth", 0)
+//!
+
+// Get transaction count of an account...
+provider.getTransactionCount("ricmoo.firefly.eth");
+//!
 
 
-_subsection: Blocks Methods
+_subsection: Blocks Methods  @<Provider--block-methods>
 
-_property: provider.getBlock(block) => Promise<[[provider-block]]>  @<providers-getblock> @SRC<providers/base-provider>
+_property: provider.getBlock(block) => Promise<[[providers-Block]]>  @<Provider-getBlock> @SRC<providers/base-provider>
 Get the //block// from the network, where the ``result.transactions`` is a list
 of transaction hashes.
 
-_property: provider.getBlockWithTransactions(block) => Promise<[[provider-blocktxs]]>  @<providers-getblockwithtransactions> @SRC<providers/base-provider>
+_property: provider.getBlockWithTransactions(block) => Promise<[[providers-BlockWithTransactions]]>  @<Provider-getBlockWithTransactions> @SRC<providers/base-provider>
 Get the //block// from the network, where the ``result.transactions`` is
-an Array of [[provider-transactionresponse]] objects.
+an Array of [[providers-TransactionResponse]] objects.
 
+_code: Block Examples @lang<javascript>
 
-_subsection: Ethereum Naming Service (ENS) Methods
+provider.getBlock(100004)
+//!
 
-TODO: Explain ENS here...
+provider.getBlockWithTransactions(100004)
+//!
 
-_property: provider.lookupAddress(address) => Promise<string>  @<providers-lookupaddress> @SRC<providers/base-provider>
+_subsection: Ethereum Naming Service (ENS) Methods @<Provider--ens-methods>
+
+The [Ethereum Naming Service](link-ens) (ENS) allows a short and
+easy-to-remember ENS Name to be atached to any set of keys
+and values.
+
+One of the most common uses for this is to use a simple name to
+refer to an [Ethereum Address](address).
+
+In the ethers API, nearly anywhere that accepts an address, an
+ENS name may be used instead, which can simplify code and make
+reading and debugging much simpler.
+
+The provider offers some basic operations to help resolve and
+work with ENS names.
+
+_property: provider.lookupAddress(address) => Promise<string>  @<Provider-lookupAddress> @SRC<providers/base-provider>
 Performs a reverse lookup of the //address// in ENS using the
 //Reverse Registrar//.  If the name does not exist, or the
 forward lookup does not match, ``null`` is returned.
 
-_property: provider.resolveName(name) => Promise<string<[Address](address)>>  @<providers-resolvename> @SRC<providers/base-provider>
+_property: provider.resolveName(name) => Promise<string<[Address](address)>>  @<Provider-ResolveName> @SRC<providers/base-provider>
 Looks up the address of //name//. If the name is not owned, or
 does not have a //Resolver// configured, or the //Resolver// does
 not have an address configured, ``null`` is returned.
 
-_heading: Examples
+_code: ENS Examples @lang<javascript>
 
-_code: example-ens.js
+// Reverse lookup of an ENS by address...
+provider.lookupAddress("0x6fC21092DA55B392b045eD78F4732bff3C580e2c");
+//!
 
-_subsection: Logs Methods
+// Lookup an address of an ENS name...
+provider.resolveName("ricmoo.firefly.eth");
+//!
 
-_property: provider.getLogs(filter) => Promise<Array<[[provider-log]]>>  @<providers-getlogs> @SRC<providers/base-provider>
-Returns the Array of [[provider-log]] matching the //filter//.
+
+_subsection: Logs Methods  @<Provider--log-methods>
+
+_property: provider.getLogs(filter) => Promise<Array<[[providers-Log]]>>  @<Provider-getLogs> @SRC<providers/base-provider>
+Returns the Array of [[providers-Log]] matching the //filter//.
 
 Keep in mind that many backends will discard old events, and that requests
 which are too broad may get dropped as they require too many resources to
 execute the query.
 
 
-_subsection: Network Status Methods
+_subsection: Network Status Methods  @<Provider--network-methods>
 
-_property: provider.getNetwork() => Promise<[[provider-network]]>  @<providers-getnetwork> @SRC<providers/base-provider:method.BaseProvider.getNetwork>
-Returns the [[provider-network]] this Provider is connected to.
+_property: provider.getNetwork() => Promise<[[providers-Network]]>  @<Provider-getNetwork> @SRC<providers/base-provider:method.BaseProvider.getNetwork>
+Returns the [[providers-Network]] this Provider is connected to.
 
-_property: provider.getBlockNumber() => Promise<number>  @<providers-getblocknumber> @SRC<providers/base-provider>
+_property: provider.getBlockNumber() => Promise<number>  @<Provider-getBlockNumber> @SRC<providers/base-provider>
 Returns the block number (or height) of the most recently mined block.
 
-_property: provider.getGasPrice() => Promise<[[bignumber]]>  @<providers-getgasprice> @SRC<providers/base-provider>
+_property: provider.getGasPrice() => Promise<[[BigNumber]]>  @<Provider-getGasPrice> @SRC<providers/base-provider>
 Returns a //best guess// of the [[gas-price]] to use in a transaction.
 
+_code: Network Status Examples @lang<javascript>
 
-_subsection: Transactions Methods
+// The network information
+provider.getNetwork()
+// <hide>
+//!
+network = utils.shallowCopy(_)
+delete network._defaultProvider
+network
+// </hide>
+//!
 
-_property: provider.call(transaction [ , blockTag = "latest" ]) => Promise<string<[[hexstring]]>>  @<providers-call> @SRC<providers/base-provider>
+// The current block number
+provider.getBlockNumber()
+//!
+
+// Get the current suggested gas price (in wei)...
+gasPrice = await provider.getGasPrice()
+//! async gasPrice
+
+// ...often this gas price is easier to understand or
+// display to the user in gwei (giga-wei, or 1e9 wei)
+utils.formatUnits(gasPrice, "gwei")
+//!
+
+
+_subsection: Transactions Methods  @<Provider--transaction-methods>
+
+_property: provider.call(transaction [ , blockTag = latest ]) => Promise<string<[[DataHexString]]>>  @<Provider-call> @SRC<providers/base-provider>
 Returns the result of executing the //transaction//, using //call//. A call
 does not require any ether, but cannot change any state. This is useful
 for calling gettings on Contracts.
 
-_property: provider.estimateGas(transaction) => Promise<[[bignumber]]>  @<providers-estimategas> @SRC<providers/base-provider>
+_property: provider.estimateGas(transaction) => Promise<[[BigNumber]]>  @<Provider-estimateGas> @SRC<providers/base-provider>
 Returns an estimate of the amount of gas that would be required to submit //transaction//
 to the network.
 
@@ -91,48 +156,171 @@ An estimate may not be accurate since there could be another transaction
 on the network that was not accounted for, but after being mined affected
 relevant state.
 
-_property: provider.sendTransaction(transaction) => Promise<[[provider-transactionresponse]]>  @<providers-sendtransaction> @SRC<providers/base-provider>
+_property: provider.sendTransaction(transaction) => Promise<[[providers-TransactionResponse]]>  @<Provider-sendTransaction> @SRC<providers/base-provider>
 Submits //transaction// to the network to be mined. The //transaction// **must** be signed,
 and be valid (i.e. the nonce is correct and the account has sufficient balance to pay
 for the transaction).
 
-_property: provider.waitForTransaction(transactionHash) => Promise<[[provider-receipt]]>  @<providers-waitfortransaction> @SRC<providers/base-provider>
+_property: provider.waitForTransaction(hash [ , confirms = 1 [ , timeout ] ]) => Promise<[TxReceipt](providers-TransactionReceipt)>  @<Provider-waitForTransaction> @SRC<providers/base-provider>
 Returns a Promise which will not resolve until //transactionHash// is mined.
 
 
-_subsection: Event Emitter Methods
+_subsection: Event Emitter Methods @<Provider--event-methods>
 
 Explain events here...
 
-_property: provider.on(eventName, listener) => this  @<providers-on> @SRC<providers/base-provider>
+_property: provider.on(eventName, listener) => this  @<Provider-on> @SRC<providers/base-provider>
 Add a //listener// to be triggered for each //eventName//.
 
-_property: provider.once(eventName, listener) => this  @<providers-once> @SRC<providers/base-provider>
+_property: provider.once(eventName, listener) => this  @<Provider-once> @SRC<providers/base-provider>
 Add a //listener// to be triggered for only the next //eventName//,
 at which time it be removed.
 
-_property: provider.emit(eventName, ...args) => boolean  @<providers-emit> @SRC<providers/base-provider>
+_property: provider.emit(eventName, ...args) => boolean  @<Provider-emit> @SRC<providers/base-provider>
 Notify all listeners of //eventName//, passing //args// to each listener. This
 is generally only used internally.
 
-_property: provider.off(eventName [ , listener ]) => this  @<providers-off> @SRC<providers/base-provider>
+_property: provider.off(eventName [ , listener ]) => this  @<Provider-off> @SRC<providers/base-provider>
 Remove a //listener// for //eventName//. If no //listener// is provided,
 all listeners for //eventName// are removed.
 
-_property: provider.removeAllListeners([ eventName ]) => this  @<providers-removealllisteners> @SRC<providers/base-provider>
+_property: provider.removeAllListeners([ eventName ]) => this  @<Provider-removeAllListeners> @SRC<providers/base-provider>
 Remove all the listeners for //eventName//. If no //eventName// is provided,
 **all** events are removed.
 
-_property: provider.listenerCount([ eventName ]) => number  @<providers-listenercount> @SRC<providers/base-provider>
+_property: provider.listenerCount([ eventName ]) => number  @<Provider-listenerCount> @SRC<providers/base-provider>
 Returns the number of listeners for //eventName//. If no //eventName// is
 provided, the total number of listeners is returned.
 
-_property: provider.listeners(eventName) => Array<Listener>  @<providers-listeners> @SRC<providers/base-provider>
+_property: provider.listeners(eventName) => Array<Listener>  @<Provider-listeners> @SRC<providers/base-provider>
 Returns the list of Listeners for //eventName//.
 
 
-_subsection: Inspection Methods
+_heading: Events  @<Provider--events>
 
-_property: Provider.isProvider(object) => boolean  @<providers-isprovider> @SRC<abstract-provider>
+Any of the following may be used as the //eventName// in the above methods.
+
+_definition: **Log Filter**
+
+A filter is an object, representing a contract log Filter, which has the optional
+properties ``address`` (the source contract) and ``topics`` (a topic-set to match).
+
+If ``address`` is unspecified, the filter matches any contract address.
+
+See events for more information on how to specify topic-sets.
+
+_definition: **Topic-Set Filter**
+
+The value of a **Topic-Set Filter** is a array of Topic-Sets.
+
+This event is identical to a //Log Filter// with the address omitted (i.e. from
+any contract).
+
+_definition: **Transaction Filter**
+
+The value of a **Transaction Filter** is any transaction hash.
+
+This event is emitted on every block that is part of a chain that
+includes the given mined transaction. It is much more common that the
+[once](Provider-once) method is used than the [on](Provider-on) method.
+
+_null:
+
+In addition to transaction and filter events, there are several named
+events.
+
+_table: Named Provider Events @style<full>
+
+$Block:    emitted when a new block is mined
+$Error:    emitted on any error
+$Pending:  emitted when a new transaction enters the memory pool; only
+           certain providers offer this event and may require
+           running your own node for reliable results
+$WillPoll: emitted prior to a polling loop is about to begin;
+           //(very rarely used by most developers)//
+$DidPoll:  emitted after all events from a polling loop are emitted;
+           //(very rarely used by most developers)//
+$Poll:     emitted during each poll cycle after `blockNumber` is updated
+           (if changed) and before any other events (if any) are emitted
+           during the poll loop;
+           //(very rarely used by most developers)//
+$Debug:    each Provider may use this to emit useful debugging information
+           and the format is up to the developer;
+           //(very rarely used by most developers)//
+
+|   **Event Name**    |  **Arguments**                   <|   **Description**  <<<|
+|    ``"block"``      |   //blockNumber//                <| $Block             <<<|
+|    ``"error"``      |   //error//                      <| $Error             <<<|
+|    ``"pending"``    |   //pendingTransaction//         <| $Pending           <<<|
+|    ``"willPoll"``   |   //pollId//                     <| $WillPoll          <<<|
+|    ``"poll"``       |   //pollId//, //blockNumber//    <| $Poll              <<<|
+|    ``"didPoll"``    |   //pollId//                     <| $DidPoll           <<<|
+|    ``"debug"``      |   provider dependent             <| $Debug             <<<|
+
+
+_code: Events Example @lang<javascript>
+
+// <hide>
+const txHash = utils.id("dummy-data");
+const myAddress = ethers.constants.HashZero;
+const myOtherAddress = ethers.constants.HashZero;
+// </hide>
+
+provider.on("block", (blockNumber) => {
+    // Emitted on every block change
+})
+
+
+provider.once(txHash, (transaction) => {
+    // Emitted when the transaction has been mined
+})
+
+
+// This filter could also be generated with the Contract or
+// Interface API. If address is not specified, any address
+// matches and if topics is not specified, any log matches
+filter = {
+    address: "dai.tokens.ethers.eth",
+    topics: [
+        utils.id("Transfer(address,address,uint256")
+    ]
+}
+provider.on(filter, (log, event) => {
+    // Emitted whenever a DAI token transfer occurs
+})
+
+
+// Notice this is an array of topic-sets and is identical to
+// using a filter with no address (i.e. match any address)
+topicSets = [
+    utils.id("Transfer(address,address,uint256"),
+    null,
+    [
+        myAddress,
+        myOtherAddress
+    ]
+]
+provider.on(topicSets, (log, event) => {
+    // Emitted any token is sent TO either address
+})
+
+
+provider.on("pending", (tx) => {
+    // Emitted when any new pending transaction is noticed
+});
+
+
+provider.on("error", (tx) => {
+    // Emitted when any error occurs
+});
+
+// <hide>
+// Make sure our documentation builds without waiting forever
+provider.removeAllListeners()
+// </hide>
+
+_subsection: Inspection Methods  @<Provider--inspection-methods>
+
+_property: Provider.isProvider(object) => boolean  @<Provider-isProvider> @SRC<abstract-provider>
 Returns true if and only if //object// is a Provider.
 

docs.wrm/api/providers/types.wrm

@@ -1,6 +1,6 @@
 _section: Types
 
-_subsection: BlockTag @<provider-blocktag>
+_subsection: BlockTag @<providers-BlockTag>
 A **BlockTag** specifies a specific location in the Blockchain.
 
 - **``"latest"``** -- The most recently mined block
@@ -10,16 +10,16 @@ A **BlockTag** specifies a specific location in the Blockchain.
 - **//number//** -- The block at this height
 - **//a negative number//** -- The block this many blocks ago
 
-_heading: EventType @<provider-eventtype>
+_heading: EventType @<providers-EventType>
 
 And **EventType** can be any of the following.
 
 - **//string//** -- TODO...
-- **//Array<string<[[datahexstring]]<32>> | Array<string<[[datahexstring]]<32>>>>//** -- TODO...
-- **//[[provider-eventfilter]]//** -- TODO...
+- **//Array<string<[[DataHexString]]<32>> | Array<string<[[DataHexString]]<32>>>>//** -- TODO...
+- **//[[providers-EventFilter]]//** -- TODO...
 
 
-_subsection: Network @<provider-network>
+_subsection: Network @<providers-Network>
 A **Network** represents an Etherem network.
 
 _property: network.name => string
@@ -33,12 +33,12 @@ _property: network.ensAddress => string<[[address]]>
 The address at which the ENS registry is deployed on this network.
 
 
-_subsection: Block @<provider-block>
+_subsection: Block @<providers-Block>
 
-_property: block.hash => string<[[datahexstring]]<32>>
+_property: block.hash => string<[[DataHexString]]<32>>
 The hash of this block.
 
-_property: block.parentHash => string<[[datahexstring]]<32>>
+_property: block.parentHash => string<[[DataHexString]]<32>>
 The hash of the previous block.
 
 _property: block.number => number
@@ -47,7 +47,7 @@ The height (number) of this block.
 _property: block.timestamp => number
 The timestamp of this block.
 
-_property: block.nonce => string<[[datahexstring]]>
+_property: block.nonce => string<[[DataHexString]]>
 The nonce used as part of the proof-of-work to mine this block.
 
 This property is generally of little interest developers.
@@ -57,14 +57,14 @@ The difficulty target required to be met by the miner of the block.
 
 This property is generally of little interest developers.
 
-_property: block.gasLimit => [[bignumber]]
+_property: block.gasLimit => [[BigNumber]]
 The maximum amount of gas that this block was permitted to use. This
 is a value that can be voted up or voted down by miners and is used
 to automatically adjust the bandwidth requirements of the network.
 
 This property is generally of little interest developers.
 
-_property: block.gasUsed => [[bignumber]]
+_property: block.gasUsed => [[BigNumber]]
 The total amount of gas used by all transactions in this block.
 
 _property: block.miner => string
@@ -82,51 +82,51 @@ Often only the hashes of the transactions included in a block are needed,
 so by default a block only contains this information, as it is
 substantially less data.
 
-_property: block.transactions => Array<string<[[datahexstring]]<32>>>
+_property: block.transactions => Array<string<[[DataHexString]]<32>>>
 A list of the transactions hashes for each transaction this block
 includes.
 
-_heading: BlockWithTransactions @<provider-blocktxs> @INHERIT<[Block](provider-block)>
+_heading: BlockWithTransactions @<providers-BlockWithTransactions> @INHERIT<[Block](providers-Block)>
 
 If all transactions for a block are needed, this object instead includes
 the full details on each transaction.
 
-_property: block.transactions => Array<[[provider-transactionresponse]]>
+_property: block.transactions => Array<[[providers-TransactionResponse]]>
 A list of the transactions this block includes.
 
 
 _subsection: Events and Logs
 
-_heading: EventFilter @<provider-eventfilter>
+_heading: EventFilter @<providers-EventFilter>
 
 _property: filter.address => string<[[address]]>
 The address to filter by, or ``null`` to match any address.
 
-_property: filter.topics => Array<string<[[datahexstring]]<32>> | Array<string<[[datahexstring]]<32>>>>
+_property: filter.topics => Array<string<[[DataHexString]]<32>> | Array<string<[[DataHexString]]<32>>>>
 The topics to filter by, or ``null`` to match any topics. Each entry represents an
 **AND** condition that must match, or may be ``null`` to match anything. If a given
 entry is an Array, then that entry is treated as an **OR** for any value in the entry.
 
-_heading: Filter @<provider-filter> @INHERIT<[[provider-eventfilter]]>
+_heading: Filter @<providers-Filter> @INHERIT<[[providers-EventFilter]]>
 
-_property: filter.fromBlock => [[provider-blocktag]]
+_property: filter.fromBlock => [[providers-BlockTag]]
 The starting block (inclusive) to search for logs matching the filter criteria.
 
-_property: filter.toBlock => [[provider-blocktag]]
+_property: filter.toBlock => [[providers-BlockTag]]
 The end block (inclusive) to search for logs matching the filter criteria.
 
-_heading: FilterByBlockHash @<provider-filterbyblockhash> @INHERIT<[[provider-eventfilter]]>
+_heading: FilterByBlockHash @<providers-FilterByBlockHash> @INHERIT<[[providers-EventFilter]]>
 
-_property: filter.blockHash => string<[[datahexstring]]<32>>
+_property: filter.blockHash => string<[[DataHexString]]<32>>
 The specific block (by its block hash) to search for logs matching the filter criteria.
 
 
-_heading: Log @<provider-log>
+_heading: Log @<providers-Log>
 
 _property: log.blockNumber => number
 The block height (number) of the block including the transaction of this log.
 
-_property: log.blockHash => string<[[datahexstring]]<32>>
+_property: log.blockHash => string<[[DataHexString]]<32>>
 The block hash of the block including the transaction of this log.
 
 _property: log.removed => boolean
@@ -141,13 +141,13 @@ The index of this log in the transaction.
 _property: log.address => string<[[address]]>
 The address of the contract that generated this log.
 
-_property: log.data => string<[[datahexstring]]>
+_property: log.data => string<[[DataHexString]]>
 The data included in this log.
 
-_property: log.topics => Array<string<[[datahexstring]]<32> > >
+_property: log.topics => Array<string<[[DataHexString]]<32> > >
 The list of topics (indexed properties) for this log.
 
-_property: log.transactionHash => string<[[datahexstring]]<32>>
+_property: log.transactionHash => string<[[DataHexString]]<32>>
 The transaction hash of the transaction of this log.
 
 _property: log.transactionIndex => number
@@ -159,7 +159,7 @@ The index of this log across all logs in the entire **block**.
 
 _subsection: Transactions
 
-_heading: TransactionRequest @<provider-transactionrequest>
+_heading: TransactionRequest @<providers-TransactionRequest>
 
 A transaction request describes a transaction that is to
 be sent to the network or otherwise processed.
@@ -177,16 +177,16 @@ _property: transactionRequest.nonce => number | Promise<number>
 The nonce for this transaction. This should be set to the number of
 transactions ever sent **from** this address.
 
-_property: transactionRequest.gasLimit => [[bignumber]] | Promise<[[bignumber]]>
+_property: transactionRequest.gasLimit => [[BigNumber]] | Promise<[[BigNumber]]>
 The maximum amount of gas this transaction is permitted to use.
 
-_property: transactionRequest.gasPrice => [[bignumber]] | Promise<[[bignumber]]>
+_property: transactionRequest.gasPrice => [[BigNumber]] | Promise<[[BigNumber]]>
 The price (in wei) per unit of gas this transaction will pay.
 
-_property: transactionRequest.data => [[datahexstring]] | Promise<[[datahexstring]]>
+_property: transactionRequest.data => [[DataHexString]] | Promise<[[DataHexString]]>
 The transaction data.
 
-_property: transactionRequest.value => [[bignumber]] | Promise<[[bignumber]]>
+_property: transactionRequest.value => [[BigNumber]] | Promise<[[BigNumber]]>
 The amount (in wei) this transaction is sending.
 
 _property: transactionRequest.chainId => number | Promise<number>
@@ -198,16 +198,16 @@ on any network. This can be **dangerous** and care should be taken, since it
 allows transactions to be replayed on networks that were possibly not
 intended.
 
-_heading: TransactionResponse @INHERIT<[[types-transaction]]> @<provider-transactionresponse>
+_heading: TransactionResponse @<providers-TransactionResponse> @INHERIT<[[Transaction]]>
 
-A **TransactionResponse** includes all properties of a [[types-transaction]] as well as several
+A **TransactionResponse** includes all properties of a [[Transaction]] as well as several
 properties that are useful once it has been mined.
 
 _property: transaction.blockNumber => number
 The number ("height") of the block this transaction was mined in. If the block has not been mined,
 this is ``null``.
 
-_property: transaction.blockHash => string<[[datahexstring]]<32>>
+_property: transaction.blockHash => string<[[DataHexString]]<32>>
 The hash of the block this transaction was mined in. If the block has not been mined,
 this is ``null``.
 
@@ -219,14 +219,14 @@ _property: transaction.confirmations => number
 The number of blocks that have been mined (including the initial block) since this
 transaction was mined.
 
-_property: transaction.raw => string<[[datahexstring]]>
+_property: transaction.raw => string<[[DataHexString]]>
 The serialized transaction.
 
-_property: transaction.wait([ confirmations = 1 ]) => Promise<[[provider-receipt]]> @<transaction>
+_property: transaction.wait([ confirmations = 1 ]) => Promise<[[providers-TransactionReceipt]]>
 Wait for //confirmations//. If 0, and the transaction has not been mined,
 ``null`` is returned.
 
-_heading: TransactionReceipt @<provider-receipt>
+_heading: TransactionReceipt @<providers-TransactionReceipt>
 
 _property: receipt.to => string<[[address]]>
 The address this transaction is to. This is ``null`` if the the
@@ -236,12 +236,12 @@ _property: receipt.from => string<[[address]]>
 The address this transaction is from.
 
 _property: receipt.contractAddress => string<[[address]]>
-If this transaction has a ``null` to address, it is an **init transaction**
+If this transaction has a ``null`` to address, it is an **init transaction**
 used to deploy a contract, in which case this is the address created by that
 contract.
 
-To compute a contract address, the [getContractAddress](utils-getcontractaddress)
-utility function can also be used with a [[provider-transactionresponse]]
+To compute a contract address, the [getContractAddress](utils-getContractAddress)
+utility function can also be used with a [[providers-TransactionResponse]]
 object, which requires the transaction nonce and the address of the sender.
 
 _property: receipt.transactionIndex => number
@@ -259,21 +259,21 @@ it could be used to verify a state transition with a fraud-proof
 only considering the single transaction; without it the full block
 must be considered.
 
-_property: receipt.gasUsed => [[bignumber]]
+_property: receipt.gasUsed => [[BigNumber]]
 The amount of gas actually used by this transaction.
 
-_property: receipt.logsBloom => string<[[datahexstring]]>
+_property: receipt.logsBloom => string<[[DataHexString]]>
 A [bloom-filter](link-wiki-bloomfilter), which
 incldues all the addresses and topics included in any log in this
 transaction.
 
-_property: receipt.blockHash => string<[[datahexstring]]<32>>
+_property: receipt.blockHash => string<[[DataHexString]]<32>>
 The block hash of the block that this transaction was included in.
 
-_property: receipt.transactionHash => string<[[datahexstring]]<32>>
+_property: receipt.transactionHash => string<[[DataHexString]]<32>>
 The transaction hash of this transaction.
 
-_property: receipt.logs => Array<[[provider-log]]>
+_property: receipt.logs => Array<[[providers-Log]]>
 All the logs emitted by this transaction.
 
 _property: receipt.blockNumber => number
@@ -284,7 +284,7 @@ _property: receipt.confirmations => number
 The number of blocks that have been mined since this transaction,
 including the actual block it was mined in.
 
-_property: receipt.cumulativeGasUsed => [[bignumber]]
+_property: receipt.cumulativeGasUsed => [[BigNumber]]
 For the block this transaction was included in, this is the sum of the
 gas used used by each transaction in the ordered list of transactions
 up to (and including) this transaction.

docs.wrm/api/signer.wrm

@@ -1,19 +1,36 @@
-_section: Signers
 
-A Signer represents...
+_section: Signers @<signers>
 
-_subsection: Signer @<signer> @SRC<abstract-signer:class.Signer>
+A **Signer** in //ethers// is an abstraction of an Ethereum Account,
+which can be used to sign messages and transactions and send
+signed transactions to the Ethereum Network to execute state
+changing operations.
 
-The **Signer** class is abstract and cannot be directly instaniated. Instead
-use one of the concreate sub-classes, such as the [[wallet]], [[void-signer]]
-or [[signer-jsonrpc]].
+The available operations depends largely on the sub-class used.
 
-_property: signer.connect(provider) => [[signer]]  @<signer-connect>
+For example, a Signer from MetaMask can send transactions and sign
+messages but cannot sign a transaction (without broadcasting it).
+
+The most common Signers you will encounter are:
+
+- [[Wallet]], which is a class which knows its private key and can
+  execute any operations with it
+- [[JsonRpcSigner]], which is connected to a [[JsonRpcProvider]] (or
+  sub-class) and is acquired using [getSigner](JsonRpcProvider-getSigner)
+
+_subsection: Signer @<Signer> @SRC<abstract-signer:class.Signer>
+
+The **Signer** class is abstract and cannot be directly instaniated.
+
+Instead use one of the concreate sub-classes, such as the [[Wallet]],
+[[VoidSigner]] or [[JsonRpcSigner]].
+
+_property: signer.connect(provider) => [[Signer]]  @<Signer-connect>
 
 Sub-classes **must** implement this, however they may simply throw an error
 if changing providers is not supported.
 
-_property: signer.getAddress() => Promise<string<[Address](address)>>  @<signer-getaddress> @SRC<abstract-signer:Signer.connect>
+_property: signer.getAddress() => Promise<string<[[address]]>>  @<Signer-getaddress> @SRC<abstract-signer:Signer.connect>
 Returns a Promise that resolves to the account address.
 
 This is a Promise so that a **Signer** can be designed around an
@@ -21,51 +38,52 @@ asynchronous source, such as  hardware wallets.
 
 Sub-classes **must** implement this.
 
-_property: Signer.isSigner(object) => boolean  @<signer-issigner> @SRC<abstract-signer>
+_property: Signer.isSigner(object) => boolean  @<Signer-isSigner> @SRC<abstract-signer>
 Returns true if an only if //object// is a **Signer**.
 
-_heading: Blockchain Methods @<signer-blockchain>
+_heading: Blockchain Methods @<Signer--blockchain-methods>
 
-_property: signer.getBalance([ blockTag = "latest" ]) => Promise<[[bignumber]]>  @<signer-getbalance> @SRC<abstract-signer>
+_property: signer.getBalance([ blockTag = "latest" ]) => Promise<[[BigNumber]]>  @<Signer-getBalance> @SRC<abstract-signer>
 Returns the balance of this wallet at //blockTag//.
 
-_property: signer.getChainId() => Promise<number>  @<signer-getchainid> @SRC<abstract-signer>
+_property: signer.getChainId() => Promise<number>  @<Signer-getChainId> @SRC<abstract-signer>
 Returns ths chain ID this wallet is connected to.
 
-_property: signer.getGasPrice() => Promise<[[bignumber]]>  @<signer-getgasprice> @SRC<abstract-signer>
+_property: signer.getGasPrice() => Promise<[[BigNumber]]>  @<Signer-getGasPrice> @SRC<abstract-signer>
 Returns the current gas price.
 
-_property: signer.getTransactionCount([ blockTag = "latest" ]) => Promise<number>  @<signer-gettransactioncount> @SRC<abstract-signer>
+_property: signer.getTransactionCount([ blockTag = "latest" ]) => Promise<number>  @<Signer-getTransactionCount> @SRC<abstract-signer>
 Returns the number of transactions this account has ever sent. This
 is the value required to be included in transactions as the ``nonce``.
 
-_property: signer.call(transactionRequest) => Promise<string<[[datahexstring]]>>  @<signer-call> @SRC<abstract-signer>
+_property: signer.call(transactionRequest) => Promise<string<[[DataHexString]]>>  @<Signer-call> @SRC<abstract-signer>
 Returns the result of calling using the //transactionRequest//, with this
 account address being used as the ``from`` field.
 
-_property: signer.estimateGas(transactionRequest) => Promise<[[bignumber]]>  @<signer-estimategas> @SRC<abstract-signer>
+_property: signer.estimateGas(transactionRequest) => Promise<[[BigNumber]]>  @<Signer-estimateGas> @SRC<abstract-signer>
 Returns the result of estimating the cost to send the //transactionRequest//,
 with this account address being used as the ``from`` field.
 
-_property: signer.resolveName(ensName) => Promise<string<[Address](address)>> @<signer-resolvename> @SRC<abstract-signer>
+_property: signer.resolveName(ensName) => Promise<string<[[address]]>> @<Signer-resolveName> @SRC<abstract-signer>
 Returns the address associated with the //ensName//.
 
 
-_heading: Signing
+_heading: Signing @<Signer--signing-methods>
 
-_property: signer.signMessage(message) => Promise<string<[FlatSignature](signature-flat)>> @<signer-signmessage>
-This returns a Promise which resolves to the [[signature-flat]]
+_property: signer.signMessage(message) => Promise<string<[RawSignature](signature-raw)>> @<Signer-signMessage>
+This returns a Promise which resolves to the [[signature-raw]]
 of //message//.
 
 Sub-classes **must** implement this, however they may throw if signing a
-message is not supported.
+message is not supported, such as in a Contract-based Wallet or
+Meta-Transaction-based Wallet.
 
 _note: Note
 
 If //message// is a string, it is **treated as a string** and
 converted to its representation in UTF8 bytes.
 
-**If and only if** a message is a [[bytes]] will it be treated as
+**If and only if** a message is a [[Bytes]] will it be treated as
 binary data.
 
 For example, the string ``"0x1234"`` is 6 characters long (and in
@@ -78,31 +96,34 @@ string, it **must** be converted to an array first, using the
 
 _null:
 
-_property: signer.signTransaction(transactionRequest) => Promise<string<[[datahexstring]]>> @<signer-signtransaction>
+_property: signer.signTransaction(transactionRequest) => Promise<string<[[DataHexString]]>> @<Signer-signTransaction>
 Returns a Promise which resolves to the signed transaction of the
 //transactionRequest//. This method does not populate any missing fields.
 
 Sub-classes **must** implement this, however they may throw if signing a
-transaction is not supported.
+transaction is not supported, which is common for security reasons in many
+clients.
 
-_property: signer.sendTransaction(transactionRequest) => Promise<[[provider-transactionresponse]]> @<signer-sendtransaction>
+_property: signer.sendTransaction(transactionRequest) => Promise<[[providers-TransactionResponse]]> @<Signer-sendTransaction>
 This method populates the transactionRequest with missing fields, using
-[populateTransaction](signer-populatetransaction) and returns a Promise which resolves to the transaction.
+[populateTransaction](Signer-populateTransaction) and returns a Promise which resolves to the transaction.
 
-Sub-classes **must** implement this, however they may throw if signing a
-transaction is not supported.
+Sub-classes **must** implement this, however they may throw if sending a
+transaction is not supported, such as the [[VoidSigner]] or if the
+Wallet is offline and not connected to a [[Provider]].
 
-_heading: Sub-Classes @<signer-subclassing>
+_heading: Sub-Classes @<Signer--subclassing>
 
 It is very important that all important properties of a **Signer** are
 **immutable**. Since Ethereum is very asynchronous and deals with critical
 data (such as ether and other potentially valuable crypto assets), keeping
-properties such as the //provider// and //address// static helps prevent
-serious issues.
+properties such as the //provider// and //address// static throughout the
+life-cycle of the Signer helps prevent serious issues and many other classes
+and libraries make this assumption.
 
-A sub-class **must** call ``super()``.
+A sub-class **must** extend Sigenr and **must** call ``super()``.
 
-_property: signer.checkTransaction(transactionRequest) => [[provider-transactionrequest]]  @<signer-checktransaction> @SRC<abstract-signer>
+_property: signer.checkTransaction(transactionRequest) => [[providers-TransactionRequest]]  @<Signer-checkTransaction> @SRC<abstract-signer>
 This is generally not required to be overridden, but may needed to provide
 custom behaviour in sub-classes.
 
@@ -110,11 +131,12 @@ This should return a **copy** of the //transactionRequest//, with any properties
 needed by ``call``, ``estimateGas`` and ``populateTransaction`` (which is used
 by sendTransaction). It should also throw an error if any unknown key is specified.
 
-The default implementation checks only valid [[provider-transactionrequest]] properties
-exist and adds ``from`` to the transaction if it does not exist, or verifies it is equal
-to the Signer's address if it does exist.
+The default implementation checks only valid [[providers-TransactionRequest]] properties
+exist and adds ``from`` to the transaction if it does not exist.
 
-_property: signer.populateTransaction(transactionRequest) => Promise<[[provider-transactionrequest]]> @<signer-populatetransaction> @SRC<abstract-signer>
+If there is a ``from`` field it **must** be verified to be equal to the Signer's address.
+
+_property: signer.populateTransaction(transactionRequest) => Promise<[[providers-TransactionRequest]]> @<Signer-populateTransaction> @SRC<abstract-signer>
 This is generally not required to be overridden, but may needed to provide
 custom behaviour in sub-classes.
 
@@ -127,58 +149,139 @@ The default implementation calls ``checkTransaction`` and resolves to if it is a
 ENS name, adds ``gasPrice``, ``nonce``, ``gasLimit`` and ``chainId`` based on the
 related operations on Signer.
 
-_subsection: Wallet  @<wallet> @INHERIT<[[externally-owned-account]] and [[signer]]> @SRC<wallet:class.Wallet>
 
-The Wallet class inherits [[signer]] and can sign transactions and messages
+_subsection: Wallet  @<Wallet> @INHERIT<[[ExternallyOwnedAccount]] and [[Signer]]> @SRC<wallet:class.Wallet>
+
+The Wallet class inherits [[Signer]] and can sign transactions and messages
 using a private key as a standard Externally Owned Account (EOA).
 
-_property: new ethers.Wallet(privateKey [ , provider ])  @<wallet-constructor> @SRC<wallet:constructor.Wallet>
+_property: new ethers.Wallet(privateKey [ , provider ])  @<Wallet-constructor> @SRC<wallet:constructor.Wallet>
 Create a new Wallet instance for //privateKey// and optionally
 connected to the //provider//.
 
-_property: ethers.Wallet.createRandom( [ options = { } ]) => [[wallet]]  @<wallet-createrandom> @SRC<wallet>
+_property: ethers.Wallet.createRandom( [ options = { } ]) => [[Wallet]]  @<Wallet-createRandom> @SRC<wallet>
 Returns a new Wallet with a random private key, generated from
 cryptographically secure entropy sources. If the current environment
 does not have a secure entropy source, an error is thrown.
 
-_property: ethers.Wallet.fromEncryptedJson(json, password [ , progress ])  => Promise<[[wallet]]> @<wallet-fromencryptedjson> @SRC<wallet>
-Create an instance from an encrypted JSON wallet. If //progress//
-is provided it will be called during decryption with a value between 0 and
-1 indicating the progress towards completion.
+Wallets created using this method will have a mnemonic.
 
-_property: ethers.Wallet.fromMnemonic(mnemonic [ , path, [ wordlist ] ]) => [[wallet]]
+_property: ethers.Wallet.fromEncryptedJson(json, password [ , progress ])  => Promise<[[Wallet]]> @<Wallet-fromEncryptedJson> @SRC<wallet>
+Create an instance from an encrypted JSON wallet.
+
+If //progress// is provided it will be called during decryption
+with a value between 0 and 1 indicating the progress towards
+completion.
+
+_property: ethers.Wallet.fromEncryptedJsonSync(json, password)  => [[Wallet]] @<Wallet-fromEncryptedJsonSync> @SRC<wallet>
+Create an instance from an encrypted JSON wallet.
+
+This operation will operate synchronously which will lock up the user
+interface, possibly for a non-trivial duration. Most applications should
+use the asynchronous ``fromEncryptedJson`` instead.
+
+_property: ethers.Wallet.fromMnemonic(mnemonic [ , path, [ wordlist ] ]) => [[Wallet]] @<Wallet.fromMnemonic>
 Create an instance from a mnemonic phrase.
 
-If path is not specified, the Ethereum default path is used (i.e. m/44'/60'/0'/0/0).
+If path is not specified, the Ethereum default path is used (i.e. ``m/44'/60'/0'/0/0``).
 
 If wordlist is not specified, the English Wordlist is used.
 
-_heading: Properties
+_heading: Properties @<Wallet--properties>
 
-_property: wallet.address => string<[Address](address)>
+_property: wallet.address => string<[[address]]>
 The address for the account this Wallet represents.
 
-_property: wallet.provider => [[provider]]
-The provider this wallet is connected to, which will ge used for any [[signer-blockchain]]
+_property: wallet.provider => [[Provider]]
+The provider this wallet is connected to, which will ge used for any [[Signer--blockchain-methods]]
 methods. This can be null.
 
 _note: Note
 A **Wallet** instance is immuatable, so if you wish to change the Provider, you
-may use the [connect](signer-connect) method to create a new instance connected
+may use the [connect](Signer-connect) method to create a new instance connected
 to the desired provider.
 
-_property: wallet.publicKey => string<[[datahexstring]]<65>>
+_property: wallet.publicKey => string<[[DataHexString]]<65>>
 The uncompressed public key for this Wallet represents.
 
-_heading: Methods
+_heading: Methods @<Wallet--methods>
 
-_property: wallet.encrypt(password, [ options = { }, [ progress ] ]) => Promise<string>
+_property: wallet.encrypt(password, [ options = { }, [ progress ] ]) => Promise<string> @<Wallet-encrypt>
 
 Encrypt the wallet using //password// returning a Promise which resolves
 to a JSON wallet.
 
+If //progress// is provided it will be called during decryption
+with a value between 0 and 1 indicating the progress towards
+completion.
 
-_subsection: VoidSigner  @<void-signer> @INHERIT<[[signer]]> @SRC<abstract-signer:class.VoidSigner>
+_code: Wallet Examples @lang<javascript>
+
+// Create a wallet instance from a mnemonic...
+mnemonic = "announce room limb pattern dry unit scale effort smooth jazz weasel alcohol"
+walletMnemonic = Wallet.fromMnemonic(mnemonic)
+
+// ...or from a private key
+walletPrivateKey = new Wallet(walletMnemonic.privateKey)
+
+walletMnemonic.address === walletPrivateKey.address
+//!
+
+// The address as a Promise per the Signer API
+walletMnemonic.getAddress()
+//!
+
+// A Wallet address is also available synchronously
+walletMnemonic.address
+//!
+
+// The internal cryptographic components
+walletMnemonic.privateKey
+//!
+walletMnemonic.publicKey
+//!
+
+// The wallet mnemonic
+walletMnemonic.mnemonic
+//!
+
+// Note: A wallet created with a private key does not
+//       have a mnemonic (the derivation prevents it)
+walletPrivateKey.mnemonic
+//!
+
+// Signing a message
+walletMnemonic.signMessage("Hello World")
+//!
+
+tx = {
+  to: "0x8ba1f109551bD432803012645Ac136ddd64DBA72",
+  value: utils.parseEther("1.0")
+}
+
+// Signing a transaction
+walletMnemonic.signTransaction(tx)
+//!
+
+// The connect method returns a new instance of the
+// Wallet connected to a provider
+wallet = walletMnemonic.connect(provider)
+
+// Querying the network
+wallet.getBalance();
+//!
+wallet.getTransactionCount();
+//!
+
+// Sending ether
+wallet.sendTransaction(tx)
+// <hide>
+//! error
+// </hide>
+
+
+
+_subsection: VoidSigner  @<VoidSigner> @INHERIT<[[Signer]]> @SRC<abstract-signer:class.VoidSigner>
 
 A **VoidSigner** is a simple Signer which cannot sign.
 
@@ -189,28 +292,64 @@ will be carried.
 For example, the ``call`` operation will automatically have the
 provided address passed along during the execution.
 
-_property: new ethers.VoidSigner(address) => [[void-signer]]
+_property: new ethers.VoidSigner(address [ , provider ]) => [[VoidSigner]]
 Create a new instance of a **VoidSigner** for //address//.
 
-_property: voidSigner.address => string<[Address](address)>
+_property: voidSigner.address => string<[[address]]>
 The address of this **VoidSigner**.
 
+_code: VoidSigner Pre-flight Example @lang<javascript>
 
-_subsection: ExternallyOwnedAccount  @<externally-owned-account>
+address = "0x8ba1f109551bD432803012645Ac136ddd64DBA72"
+signer = new ethers.VoidSigner(address, provider)
+
+// The DAI token contract
+abi = [
+  "function balanceOf(address) view returns (uint)",
+  "function transfer(address, uint) returns (bool)"
+]
+contract = new ethers.Contract("dai.tokens.ethers.eth", abi, signer)
+
+// <hide>
+//!
+// </hide>
+// Get the number of tokens for this account
+tokens = await contract.balanceOf(signer.getAddress())
+//! async tokens
+
+//
+// Pre-flight (check for revert) on DAI from the signer
+//
+// Note: We do not have the private key at this point, this
+//       simply allows us to check what would happen if we
+//       did. This can be useful to check before prompting
+//       a request in the UI
+//
+
+// This will pass since the token balance is available
+contract.callStatic.transfer("donations.ethers.eth", tokens)
+//!
+
+// This will fail since it is greater than the token balance
+contract.callStatic.transfer("donations.ethers.eth", tokens.add(1))
+//! error
+
+
+_subsection: ExternallyOwnedAccount  @<ExternallyOwnedAccount>
 
 This is an interface which contains a minimal set of properties
 required for Externally Owned Accounts which can have certain
 operations performed, such as encoding as a JSON wallet.
 
-_property: eoa.address => string<[Address](address)>
+_property: eoa.address => string<[[address]]>
 
 The [[address]] of this EOA.
 
-_property: eoa.privateKey => string<[[datahexstring]]<32>>
+_property: eoa.privateKey => string<[[DataHexString]]<32>>
 
 The privateKey of this EOA
 
-_property: eoa.mnemonic => [[hdnode-mnemonic]]
+_property: eoa.mnemonic => [[Mnemonic]]
 
 //Optional//. The account HD mnemonic, if it has one and can be
 determined. Some sources do not encode the mnemonic, such as an

docs.wrm/api/utils/abi/coder.wrm

@@ -0,0 +1,48 @@
+_section: AbiCoder @<AbiCoder> @SRC<abi:class.AbiCoder>
+
+The **AbiCoder** is a collection of Coders which can be used to
+encode and decode the binary data formats used to interoperate
+between the EVM and higher level libraries.
+
+Most developers will never need to use this class directly, since
+the [[Interface]] class greatly simplifies these operations.
+
+
+_subsection: Creating Instance @<AbiCoder--creating>
+
+For the most part, there should never be a need to manually create
+an instance of an [[AbiCoder]], since one is created with the
+default coersion function when the library is loaded which can
+be used universally.
+
+This is likely only needed by those with specific needs to override
+how values are coerced after they are decoded from their binary format.
+
+_property: new ethers.utils.AbiCoder([coerceFunc]) @SRC<abi:constructor.AbiCoder>
+
+Create a new AbiCoder instance, which will call the //coerceFunc// on every
+decode, where the result of the call will be used in the Result.
+
+The function signature is `(type, value)`, where the //type// is the string
+describing the type and the //value// is the processed value from the underlying
+Coder.
+
+If the callback throws, the Result will contain a property that when accessed will
+throw, allowing for higher level libraries to recover from data errors.
+
+_property: ethers.utils.defaultAbiCoder => [[AbiCoder]]
+
+An [[AbiCoder]] created when the library is imported which is used by
+the [[Interface]].
+
+_subsection: Coding Methods @<AbiCoder--methods>
+
+_property: abiCoder.encode(types, values) => string<[[DataHexString]]> @<AbiCoder-encode> @SRC<abi/abi-coder>
+
+Encode the array //values// according the array of //types//, each of which may be a
+string or a [[ParamType]].
+
+_property: abiCoder.decode(types, data) => [[Result]] @<AbiCoder-decode> @SRC<abi/abi-coder>
+
+Decode the //data// according to the array of //types//, each of which may be a
+string or [[ParamType]].

docs.wrm/api/utils/abi/formats.wrm

@@ -0,0 +1,11 @@
+_section: ABI Formats @<abi-formats>
+
+@TODO: Expand this section
+
+_subsection: Human-Readable ABI @<abi-formats--human-readable-abi>
+
+See [Human-Readable Abi](link-ricmoo-humanreadableabi).
+
+_subsection: Solidity JSON ABI @<abi-formats--solidity>
+
+See [Solidity compiler](link-solc-output).

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

@@ -1,4 +1,4 @@
-_section: Fragments
+_section: Fragments  @<fragments>
 
 Explain an ABI.
 
@@ -10,7 +10,7 @@ The **JSON ABI Format** is the format that is
 [output from the Solidity compiler](link-solc-output).
 
 A JSON serialized object is always a string, which represents an Array
-of Objects, where each Object has various properties describing the [[abi-fragment]] of the ABI.
+of Objects, where each Object has various properties describing the [[Fragment]] of the ABI.
 
 The deserialied JSON string (which is a normal JavaScript Object) may
 also be passed into any function which accepts a JSON String ABI.
@@ -22,9 +22,9 @@ The Human-Readable ABI was
 [article](link-ricmoo-humanreadableabi)
 
 
-_heading: Output Formats @<abi-outputformats> @SRC<abi/fragments:FormatTypes>
+_heading: Output Formats @<fragments--output-formats> @SRC<abi/fragments:FormatTypes>
 
-Each [[abi-fragment]] and [[abi-paramtype]] may be output using its ``format``
+Each [[Fragment]] and [[ParamType]] may be output using its ``format``
 method.
 
 _property: ethers.utils.FragmentTypes.full => string
@@ -37,7 +37,7 @@ _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).
+reconstruct the original Fragment using [Fragment&thinsp;.&thinsp;from](Fragment-from).
 
 _property: ethers.utils.FragmentTypes.json => string
 
@@ -51,55 +51,55 @@ signature hash or an event topic hash.
 
 _warning: Note
 
-The ``sighash`` format is **insufficient** to re-create the original [[abi-fragment]],
+The ``sighash`` format is **insufficient** to re-create the original [[Fragment]],
 since it discards modifiers such as indexed, anonymous, stateMutability, etc.
 
 
-_subsection: Fragment @<abi-fragment> @SRC<abi/fragments:class.Fragment>
+_subsection: Fragment @<Fragment> @SRC<abi/fragments:class.Fragment>
 
 An ABI is a collection of **Fragments**, where each fragment specifies:
 
-- An [Event](abi-eventfragment)
-- A [Function](abi-functionfragment)
-- A [Constructor](abi-constructorfragment)
+- An [Event](EventFragment)
+- A [Function](FunctionFragment)
+- A [Constructor](ConstructorFragment)
 
 _heading: Properties
 
 _property: fragment.name => string
 
 This is the name of the Event or Function. This will be null for
-a [[abi-constructorfragment]].
+a [[ConstructorFragment]].
 
 _property: fragment.type => string
 
-This is a string which indicates the type of the [[abi-fragment]]. This
+This is a string which indicates the type of the [[Fragment]]. This
 will be one of:
 
 - ``constructor``
 - ``event``
 - ``function``
 
-_property: fragment.inputs => Array<[[abi-paramtype]]>
+_property: fragment.inputs => Array<[[ParamType]]>
 
-This is an array of of each [[abi-paramtype]] for the input parameters to
+This is an array of of each [[ParamType]] for the input parameters to
 the Constructor, Event of Function.
 
 _heading: Methods
 
-_property: ethers.utils.Fragment.from(objectOrString) => [[abi-fragment]] @<abi-fragment-from> @SRC<abi/fragments:Fragment.from>
+_property: ethers.utils.Fragment.from(objectOrString) => [[Fragment]] @<Fragment-from> @SRC<abi/fragments:Fragment.from>
 
 Returns a 
 
-_property: ethers.utils.Fragment.isFragment(object) => boolean @<abi-isfragment> @SRC<abi/fragments:Fragment.isFragment>
+_property: ethers.utils.Fragment.isFragment(object) => boolean @<Fragment-isFragment> @SRC<abi/fragments:Fragment.isFragment>
 
 Tra lal al
 
 
-_subsection: ConstructorFragment @<abi-constructorfragment> @INHERIT<[[abi-fragment]]> @SRC<abi/fragments:class.ConstructorFragment>
+_subsection: ConstructorFragment @<ConstructorFragment> @INHERIT<[[Fragment]]> @SRC<abi/fragments:class.ConstructorFragment>
 
 _heading: Properties
 
-_property: fragment.gas => [[bignumber]]
+_property: fragment.gas => [[BigNumber]]
 
 This is the gas limit that should be used during deployment. It may be
 null.
@@ -118,16 +118,16 @@ This is the state mutability of the constructor. It can be any of:
 
 _heading: Methods
 
-_property: ethers.utils.ConstructorFragment.from(objectOrString) => [[abi-constructorfragment]] @<abi-constructorfragment-from> @SRC<abi/fragments:ConstructorFragment.from>
+_property: ethers.utils.ConstructorFragment.from(objectOrString) => [[ConstructorFragment]] @<ConstructorFragment-from> @SRC<abi/fragments:ConstructorFragment.from>
 
 Tra la la...
 
-_property: ethers.utils.ConstructorFragment.isConstructorFragment(object) => boolean @<abi-isconstructorfragment> @SRC<abi/fragments:ConstructorFragment.isConstructorFragment>
+_property: ethers.utils.ConstructorFragment.isConstructorFragment(object) => boolean @<ConstructorFragment-isConstructorFragment> @SRC<abi/fragments:ConstructorFragment.isConstructorFragment>
 
 Tra lal al
 
 
-_subsection: EventFragment @<abi-eventfragment> @INHERIT<[[abi-fragment]]> @SRC<abi/fragments:class.EventFragment>
+_subsection: EventFragment @<EventFragment> @INHERIT<[[Fragment]]> @SRC<abi/fragments:class.EventFragment>
 
 _heading: Properties
 
@@ -138,16 +138,16 @@ topic hash as topic0 when creating a log.
 
 _heading: Methods
 
-_property: ethers.utils.EventFragment.from(objectOrString) => [[abi-eventfragment]] @<abi-eventfragment-from> @SRC<abi/fragments:EventFragment.from>
+_property: ethers.utils.EventFragment.from(objectOrString) => [[EventFragment]] @<EventFragment-from> @SRC<abi/fragments:EventFragment.from>
 
 Tra la la...
 
-_property: ethers.utils.EventFragment.isEventFragment(object) => boolean @<abi-iseventfragment> @SRC<abi/fragments:EventFragment.isEventFragment>
+_property: ethers.utils.EventFragment.isEventFragment(object) => boolean @<EventFragment-isEventFragment> @SRC<abi/fragments:EventFragment.isEventFragment>
 
 Tra lal al
 
 
-_subsection: FunctionFragment @<abi-functionfragment> @INHERIT<[[abi-constructorfragment]]> @SRC<abi/fragments:class.FunctionFragment>
+_subsection: FunctionFragment @<FunctionFragment> @INHERIT<[[ConstructorFragment]]> @SRC<abi/fragments:class.FunctionFragment>
 
 _heading: Properties
 
@@ -165,22 +165,22 @@ This is the state mutability of the constructor. It can be any of:
 - ``pure``
 - ``view``
 
-_property: fragment.outputs => Array<[[abi-paramtype]]>
+_property: fragment.outputs => Array<[[ParamType]]>
 
 A list of the Function output parameters.
 
 _heading: Method
 
-_property: ethers.utils.FunctionFragment.from(objectOrString) => [[abi-functionfragment]] @<abi-functionfragment-from> @SRC<abi/fragments:ConstructorFragment.from>
+_property: ethers.utils.FunctionFragment.from(objectOrString) => [[FunctionFragment]] @<FunctionFragment-from> @SRC<abi/fragments:ConstructorFragment.from>
 
 Tra la la...
 
-_property: ethers.utils.FunctionFragment.isFunctionFragment(object) => boolean @<abi-isfunctionfragment> @SRC<abi/fragments:FunctionFragment.isFunctionFragment>
+_property: ethers.utils.FunctionFragment.isFunctionFragment(object) => boolean @<FunctionFragment-isFunctionFragment> @SRC<abi/fragments:FunctionFragment.isFunctionFragment>
 
 Tra lal al
 
 
-_subsection: ParamType @<abi-paramtype> @SRC<abi/fragments:class.ParamType>
+_subsection: ParamType @<ParamType> @SRC<abi/fragments:class.ParamType>
 
 The following examples will represent the Solidity parameter:
 
@@ -188,38 +188,38 @@ The following examples will represent the Solidity parameter:
 
 _heading: Properties
 
-_property: paramType.name => string @<abi-paramtype-name>
+_property: paramType.name => string @<ParamType-name>
 
 The local parameter name. This may be null for unnamed parameters. For example,
 the parameter definition ``string foobar`` would be ``foobar``.
 
-_property: paramType.type => string @<abi-paramtype-type>
+_property: paramType.type => string @<ParamType-type>
 
 The full type of the parameter, including tuple and array symbols. This may be null
 for unnamed parameters. For the above example, this would be ``foobar``.
 
-_property: paramType.basetype => string @<abi-paramtype-basetype>
+_property: paramType.baseType => string @<ParamType-baseType>
 
 The base type of the parameter. For primitive types (e.g. ``address``, ``uint256``, etc)
-this is equal to [type](abi-paramtype-type). For arrays, it will be the string ``array`` and for
+this is equal to [type](ParamType-type). For arrays, it will be the string ``array`` and for
 a tuple, it will be the string ``tuple``.
 
-_property: paramType.indexed => boolean @<abi-paramtype-indexed>
+_property: paramType.indexed => boolean @<ParamType-indexed>
 
 Whether the parameter has been marked as indexed. This **only** applies
-to parameters which are part of an [[abi-eventfragment]].
+to parameters which are part of an [[EventFragment]].
 
-_property: paramType.arrayChildren => [[abi-paramtype]] @<abi-paramtype-arraychildren>
+_property: paramType.arrayChildren => [[ParamType]] @<ParamType-arrayChildren>
 
 The type of children of the array. This is null for for any parameter
 wjhich is not an array.
 
-_property: paramType.arrayLength => number @<abi-paramtype-arraylength>
+_property: paramType.arrayLength => number @<ParamType-arrayLength>
 
 The length of the array, or ``-1`` for dynamic-length arrays. This is
 null for parameters which is not arrays.
 
-_property: paramType.components => Array<[[abi-paramtype]]> @<abi-paramtype-components>
+_property: paramType.components => Array<[[ParamType]]> @<ParamType-components>
 
 The components of a tuple. This is null for non-tuple parameters.
 
@@ -232,10 +232,10 @@ _property: paramType.format([ outputType = sighash ])
 
 Tra la la...
 
-_property: ethers.utils.ParamType.from(objectOrString) => [[abi-paramtype]] @<abi-paramtype-from> @SRC<abi/fragments:ParamType.from>
+_property: ethers.utils.ParamType.from(objectOrString) => [[ParamType]] @<ParamType-from> @SRC<abi/fragments:ParamType.from>
 
 Tra la la...
 
-_property: ethers.utils.ParamType.isParamType(object) => boolean @<abi-paramtype-isparamtype> @SRC<abi/fragments:ParamType.isParamType>
+_property: ethers.utils.ParamType.isParamType(object) => boolean @<ParamType-isParamType> @SRC<abi/fragments:ParamType.isParamType>
 
 Tra la la...

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

@@ -1,5 +1,21 @@
 _section: Application Binary Interface @NAV<ABI>
 
+An **Application Binary Interface** (ABI) is a collection of
+[Fragments](Fragment) which specify how to interact with
+various components of a Contract.
+
+An [[Interface]] helps organize Fragments by type as well
+as provides the functionality required to encode, decode and
+work with each component.
+
+Most developers will not require this low-level access to encoding
+and decoding the binary data on the network and will most likely
+use a [[Contract]] which provides a more convenient interface. Some
+framework, tool developers or developers using advanced techniques
+may find these classes and utilities useful.
+
 _toc:
-  interface
+  coder
+  formats
   fragments
+  interface

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

@@ -1,4 +1,4 @@
-_section: Interface @<abi-interface> @SRC<abi/interface:class.Interface>
+_section: Interface @<Interface> @SRC<abi/interface:class.Interface>
 
 The **Interface** Class abstracts the encoding and decoding required
 to interact with contracts on the Ethereum network.
@@ -12,7 +12,7 @@ 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
+_subsection: Creating Instances @<Interface--creating>
 
 _property: new ethers.utils.Interface(abi) @SRC<abi/interface:constructor.Interface>
 Create a new **Interface** from a JSON string or object representing
@@ -26,22 +26,22 @@ 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
+_subsection: Properties @<Interface--properties>
 
-_property: interface.fragments => Array<[[abi-fragment]]>
-All the [Fragments](abi-fragment) in the interface.
+_property: interface.fragments => Array<[[Fragment]]>
+All the [Fragments](Fragment) in the interface.
 
-_property: interface.events => Array<[[abi-eventfragment]]>
-All the [Event Fragments](abi-eventfragment) in the interface.
+_property: interface.events => Array<[[EventFragment]]>
+All the [Event Fragments](EventFragment) in the interface.
 
-_property: interface.functions => Array<[[abi-functionfragment]]>
-All the [Function Fragments](abi-functionfragment) in the interface.
+_property: interface.functions => Array<[[FunctionFragment]]>
+All the [Function Fragments](FunctionFragment) in the interface.
 
-_property: interface.deploy => [[abi-constructorfragment]]
-The [Constructor Fragments](abi-constructorfragment) for the interface.
+_property: interface.deploy => [[ConstructorFragment]]
+The [Constructor Fragments](ConstructorFragment) for the interface.
 
 
-_subsection: Formatting
+_subsection: Formatting @<Interface--formatting>
 
 _property: interface.format( [ format ]) => string | Array<string> @SRC<abi/interface>
 Return the formatted **Interface**. If the format type is ``json`` a
@@ -49,87 +49,87 @@ single string is returned, otherwise an Array of the human-readable
 strings is returned.
 
 
-_subsection: Fragment Access
+_subsection: Fragment Access @<Interface--fragments>
 
-_property: interface.getFunction(fragment) => [[abi-functionfragment]]  @SRC<abi/interface>
-Returns the [[abi-functionfragment]] for //fragment// (see [[abi-fragmentid]]).
+_property: interface.getFunction(fragment) => [[FunctionFragment]]  @SRC<abi/interface>
+Returns the [[FunctionFragment]] for //fragment// (see [[Interface--specifying-fragments]]).
 
-_property: interface.getEvent(fragment) => [[abi-eventfragment]] @SRC<abi/interface>
-Returns the [[abi-eventfragment]] for //fragment// (see [[abi-fragmentid]]).
+_property: interface.getEvent(fragment) => [[EventFragment]] @SRC<abi/interface>
+Returns the [[EventFragment]] for //fragment// (see [[Interface--specifying-fragments]]).
 
 
-_subsection: Signature and Topic Hashes
+_subsection: Signature and Topic Hashes @<Interface--selectors>
 
-_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.getSighash(fragment) => string<[[DataHexString]]<4>> @SRC<abi/interface:method.Interface.getSighash>
+Return the sighash (or Function Selector) for //fragment// (see [[Interface--specifying-fragments]]).
 
-_property: interface.getEventTopic(fragment) => string<[[datahexstring]]<32>> @SRC<abi/interface:method.Interface.getEventTopic>
-Return the topic hash 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 [[Interface--specifying-fragments]]).
 
 
-_subsection: Encoding Data
+_subsection: Encoding Data @<Interface--encoding>
 
-_property: interface.encodeDeploy([ values ]) => string<[[datahexstring]]> @SRC<abi/interface>
+_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//.
+(see [[Interface--specifying-fragments]]) for the given //values//.
 
-Each //topic// is a 32 byte (64 nibble) [[datahexstring]].
+Each //topic// is a 32 byte (64 nibble) [[DataHexString]].
 
-_property: interface.encodeFunctionData(fragment [ , values ]) => string<[[datahexstring]]> @SRC<abi/interface>
+_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//.
+//fragment// (see [[Interface--specifying-fragments]]) for the given //values//.
 
-_property: interface.encodeFunctionResult(fragment [ , values ]) => string<[[datahexstring]]> @SRC<abi/interface>
+_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//.
+//fragment// (see [[Interface--specifying-fragments]]) for the given //values//.
 
 Most developers will not need this method, but may be useful for authors of a mock blockchain.
 
 
-_subsection: Decoding Data
+_subsection: Decoding Data @<Interface--decoding>
 
-_property: interface.decodeEventLog(fragment, data [ , topics ]) => [[abi-result]] @SRC<abi/interface>
+_property: interface.decodeEventLog(fragment, data [ , topics ]) => [[Result]] @SRC<abi/interface>
 Returns the decoded event values from an event log for
-//fragment// (see [[abi-fragmentid]]) for the given //data//
+//fragment// (see [[Interface--specifying-fragments]]) 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>
+_property: interface.decodeFunctionData(fragment, data) => [[Result]] @SRC<abi/interface>
 Returns the decoded values from transaction data for
-//fragment// (see [[abi-fragmentid]]) for the given //data//.
+//fragment// (see [[Interface--specifying-fragments]]) 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>
+_property: interface.decodeFunctionResult(fragment, data) => [[Result]] @SRC<abi/interface>
 Returns the decoded values from the result of a call for
-//fragment// (see [[abi-fragmentid]]) for the given //data//.
+//fragment// (see [[Interface--specifying-fragments]]) for the given //data//.
 
 
-_subsection: Parsing
+_subsection: Parsing @<Interface--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>
+_property: interface.parseLog(log) => [[LogDescription]] @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>
+_property: interface.parseTransaction(transaction) => [[TransactionDescription]] @SRC<abi/interface>
 Search for the function that matches the //transaction// data sighash
 and parse the transaction properties.
 
 
-_subsection: Types
+_subsection: Types @<Interface--types>
 
-_heading: Result @<abi-result> @INHERIT<Array&lt;any&gt;>
+_heading: Result @<Result> @INHERIT<Array\<any\>>
 
 A **Result** is an array, so each value can be accessed as a positional
 argument.
@@ -142,13 +142,13 @@ 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>
+_heading: LogDescription @<LogDescription>
 
-_property: logDescription.args => [[abi-result]]
+_property: logDescription.args => [[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.eventFragment => [[EventFragment]]
+The [[EventFragment]] which matches the topic in the Log.
 
 _property: logDescription.name => string
 The event name. (e.g. ``Transfer``)
@@ -160,14 +160,14 @@ _property: logDescription.topic => string
 The topic hash.
 
 
-_heading: TransactionDescription @<abi-transaction>
+_heading: TransactionDescription @<TransactionDescription>
 
-_property: transactionDescription.args => [[abi-result]]
+_property: transactionDescription.args => [[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.functionFragment => [[FunctionFragment]]
+The [[FunctionFragment]] which matches the sighash in the transaction data.
 
 _property: transactionDescription.name => string
 The name of the function. (e.g. ``transfer``)
@@ -178,19 +178,19 @@ 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]]
+_property: transactionDescription.value => [[BigNumber]]
 The value from the transaction.
 
 
-_subsection: Specifying Fragments @<abi-fragmentid>
+_subsection: Specifying Fragments @<Interface--specifying-fragments>
 
 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
+- 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,
+- 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
+- The **sighash** or **topichash** of the function. The sighash is often referred
   to the function selector in Solidity (e.g. ``0xa9059cbb``)
-- A [[abi-fragment]]    
+- A [[Fragment]]

docs.wrm/api/utils/address.wrm

@@ -9,7 +9,7 @@ _subsection: Address Formats  @<address-formats>
 
 _heading: Address  @<address>
 
-An **Address** is a [[datahexstring]] of 20 bytes (40 nibbles), with optional
+An **Address** is a [[DataHexString]] of 20 bytes (40 nibbles), with optional
 mixed case.
 
 If the case is mixed, it is a **Checksum Address**, which uses a specific pattern
@@ -39,28 +39,45 @@ accepts an address can receive an ICAP address, and it will be converted interna
 To convert an address into the ICAP format, see [getIcapAddress](utils-getIcapAddress).
 
 
-_subsection: Functions
+_subsection: Converting and Verifying @<utils--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
+If //address// is an invalid 40-nibble [[HexString]] or if it contains mixed case and
 the checksum is invalid, an InvalidArgument Error is throw.
 
 The value of //address// may be any supported address format.
 
-
-_property: ethers.utils.isAddress(address) => boolean  @<utils-isAddress> @SRC<address>
-Returns true if //address// is valid (in any supported format).
-
 _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: ethers.utils.getContractAddress(transaction) => string<[[address]]>  @<utils-getcontractaddress> @SRC<address>
+_property: ethers.utils.isAddress(address) => boolean  @<utils-isAddress> @SRC<address>
+Returns true if //address// is valid (in any supported format).
+
+
+_subsection: Derivation @<utils--address-derivation>
+
+_property: ethers.utils.computeAddress(publicOrPrivateKey) => string<[[address]]>  @<utils-computeAddress> @SRC<transactions>
+Returns the address for //publicOrPrivateKey//. A public key may be
+compressed or uncompressed, and a private key will be converted
+automatically to a public key for the derivation.
+
+_property: ethers.utils.recoverAddress(digest, signature) => string<[[address]]>  @<utils-recoverAddress> @SRC<transactions>
+Use [[link-wiki-ecrecover]] to determine the address that signed //digest// to
+which generated //signature//.
+
+
+_subsection: Contracts Addresses @<utils--contract-addresses>
+
+_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: 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-create.js

@@ -1,50 +0,0 @@
-// <hide>
-const { BigNumber } = require("./packages/ethers");
-const { constants } = require("./packages/ethers");
-
-function _inspect(result) {
-    if (BigNumber.isBigNumber(result)) {
-        return `{ BigNumber: ${ JSON.stringify(result.toString()) } }`;
-    }
-    return result;
-}
-// </hide>
-
-// From a decimal string...
-BigNumber.from("42")
-//!
-
-// From a hexstring...
-BigNumber.from("0x2a")
-//!
-
-// From a negative hexstring...
-BigNumber.from("-0x2a")
-//!
-
-// From an Array (or Uint8Array)...
-BigNumber.from([ 42 ])
-//!
-
-// From an existing BigNumber...
-let one1 = constants.One;
-let one2 = BigNumber.from(one1)
-
-one2
-//!
-
-// ...which returns the same instance
-one1 === one2
-//!
-
-// From a (safe) number...
-BigNumber.from(42)
-//!
-
-// From a ES2015 BigInt... (only on platforms with BigInt support)
-BigNumber.from(42n)
-//!
-
-// Numbers outside the safe range fail:
-BigNumber.from(Number.MAX_SAFE_INTEGER);
-//! error

docs.wrm/api/utils/bignumber-examples.js

@@ -1,16 +0,0 @@
-// <hide>
-const { BigNumber } = require("./packages/ethers");
-
-function _inspect(result) {
-    if (BigNumber.isBigNumber(result)) {
-        return `{ BigNumber: ${ JSON.stringify(result.toString()) } }`;
-    }
-    return result;
-}
-// </hide>
-
-let a = BigNumber.from(42);
-let b = BigNumber.from("91");
-
-  a.mul(b);
-  //!

docs.wrm/api/utils/bignumber-ieee754.js

@@ -1,2 +0,0 @@
-(Number.MAX_SAFE_INTEGER + 2 - 2) == (Number.MAX_SAFE_INTEGER)
-//!

docs.wrm/api/utils/bignumber-import.source

@@ -1,18 +0,0 @@
-/////
-// CommonJS:
-
-// From the Umbrella ethers package...
-const { BigNumber } = require("ethers");
-
-// From the bignumber pacakge...
-const { BigNumber } = require("@ethersproject/bignumber");
-
-
-/////
-// ES6 and TypeScript:
-
-// From the Umbrella ethers package...
-import { BigNumber } from "ethers";
-
-// From the bignumber pacakge...
-import { BigNumber } from "@ethersproject/bignumber";

docs.wrm/api/utils/bignumber.wrm

@@ -1,7 +1,7 @@
-_section: BigNumber @<bignumber>
+_section: BigNumber @<BigNumber>
 
 Many operations in Ethereum operation on numbers which are
-[outside the range of safe values](notes-safenumbers) to use
+[outside the range of safe values](BigNumber--notes-safenumbers) to use
 in JavaScript.
 
 A **BigNumber** is an object which safely allows mathematic operations
@@ -11,27 +11,23 @@ Most operations which need to return a value will return a **BigNumber**
 and parameters which accept values will generally accept them.
 
 
-_heading: Importing
+_subsection: Types @<BigNumber--types>
 
-_code: bignumber-import.source
-
-_subsection: Types
-
-_heading: BigNumberish @<bignumberish>
+_heading: BigNumberish @<BigNumberish>
 
 Many functions and methods in this library take in values which
 can be non-ambiguously and safely converted to a BigNumber. These
 values can be sepcified as:
 
 _definition: **//string//**
-A [hexstring](hexstring) or a decimal string, either of which may
+A [[HexString]] or a decimal string, either of which may
 be negative.
 
 _definition: **//BytesLike//**
-A [BytesLike](byteslike) Object, such as an Array or Uint8Array.
+A [[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](link-js-maxsafe) for JavaScript numbers.
@@ -41,19 +37,58 @@ A JavaScript [BigInt](link-js-bigint)
 object, on environments that support BigInt.
 
 
-_subsection: Creating Instances
+_subsection: Creating Instances @<BigNumber--creating>
 
 The constructor of BigNumber cannot be called directly. Instead, Use the static ``BigNumber.from``.
 
-_property: ethers.BigNumber.from(aBigNumberish) => [[bignumber]]
+_property: ethers.BigNumber.from(aBigNumberish) => [[BigNumber]]
 Returns an instance of a **BigNumber** for //aBigNumberish//.
 
 _heading: Examples:  @<>
 
-_code: bignumber-create.js
+_code: @lang<javascript>
+
+// From a decimal string...
+BigNumber.from("42")
+//!
+
+// From a HexString...
+BigNumber.from("0x2a")
+//!
+
+// From a negative HexString...
+BigNumber.from("-0x2a")
+//!
+
+// From an Array (or Uint8Array)...
+BigNumber.from([ 42 ])
+//!
+
+// From an existing BigNumber...
+let one1 = constants.One;
+let one2 = BigNumber.from(one1)
+
+one2
+//!
+
+// ...which returns the same instance
+one1 === one2
+//!
+
+// From a (safe) number...
+BigNumber.from(42)
+//!
+
+// From a ES2015 BigInt... (only on platforms with BigInt support)
+BigNumber.from(42n)
+//!
+
+// Numbers outside the safe range fail:
+BigNumber.from(Number.MAX_SAFE_INTEGER);
+//! error
 
 
-_subsection: Methods
+_subsection: Methods @<BigNumber--methods>
 
 The BigNumber class is immutable, so no operations can change the value
 it represents.
@@ -61,29 +96,29 @@ it represents.
 
 _heading: Math Operations
 
-_property: bignumber.add(otherValue) => [[bignumber]]  @SRC<bignumber>
-Returns a BigNumber with the value of //bignumber// **+** //otherValue//.
+_property: BigNumber.add(otherValue) => [[BigNumber]]  @SRC<bignumber>
+Returns a BigNumber with the value of //BigNumber// **+** //otherValue//.
 
-_property: bignumber.sub(otherValue) => [[bignumber]]  @SRC<bignumber>
-Returns a BigNumber with the value of //bignumber// **&ndash;** //otherValue//.
+_property: BigNumber.sub(otherValue) => [[BigNumber]]  @SRC<bignumber>
+Returns a BigNumber with the value of //BigNumber// **-** //otherValue//.
 
-_property: bignumber.mul(otherValue) => [[bignumber]]  @SRC<bignumber>
-Returns a BigNumber with the value of //bignumber// **&times;** //otherValue//.
+_property: BigNumber.mul(otherValue) => [[BigNumber]]  @SRC<bignumber>
+Returns a BigNumber with the value of //BigNumber// **&times;** //otherValue//.
 
-_property: bignumber.div(divisor) => [[bignumber]]  @SRC<bignumber>
-Returns a BigNumber with the value of //bignumber// **&#247;** //divisor//.
+_property: BigNumber.div(divisor) => [[BigNumber]]  @SRC<bignumber>
+Returns a BigNumber with the value of //BigNumber// **&div;** //divisor//.
 
-_property: bignumber.mod(divisor) => [[bignumber]]  @SRC<bignumber>
-Returns a BigNumber with the value of the **remainder** of //bignumber// &#247; //divisor//.
+_property: BigNumber.mod(divisor) => [[BigNumber]]  @SRC<bignumber>
+Returns a BigNumber with the value of the **remainder** of //BigNumber// &div; //divisor//.
 
-_property: bignumber.pow(exponent) => [[bignumber]]  @SRC<bignumber>
-Returns a BigNumber with the value of //bignumber// to the power of //exponent//.
+_property: BigNumber.pow(exponent) => [[BigNumber]]  @SRC<bignumber>
+Returns a BigNumber with the value of //BigNumber// to the power of //exponent//.
 
-_property: bignumber.abs() => [[bignumber]]  @SRC<bignumber>
-Returns a BigNumber with the absolute value of //bignumber//.
+_property: BigNumber.abs() => [[BigNumber]]  @SRC<bignumber>
+Returns a BigNumber with the absolute value of //BigNumber//.
 
-_property: bignumber.maskn(bitcount) => [[bignumber]]  @SRC<bignumber>
-Returns a BigNumber with the value of //bignumber// with bits beyond
+_property: BigNumber.mask(bitcount) => [[BigNumber]]  @SRC<bignumber>
+Returns a BigNumber with the value of //BigNumber// with bits beyond
 the //bitcount// least significant bits set to zero.
 
 
@@ -94,48 +129,48 @@ is an elegant method used to encode and decode fixed-width signed values
 while efficiently preserving mathematic operations.
 Most users will not need to interact with these.
 
-_property: bignumber.fromTwos(bitwidth) => [[bignumber]]  @SRC<bignumber>
-Returns a BigNumber with the value of //bignumber// converted from twos-compliment with //bitwidth//.
+_property: BigNumber.fromTwos(bitwidth) => [[BigNumber]]  @SRC<bignumber>
+Returns a BigNumber with the value of //BigNumber// converted from twos-compliment with //bitwidth//.
 
-_property: bignumber.toTwos(bitwidth) => [[bignumber]]  @SRC<bignumber>
-Returns a BigNumber with the value of //bignumber// converted to twos-compliment with //bitwidth//.
+_property: BigNumber.toTwos(bitwidth) => [[BigNumber]]  @SRC<bignumber>
+Returns a BigNumber with the value of //BigNumber// converted to twos-compliment with //bitwidth//.
 
 
 _heading: Comparison and Equivalence
 
-_property: bignumber.eq(otherValue) => boolean  @SRC<bignumber>
-Returns true if and only if the value of //bignumber// is equal to //otherValue//.
+_property: BigNumber.eq(otherValue) => boolean  @SRC<bignumber>
+Returns true if and only if the value of //BigNumber// is equal to //otherValue//.
 
-_property: bignumber.lt(otherValue) => boolean  @SRC<bignumber>
-Returns true if and only if the value of //bignumber// **<** //otherValue//.
+_property: BigNumber.lt(otherValue) => boolean  @SRC<bignumber>
+Returns true if and only if the value of //BigNumber// **<** //otherValue//.
 
-_property: bignumber.lte(otherValue) => boolean  @SRC<bignumber>
-Returns true if and only if the value of //bignumber// **&le;** //otherValue//.
+_property: BigNumber.lte(otherValue) => boolean  @SRC<bignumber>
+Returns true if and only if the value of //BigNumber// **&le;** //otherValue//.
 
-_property: bignumber.gt(otherValue) => boolean  @SRC<bignumber>
-Returns true if and only if the value of //bignumber// **>** //otherValue//.
+_property: BigNumber.gt(otherValue) => boolean  @SRC<bignumber>
+Returns true if and only if the value of //BigNumber// **>** //otherValue//.
 
-_property: bignumber.gte(otherValue) => boolean  @SRC<bignumber>
-Returns true if and only if the value of //bignumber// **&ge;** //otherValue//.
+_property: BigNumber.gte(otherValue) => boolean  @SRC<bignumber>
+Returns true if and only if the value of //BigNumber// **&ge;** //otherValue//.
 
-_property: bignumber.isZero() => boolean  @SRC<bignumber>
-Returns true if and only if the value of //bignumber// is zero.
+_property: BigNumber.isZero() => boolean  @SRC<bignumber>
+Returns true if and only if the value of //BigNumber// is zero.
 
 
 _heading: Conversion
 
-_property: bignumber.toNumber() => number  @SRC<bignumber>
-Returns the value of //bignumber// as a JavaScript value.
+_property: BigNumber.toNumber() => number  @SRC<bignumber>
+Returns the value of //BigNumber// as a JavaScript value.
 
 This will **throw an error**
 if the value is greater than or equal to //Number.MAX_SAFE_INTEGER// or less than or
 equal to //Number.MIN_SAFE_INTEGER//.
 
-_property: bignumber.toString() => string  @SRC<bignumber:BigNumber.toString>
-Returns the value of //bignumber// as a base-10 string.
+_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 [[datahexstring]].
+_property: BigNumber.toHexString() => string<[[DataHexString]]>  @SRC<bignumber:BigNumber.toHexString>
+Returns the value of //BigNumber// as a base-16, ``0x``-prefixed [[DataHexString]].
 
 
 _heading: Inspection
@@ -146,15 +181,21 @@ Returns true if and only if the //object// is a BigNumber object.
 
 _heading: Examples
 
-_code: bignumber-examples.js
+_code: @lang<javascript>
+
+let a = BigNumber.from(42);
+let b = BigNumber.from("91");
+
+a.mul(b);
+//!
 
 
-_subsection: Notes
+_subsection: Notes @<BigNumber--notes>
 
 This section is a for a couple of questions that come up frequently.
 
 
-_heading: Why can't I just use numbers? @<notes-safenumbers>
+_heading: Why can't I just use numbers? @<BigNumber--notes-safenumbers>
 
 The first problem many encounter when dealing with Ethereum is
 the concept of numbers. Most common currencies are broken down
@@ -171,13 +212,18 @@ experience rounding errors.
 
 To demonstrate how this may be an issue in your code, consider:
 
-_code: bignumber-ieee754.js
+_code: @lang<javascript>
+
+(Number.MAX_SAFE_INTEGER + 2 - 2) == (Number.MAX_SAFE_INTEGER)
+//!
+
+_null:
 
 To remedy this, all numbers (which can be large) are stored
-and manipulated as [Big Numbers](bignumber).
+and manipulated as [Big Numbers](BigNumber).
 
-The functions [parseEther( etherString )](http://linkto) and
-[formatEther( wei )](http://linkto) can be used to convert
+The functions [parseEther( etherString )](utils-parseEther) and
+[formatEther( wei )](utils-formatEther) can be used to convert
 between string representations, which are displayed to or entered
 by the user and Big Number representations which can have
 mathematical operations handled safely.
@@ -189,7 +235,7 @@ 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
+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.
 
@@ -197,7 +243,7 @@ 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
+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.
@@ -222,7 +268,7 @@ over other libraries which include separate Big Number libraries for
 various purposes.
 
 
-_heading: Why not allow us to set a global Big Number library?
+_heading: 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
@@ -236,6 +282,6 @@ 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
+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-conversion.js

@@ -1,37 +0,0 @@
-// <hide>
-
-const { ethers } = require("./packages/ethers");
-const { arrayify, hexlify, hexValue } = ethers.utils;
-
-function _inspect(result) {
-    if (result && typeof(result.length) === "number" && typeof(result) !== "string") {
-        return "[ " + Array.prototype.map.call(result, (i) => _inspect(i)).join(", ") + " ]";
-    }
-    return result;
-}
-
-// </hide>
-
-// Convert a hexstring to a Uint8Array
-arrayify("0x1234")
-//!
-
-// Convert an Array to a hexstring
-hexlify([1, 2, 3, 4])
-//!
-
-// Convert an Object to a hexstring
-hexlify({ length: 2, "0": 1, "1": 2 })
-//!
-
-// Convert an Array to a hexstring
-hexlify([ 1 ])
-//!
-
-// Convert a number to a stripped hex value
-hexValue(1)
-//!
-
-// Convert an Array to a stripped hex value
-hexValue([ 1, 2 ])
-//!

docs.wrm/api/utils/bytes.wrm

@@ -4,7 +4,7 @@ Tra la la...
 
 _subsection: Types
 
-_heading: Bytes @<bytes>
+_heading: Bytes @<Bytes>
 
 A **Bytes** is any object which is an
 [Array](link-js-array) or [TypedArray](link-js-typedarray) with
@@ -12,39 +12,38 @@ each value in the valid byte range (i.e. between 0 and 255 inclusive),
 or is an Object with a ``length`` property where each indexed property
 is in the valid byte range.
 
-_heading: BytesLike @<byteslike>
+_heading: BytesLike @<BytesLike>
 
-A **BytesLike** can be either a [[bytes]] or a [[datahexstring]].
+A **BytesLike** can be either a [[Bytes]] or a [[DataHexString]].
 
-_heading: DataHexstring @<datahexstring>
+_heading: DataHexString @<DataHexString>
 
-A **DataHexstring** is identical to a [[hexstring]] except that it has
+A **DataHexstring** is identical to a [[HexString]] except that it has
 an even number of nibbles, and therefore is a valid representation of
 binary data as a string.
 
-_heading: Hexstring @<hexstring>
+_heading: HexString @<HexString>
 
 A **Hexstring** is a string which has a ``0x`` prefix followed by any
 number of nibbles (i.e. case-insensitive hexidecumal characters, ``0-9`` and ``a-f``).
 
-_heading: Signature @<signature>
+_heading: Signature @<Signature>
 
 - **r** and **s** --- The x co-ordinate of **r** and the **s** value of the signature
 - **v** --- The parity of the y co-ordinate of **r**
 - **_vs** --- The [compact representation](link-eip-2098) of the **s** and **v**
 - **recoveryParam** --- The normalized (i.e. 0 or 1) value of **v**
 
-_heading: Flat-Format Signature @<signature-flat>
+_heading: Raw Signature @<signature-raw> @inherit<string\<[[DataHexString]]\<65\>\>>
 
-A **Flat-Format Signature** is a common Signature format where
-the r, s and v are concanenated into a 65 byte (130 nibble)
-[[datahexstring]].
+A **Raw Signature** is a common Signature format where the r, s and v are
+concanenated into a 65 byte (130 nibble) [[DataHexString]].
 
 
-_heading: SignatureLike @<signaturelike>
+_heading: SignatureLike @<SignatureLike>
 
-A **SignatureLike** is similar to a [[signature]], except redundant properties
-may be omitted or it may be a [[signature-flat]].
+A **SignatureLike** is similar to a [[Signature]], except redundant properties
+may be omitted or it may be a [[signature-raw]].
 
 For example, if **_vs** is specified, **s** and **v** may be omitted. Likewise,
 if **recoveryParam** is provided, **v** may be omitted (as in these cases the
@@ -53,44 +52,66 @@ missing values can be computed).
 
 _subsection: Inspection
 
-_property: ethers.utils.isBytes(object) => boolean  @<utils-isbytes> @SRC<bytes>
-Returns true if and only if //object// is a valid [[bytes]].
+_property: ethers.utils.isBytes(object) => boolean  @<utils-isBytes> @SRC<bytes>
+Returns true if and only if //object// is a valid [[Bytes]].
 
-_property: ethers.utils.isBytesLike(object) => boolean  @<utils-isbyteslike> @SRC<bytes>
-Returns true if and only if //object// is a [[bytes]] or [[datahexstring]].
+_property: ethers.utils.isBytesLike(object) => boolean  @<utils-isBytesLike> @SRC<bytes>
+Returns true if and only if //object// is a [[Bytes]] or [[DataHexString]].
 
-_property: ethers.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
+If //length// is specified and //object// is not a valid [[DataHexString]] of
 //length// bytes, an InvalidArgument error is thrown.
 
 
 _subsection: Converting between Arrays and Hexstrings
 
-_property: ethers.utils.arrayify(datahexstringOrArrayish [ , options ]) => Uint8Array  @<utils-arrayify> @SRC<bytes>
-Converts //datahexstringOrArrayish// to a Uint8Array.
+_property: ethers.utils.arrayify(DataHexStringOrArrayish [ , options ]) => Uint8Array  @<utils-arrayify> @SRC<bytes>
+Converts //DataHexStringOrArrayish// to a Uint8Array.
 
-_property: ethers.utils.hexlify(hexstringOrArrayish) => string<[[datahexstring]]>  @<utils-hexlify> @SRC<bytes>
-Converts //hexstringOrArrayish// to a [[datahexstring]].
+_property: ethers.utils.hexlify(hexstringOrArrayish) => string<[[DataHexString]]>  @<utils-hexlify> @SRC<bytes>
+Converts //hexstringOrArrayish// to a [[DataHexString]].
 
-_property: ethers.utils.hexValue(aBigNumberish) => string<[[hexstring]]>  @<utils-hexvalue> @SRC<bytes>
-Converts //aBigNumberish// to a [[hexstring]], with no __unnecessary__ leading
+_property: ethers.utils.hexValue(aBigNumberish) => string<[[HexString]]>  @<utils-hexValue> @SRC<bytes>
+Converts //aBigNumberish// to a [[HexString]], with no __unnecessary__ leading
 zeros.
 
-_heading: Examples
+_code: Examples @lang<javascript>
 
-_code: bytes-conversion.js
+// Convert a hexstring to a Uint8Array
+arrayify("0x1234")
+//!
+
+// Convert an Array to a hexstring
+hexlify([1, 2, 3, 4])
+//!
+
+// Convert an Object to a hexstring
+hexlify({ length: 2, "0": 1, "1": 2 })
+//!
+
+// Convert an Array to a hexstring
+hexlify([ 1 ])
+//!
+
+// Convert a number to a stripped hex value
+hexValue(1)
+//!
+
+// Convert an Array to a stripped hex value
+hexValue([ 1, 2 ])
+//!
 
 
 _subsection: Array Manipulation
 
 _property: ethers.utils.concat(arrayOfBytesLike) => Uint8Array  @<utils-concat> @SRC<bytes>
-Concatenates all the [[byteslike]] in //arrayOfBytesLike// into a single Uint8Array.
+Concatenates all the [[BytesLike]] in //arrayOfBytesLike// into a single Uint8Array.
 
-_property: ethers.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: ethers.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.
 
@@ -100,23 +121,23 @@ error will be thrown.
 
 _subsection: Hexstring Manipulation
 
-_property: ethers.utils.hexConcat(arrayOfBytesLike) => string<[[datahexstring]]>  @<utils-hexconcat> @SRC<bytes>
-Concatenates all the [[byteslike]] in //arrayOfBytesLike// into a single [[datahexstring]]
+_property: ethers.utils.hexConcat(arrayOfBytesLike) => string<[[DataHexString]]>  @<utils-hexConcat> @SRC<bytes>
+Concatenates all the [[BytesLike]] in //arrayOfBytesLike// into a single [[DataHexString]]
 
-_property: ethers.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: ethers.utils.hexDataSlice(aBytesLike, offset [ , endOffset ] ) => string<[[datahexstring]]>  @<utils-hexdataslice> @SRC<bytes>
-Returns a [[datahexstring]] representation of a slice of //aBytesLike//, from
+_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: ethers.utils.hexStripZeros(aBytesLike) => string<[[hexstring]]>  @<utils-hexstripzeros> @SRC<bytes>
-Returns a [[hexstring]] representation of //aBytesLike// with all
+_property: ethers.utils.hexStripZeros(aBytesLike) => string<[[HexString]]>  @<utils-hexStripZeros> @SRC<bytes>
+Returns a [[HexString]] representation of //aBytesLike// with all
 leading zeros removed.
 
-_property: ethers.utils.hexZeroPad(aBytesLike, length) => string<[[datahexstring]]>  @<utils-hexzeropad> @SRC<bytes>
-Returns a [[datahexstring]] representation of //aBytesLike// padded to //length// 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
 error will be thrown.
@@ -124,18 +145,33 @@ error will be thrown.
 
 _subsection: Signature Conversion
 
-_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)
+_property: ethers.utils.joinSignature(aSignatureLike) => string<[RawSignature](signature-raw)>  @<utils-joinSignature> @SRC<bytes>
+Return the raw-format of //aSignaturelike//, which is 65 bytes (130 nibbles)
 long, concatenating the **r**, **s** and (normalized) **v** of a Signature.
 
-_property: ethers.utils.splitSignature(aSignatureLikeOrBytesLike) => [[signature]]  @<utils-splitsignature> @SRC<bytes>
-Return the full expanded-format of //aSignaturelike// or a flat-format [[datahexstring]].
+_property: ethers.utils.splitSignature(aSignatureLikeOrBytesLike) => [[Signature]]  @<utils-splitSignature> @SRC<bytes>
+Return the full expanded-format of //aSignaturelike// or a raw-format [[DataHexString]].
 Any missing properties will be computed.
 
 _subsection: Random Bytes
 
-_property: ethers.utils.randomBytes(length) => Uint8Array  @<utils-randombytes> @SRC<random/index>
+_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>
+_property: ethers.utils.shuffled(array) => Array<any>  @<utils-shuffled> @SRC<random>
 Return a copy of //array// shuffled using [[link-wiki-shuffle]].
+
+_code: Examples @lang<javascript>
+
+utils.randomBytes(8)
+//!
+
+const data = [ 1, 2, 3, 4, 5, 6, 7 ];
+
+// Returns a new Array
+utils.shuffled(data);
+//!
+
+// The Original is unscathed...
+data
+//!

docs.wrm/api/utils/constants-import.js

@@ -1,3 +0,0 @@
-
-//const { constants } = require("ethers");
-// const { constants } = require("@ethersproject/constants");

docs.wrm/api/utils/constants.wrm

@@ -2,45 +2,41 @@ _section: Constants @<constants>
 
 The **ethers.contants** Object contains commonly used values.
 
-_heading: Importing
-
-_code: constants-import.js
-
 
 _subsection: Bytes
 
-_property: ethers.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: ethers.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: ethers.constants.EtherSymbol => string  @<constants-ethersymbol> @SRC<constants>
+_property: ethers.constants.EtherSymbol => string  @<constants-EtherSymbol> @SRC<constants>
 The Ether symbol, **&Xi;**.
 
 
 _subsection: BigNumber
 
-_property: ethers.constants.NegativeOne => [[bignumber]]  @<constants-negativeone> @SRC<constants>
+_property: ethers.constants.NegativeOne => [[BigNumber]]  @<constants-NegativeOne> @SRC<constants>
 The BigNumber value representing ``"-1"``.
 
-_property: ethers.constants.Zero => [[bignumber]]  @<constants-zero> @SRC<constants>
+_property: ethers.constants.Zero => [[BigNumber]]  @<constants-Zero> @SRC<constants>
 The BigNumber value representing ``"0"``.
 
-_property: ethers.constants.One => [[bignumber]]  @<constants-one> @SRC<constants>
+_property: ethers.constants.One => [[BigNumber]]  @<constants-One> @SRC<constants>
 The BigNumber value representing ``"1"``.
 
-_property: ethers.constants.Two => [[bignumber]]  @<constants-two> @SRC<constants>
+_property: ethers.constants.Two => [[BigNumber]]  @<constants-Two> @SRC<constants>
 The BigNumber value representing ``"2"``.
 
-_property: ethers.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: ethers.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

@@ -10,10 +10,10 @@ gas prices in gwei for the User Interface, but when sending
 a transaction, both must be specified in wei.
 
 The [parseUnits](unit-conversion) will parse a string representing
-ether, such as ``1.1`` into a [BigNumber](bignumber) in wei, and is
+ether, such as ``1.1`` into a [BigNumber](BigNumber) in wei, and is
 useful when a user types in a value, such as sending 1.1 ether.
 
-The [formatUnits](unit-conversion) will format a [BigNumberish](bignumberish)
+The [formatUnits](unit-conversion) will format a [BigNumberish](BigNumberish)
 into a string, which is useful when displaying a balance.
 
 
@@ -21,23 +21,29 @@ _subsection: Units
 
 _heading: Decimal Count
 
-The //unit// specified may be an integer, which indicates how
-many decimal place the unit has. For example, 1 ether has 18 decimal
-places for wei, and if this library were used with Bitcoin, 1 BTC
-has 8 decimal places for satoshis.
+A **Unit** can be specified as an number, which indicates the
+number of decimal places that should be used.
+
+**Examples:**
+
+- 1 ether in wei, has **18** decimal places (i.e. 1 ether represents 10^^18^^ wei)
+- 1 bitcoin in Satoshi, has **8** decimal places (i.e. 1 bitcoin represents 10^^8^^ satoshi)
 
 _heading: Named Units
 
-In addition to specifying //unit// as a number of decimals, there
-are several common units, which can be passed in as a string:
+There are also several common **Named Units**, in which case their name (as
+a string) may be used.
 
-- **wei** --- 0
-- **kwei** --- 3
-- **mwei** --- 6
-- **gwei** --- 9
-- **szabo** --- 12
-- **finney** --- 15
-- **ether** --- 18
+_table: @STYLE<compact>
+
+|  **Name**    |  **Decimals**  |
+|  //wei//     |      0         |
+|  //kwei//    |      3         |
+|  //mwei//    |      6         |
+|  //gwei//    |      9         |
+|  //szabo//   |     12         |
+|  //finney//  |     15         |
+|  //ether//   |     18         |
 
 
 _subsection: Functions
@@ -50,17 +56,17 @@ Returns a string with value grouped by 3 digits, separated by ``,``.
 
 _heading: Conversion @<unit-conversion>
 
-_property: ethers.utils.formatUnits(value [ , unit = "ether" ] ) => string  @<utils-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: ethers.utils.formatEther(value) => string  @<utils-formatether> @SRC<units>
+_property: ethers.utils.formatEther(value) => string  @<utils-formatEther> @SRC<units>
 The equivalent to calling ``formatUnits(value, "ether")``.
 
-_property: ethers.utils.parseUnits(value [ , unit = "ether" ] ) => [BigNumber](bignumber)  @<utils-parseunits> @SRC<units>
-Returns a [BigNumber](bignumber) representation of //value//, parsed with
+_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: ethers.utils.parseEther(value) => [BigNumber](bignumber)  @<utils-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,6 +1,6 @@
 _section: Encoding Utilities @<encoding>
 
-_subsection: Base58 @<bse58> @SRC<basex:Base58>
+_subsection: Base58 @<Bse58> @SRC<basex:Base58>
 
 _property: ethers.utils.base58.decode(textData) => Uin8Array
 Return a typed Uint8Array representation of //textData// decoded using
@@ -10,7 +10,7 @@ _property: ethers.utils.base58.encode(aBytesLike) => string
 Return //aBytesLike// encoded as a string using the base-58 encoding.
 
 
-_subsection: Base64 @<base64>
+_subsection: Base64 @<Base64>
 
 _property: ethers.utils.base64.decode(textData) => Uin8Array  @SRC<base64>
 Return a typed Uint8Array representation of //textData// decoded using
@@ -20,22 +20,22 @@ _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>
+_subsection: Recursive-Length Prefix @<rlp--methods>
 
 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>
+_property: ethers.utils.RLP.encode(dataObject) => string<[[DataHexString]]>  @<utils-rlpEncode> @SRC<rlp>
 Encode a structured Data Object into its RLP-encoded representation.
 
-Each Data component may be an valid [[byteslike]].
+Each Data component may be an valid [[BytesLike]].
 
-_property: ethers.utils.RLP.decode(aBytesLike) => [DataObject](rlp-dataobject)  @<rlp-decode> @SRC<rlp>
+_property: ethers.utils.RLP.decode(aBytesLike) => [DataObject](rlp--dataobject)  @<utils.rlpDecode> @SRC<rlp>
 Decode an RLP-encoded //aBytesLike// into its structured Data Object.
 
-All Data components will be returned as a [[datahexstring]].
+All Data components will be returned as a [[DataHexString]].
 
-_heading: Data Object @<rlp-dataobject>
+_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:

docs.wrm/api/utils/fixednumber.wrm

@@ -1,4 +1,4 @@
-_section: FixedNumber @<fixednumber>
+_section: FixedNumber @<FixedNumber>
 
 A **FixedNumber** is a fixed-width (in bits) number with an internal
 base-10 divisor, which allows it to represent a decimal fractional
@@ -9,53 +9,53 @@ _subsection: Creating Instances
 The FixedNumber constructor cannot be called directly. There are several
 static methods for creating a FixedNumber.
 
-_property: FixedNumber.from(value [ , format = "fixed" ] ) => [[fixednumber]]  @SRC<bignumber:FixedNumber.from>
+_property: FixedNumber.from(value [ , format = "fixed" ] ) => [[FixedNumber]]  @SRC<bignumber:FixedNumber.from>
 Returns an instance of a **FixedNumber** for //value// as a //format//.
 
-_property: FixedNumber.fromBytes(aBytesLike [ , format = "fixed" ] ) => [[fixednumber]]  @SRC<bignumber>
+_property: FixedNumber.fromBytes(aBytesLike [ , format = "fixed" ] ) => [[FixedNumber]]  @SRC<bignumber>
 Returns an instance of a **FixedNumber** for //value// as a //format//.
 
-_property: FixedNumber.fromString(value [ , format = "fixed" ] ) => [[fixednumber]]  @SRC<bignumber:FixedNumber.fromString>
+_property: FixedNumber.fromString(value [ , format = "fixed" ] ) => [[FixedNumber]]  @SRC<bignumber:FixedNumber.fromString>
 Returns an instance of a **FixedNumber** for //value// as a //format//. The //value// must
 not contain more decimals than the //format// permits.
 
-_property: FixedNumber.fromValue(value [ , decimals = 0 [ , format = "fixed" ] ] ) => [[fixednumber]]  @SRC<bignumber:FixedNumber.fromValue>
+_property: FixedNumber.fromValue(value [ , decimals = 0 [ , format = "fixed" ] ] ) => [[FixedNumber]]  @SRC<bignumber:FixedNumber.fromValue>
 Returns an instance of a **FixedNumber** for //value// with //decimals// as a //format//.
 
 
 _subsection: Properties
 
 _property: fixednumber.format
-The [FixedFormat](fixedformat) of //fixednumber//.
+The [FixedFormat](FixedFormat) of //fixednumber//.
 
 
 _subsection: Methods
 
 _heading: Math Operations
 
-_property: fixednumber.addUnsafe(otherValue) => [[fixednumber]]  @SRC<bignumber/fixednumber>
+_property: fixednumber.addUnsafe(otherValue) => [[FixedNumber]]  @SRC<bignumber/fixednumber>
 Returns a new FixedNumber with the value of //fixedvalue// **+** //otherValue//.
 
-_property: fixednumber.subUnsafe(otherValue) => [[fixednumber]]  @SRC<bignumber/fixednumber>
-Returns a new FixedNumber with the value of //fixedvalue// **&ndash;** //otherValue//.
+_property: fixednumber.subUnsafe(otherValue) => [[FixedNumber]]  @SRC<bignumber/fixednumber>
+Returns a new FixedNumber with the value of //fixedvalue// **-** //otherValue//.
 
-_property: fixednumber.mulUnsafe(otherValue) => [[fixednumber]]  @SRC<bignumber/fixednumber>
+_property: fixednumber.mulUnsafe(otherValue) => [[FixedNumber]]  @SRC<bignumber/fixednumber>
 Returns a new FixedNumber with the value of //fixedvalue// **&times;** //otherValue//.
 
-_property: fixednumber.divUnsafe(otherValue) => [[fixednumber]]  @SRC<bignumber/fixednumber>
-Returns a new FixedNumber with the value of //fixedvalue// **&#247;** //otherValue//.
+_property: fixednumber.divUnsafe(otherValue) => [[FixedNumber]]  @SRC<bignumber/fixednumber>
+Returns a new FixedNumber with the value of //fixedvalue// **&div;** //otherValue//.
 
-_property: fixednumber.round([ decimals = 0 ]) => [[fixednumber]]  @SRC<bignumber/fixednumber>
+_property: fixednumber.round([ decimals = 0 ]) => [[FixedNumber]]  @SRC<bignumber/fixednumber>
 Returns a new FixedNumber with the value of //fixedvalue// rounded to //decimals//.
 
 
 _heading: Conversion
 
-_property: fixednumber.toFormat(format) => [[fixednumber]]  @SRC<bignumber/fixednumber>
+_property: fixednumber.toFormat(format) => [[FixedNumber]]  @SRC<bignumber/fixednumber>
 Returns a new FixedNumber with the value of //fixedvalue// with //format//.
 
 _property: fixednumber.toHexString() => string  @SRC<bignumber/fixednumber>
-Returns a [Hexstring](hexstring) representation of //fixednumber//.
+Returns a [[HexString]] representation of //fixednumber//.
 
 _property: fixednumber.toString() => string  @SRC<bignumber/fixednumber>
 Returns a string representation of //fixednumber//.
@@ -71,14 +71,14 @@ _property: FixedNumber.isFixedNumber(value) => boolean  @SRC<bignumber/fixednumb
 Returns true if and only if //value// is a **FixedNumber**.
 
 
-_subsection: FixedFormat @<fixedformat>
+_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.
+class directly is uneccessary, as passing in a [[FixedFormat--strings]]
+directly into the [[FixedNumber]] will automatically create this.
 
-_heading: Format Strings  @<fixedformatstring>
+_heading: Format Strings  @<FixedFormat--strings>
 
 A format string is composed of three components, including signed-ness,
 bit-width and number of decimals.
@@ -93,18 +93,18 @@ 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`
+- **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>
+_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]]
+Returns a new instance of a **FixedFormat** defined by //value//. Any valid [[FixedFormat--strings]]
 may be passed in as well as any object which has any of ``signed``, ``width`` and ``decimals``
-defined, including a [[fixedformat]] object.
+defined, including a [[FixedFormat]] object.
 
 _heading: Properties
 

docs.wrm/api/utils/hashing.wrm

@@ -1,31 +1,115 @@
-_section: Hashing Algorithms
+_section: Hashing Algorithms @<hashing-algorithms>
 
 Explain what hash functions are?
 
 
-_subsection: Cryptographic Hashing
+_subsection: Cryptographic Hash Functions @<cryptographic-hash-functions>
 
 The [Cryptographic Hash Functions](link-wiki-cryptographichash)
 are a specific family of hash functions.
 
-_property: ethers.utils.keccak256(aBytesLike) => string<[[datahexstring]]<32>>  @<utils-keccak256> @SRC<keccak256>
+_property: ethers.utils.id(text) => string<[[DataHexString]]<32>>  @<utils-id> @SRC<hash>
+The Ethereum Identity function computs the [KECCAK256](link-wiki-sha3) hash of the //text// bytes.
+
+_property:  ethers.utils.keccak256(aBytesLike) => string<[[DataHexString]]<32>>  @<utils-keccak256> @SRC<keccak256>
 Returns the [KECCAK256](link-wiki-sha3) digest //aBytesLike//.
 
-_property: ethers.utils.ripemd160(aBytesLike) => string<[[datahexstring]]<20>>  @<utils-ripemd160> @SRC<sha2>
+_property: ethers.utils.ripemd160(aBytesLike) => string<[[DataHexString]]<20>>  @<utils-ripemd160> @SRC<sha2>
 Returns the [RIPEMD-160](link-wiki-ripemd) digest of //aBytesLike//.
 
-_property: ethers.utils.sha256(aBytesLike) => string<[[datahexstring]]<32>>  @<utils-sha256> @SRC<sha2:function.sha256>
+_property: ethers.utils.sha256(aBytesLike) => string<[[DataHexString]]<32>>  @<utils-sha256> @SRC<sha2:function.sha256>
 Returns the [SHA2-256](link-wiki-sha2) digest of //aBytesLike//.
 
-_property: ethers.utils.sha512(aBytesLike) => string<[[datahexstring]]<64>>  @<utils-sha512> @SRC<sha2:function.sha512>
+_property: ethers.utils.sha512(aBytesLike) => string<[[DataHexString]]<64>>  @<utils-sha512> @SRC<sha2:function.sha512>
 Returns the [SHA2-512](link-wiki-sha2) digest of //aBytesLike//.
 
-_property: ethers.utils.computeHmac(algorithm, key, data) => string<[[datahexstring]]>  @<utils-computehmac> @SRC<sha2>
+_code: KECCAK256 @lang<javascript>
+
+utils.keccak256([ 0x12, 0x34 ])
+//!
+
+utils.keccak256("0x")
+//!
+
+utils.keccak256("0x1234")
+//!
+
+// The value MUST be data, such as:
+//  - an Array of numbers
+//  - a data hex string (e.g. "0x1234")
+//  - a Uint8Array
+
+// Do NOT use UTF-8 strings that are not a DataHexstring
+utils.keccak256("hello world")
+//! error
+
+// If needed, convert strings to bytes first:
+utils.keccak256(utils.toUtf8Bytes("hello world"))
+//!
+
+// Or equivalently use the identity function:
+utils.id("hello world")
+//!
+
+// Keep in mind that the string "0x1234" represents TWO
+// bytes (i.e. [ 0x12, 0x34 ]. If you wish to compute the
+// hash of the 6 characters "0x1234", convert it to UTF-8
+// bytes first using utils.toUtf8Bytes.
+
+// Consider the following examples:
+
+// Hash of TWO (2) bytes:
+utils.keccak256("0x1234")
+//!
+
+// Hash of TWO (2) bytes: (same result)
+utils.keccak256([ 0x12, 0x34 ])
+//!
+
+const bytes = utils.toUtf8Bytes("0x1234");
+// <hide>
+bytes
+// </hide>
+//!
+
+// Hash of SIX (6) characters (different than above)
+utils.keccak256(bytes)
+//!
+
+// Hash of SIX (6) characters (same result)
+utils.id("0x1234")
+//!
+
+_code: RIPEMD160  @lang<javascript>
+
+utils.ripemd160("0x")
+//!
+
+utils.ripemd160("0x1234")
+//!
+
+_code: SHA-2  @lang<javascript>
+
+utils.sha256("0x")
+//!
+
+utils.sha256("0x1234")
+//!
+
+utils.sha512("0x")
+//!
+
+utils.sha512("0x1234")
+//!
+
+
+_subsection: HMAC @<utils--hmac>
+
+_property: ethers.utils.computeHmac(algorithm, key, data) => string<[[DataHexString]]>  @<utils-computeHmac> @SRC<sha2>
 Returns the [HMAC](link-wiki-hmac) of //data// with //key//
-using the [Algorithm](supported-algorithm) //algorithm//.
+using the [Algorithm](utils--hmac-supported-algorithm) //algorithm//.
 
-
-_heading: HMAC Supported Algorithms @<supported-algorithm> @SRC<sha2:enum.SupportedAlgorithm>
+_heading: **HMAC Supported Algorithms** @<utils--hmac-supported-algorithm> @SRC<sha2:enum.SupportedAlgorithm>
 
 _property: ethers.utils.SupportedAlgorithm.sha256 => string
 Use the [SHA2-256](link-wiki-sha2) hash algorithm.
@@ -33,37 +117,73 @@ Use the [SHA2-256](link-wiki-sha2) hash algorithm.
 _property: ethers.utils.SupportedAlgorithm.sha512 => string
 Use the [SHA2-512](link-wiki-sha2) hash algorithm.
 
+_code: HMAC  @lang<javascript>
 
-_subsection: Common Hashing Helpers
+const key = "0x0102";
+const data = "0x1234";
+utils.computeHmac("sha256", key, data)
+//!
 
-_property: ethers.utils.hashMessage(message) => string<[[datahexstring]]<32>>  @<utils-hashmessage> @SRC<hash>
+
+_subsection: Hashing Helpers @<utils--hashing-helpers>
+
+_property: ethers.utils.hashMessage(message) => string<[[DataHexString]]<32>>  @<utils-hashMessage> @SRC<hash>
 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](link-wiki-sha3) hash of the //text// bytes.
-
-_property: ethers.utils.namehash(name) => string<[[datahexstring]]<32>>  @<utils-namehash> @SRC<hash>
+_property: ethers.utils.namehash(name) => string<[[DataHexString]]<32>>  @<utils-namehash> @SRC<hash>
 Returns the [ENS Namehash](link-namehash) of //name//.
 
+_code: Hashing Messages  @lang<javascript>
 
-_subsection: Solidity Hashing Algorithms
+// @TODO: include examples of hashMessage; it can be complex. :)
+
+
+_code: Namehash  @lang<javascript>
+
+utils.namehash("")
+//!
+
+utils.namehash("eth")
+//!
+
+utils.namehash("ricmoo.firefly.eth")
+//!
+
+utils.namehash("ricmoo.xyz")
+//!
+
+
+_subsection: Solidity Hashing Algorithms @<utils--solidity-hashing>
 
 When using the Solidity ``abi.packEncoded(...)`` function, a non-standard
 //tightly packed// version of encoding is used. These functions implement
 the tightly packing algorithm.
 
-_property: ethers.utils.solidityPack(arrayOfTypes, arrayOfValues) => string<[[datahexstring]]>  @<utils-soliditypack> @SRC<solidity:pack>
-Returns the non-standard encoded //arrayOfValues// packed according to
-their respecive type in //arrayOfTypes//.
+_property: ethers.utils.solidityPack(types, values) => string<[[DataHexString]]>  @<utils-solidityPack> @SRC<solidity:pack>
+Returns the non-standard encoded //values// packed according to
+their respecive type in //types//.
 
-_property: ethers.utils.solidityKeccak256(arrayOfTypes, arrayOfValues) => string<[[datahexstring]]<32>>  @<utils-soliditykeccak256> @SRC<solidity:keccak256>
-Returns the [KECCAK256](link-wiki-sha3) of the non-standard encoded //arrayOfValues// packed
-according to their respective type in //arrayOfTypes//.
+_property: ethers.utils.solidityKeccak256(types, values) => string<[[DataHexString]]<32>>  @<utils-solidityKeccak256> @SRC<solidity:keccak256>
+Returns the [KECCAK256](link-wiki-sha3) of the non-standard encoded //values// packed
+according to their respective type in //types//.
 
-_property: ethers.utils.soliditySha256(arrayOfTypes, arrayOfValues) => string<[[datahexstring]]<32>>  @<utils-soliditysha256> @SRC<solidity:sha256>
-Returns the [SHA2-256](link-wiki-sha2) of the non-standard encoded //arrayOfValues// packed
-according to their respective type in //arrayOfTypes//.
+_property: ethers.utils.soliditySha256(types, values) => string<[[DataHexString]]<32>>  @<utils-soliditySha256> @SRC<solidity:sha256>
+Returns the [SHA2-256](link-wiki-sha2) of the non-standard encoded //values// packed
+according to their respective type in //types//.
 
+_code: Solidity Hashing  @lang<javascript>
+
+utils.solidityPack([ "int16", "uint48" ], [ -1, 12 ])
+//!
+
+utils.solidityPack([ "string", "uint8" ], [ "Hello", 3 ])
+//!
+
+utils.solidityKeccak256([ "int16", "uint48" ], [ -1, 12 ])
+//!
+
+utils.soliditySha256([ "int16", "uint48" ], [ -1, 12 ])
+//!
 

docs.wrm/api/utils/hdnode.wrm

@@ -1,16 +1,16 @@
-_section: HD Wallet
+_section: HD Wallet @<hdnodes>
 
 TODO: Explain [BIP32](link-bip-32) [BIP-39](link-bip-39) and whatnot here...
 
 _subsection: Types
 
-_heading: Constants @<hdnode-defaultpath> @SRC<hdnode:defaultPath>
+_heading: Constants @<hdnodes--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>
+_heading: Mnemonic @<Mnemonic>
 
 _property: mnemonic.phrase => string
 The mnemonic phrase for this mnemonic. It is 12, 15, 18, 21 or 24 words long
@@ -23,39 +23,39 @@ _property: mnemonic.locale => string
 The language of the wordlist this mnemonic is using.
 
 
-_subsection: HDNode @<hdnode> @SRC<hdnode:class.HDNode>
+_subsection: HDNode @<HDNode> @SRC<hdnode:class.HDNode>
 
-_heading: Creating Instances
+_heading: Creating Instances @<HDNode--creating>
 
-_property: ethers.HDNode.fromMnemonic(phrase [, password [, wordlist ] ]) => [[hdnode]]  @SRC<hdnode>
-Return the [[hdnode]] for //phrase// with the optional //password//
+_property: ethers.HDNode.fromMnemonic(phrase [, password [, wordlist ] ]) => [[HDNode]]  @<HDNode-fromMnemonic> @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.fromSeed(aBytesLike) => [[HDNode]]  @<HDNode-fromSeed> @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
+_property: ethers.HDNode.fromExtendedKey(extendedKey) => [[HDNode]]  @<HDNode-fromExtendedKey> @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
+_heading: Properties  @<HDNode--properties>
 
-_property: hdNode.privateKey => string<[[datahexstring]]<32>>
+_property: hdNode.privateKey => string<[[DataHexString]]<32>>
 The private key for this HDNode.
 
-_property: hdNode.publicKey => string<[[datahexstring]]<33>>
+_property: hdNode.publicKey => string<[[DataHexString]]<33>>
 The (compresses) public key for this HDNode.
 
-_property: hdNode.fingerprint => string<[[datahexstring]]<4>>
+_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>>
+_property: hdNode.parentFingerprint => string<[[DataHexString]]<4>>
 The fingerprint of the parent node. See //fingerprint// for more
 details.
 
@@ -64,14 +64,14 @@ Most developers will not need to use this.
 _property: hdNode.address => string<[[address]]>
 The address of this HDNode.
 
-_property: hdNode.mnemonic => [[hdnode-mnemonic]]
+_property: hdNode.mnemonic => [[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>>
+_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.
@@ -97,29 +97,29 @@ serializing and deserializing (using the ``fromExtendedKey`` class
 method) will result in reduced information.
 
 
-_heading: Methods
+_heading: Methods  @<HDNode--methods>
 
-_property: hdNode.neuter() => [[hdnode]] @SRC<hdnode>
+_property: hdNode.neuter() => [[HDNode]]  @<HDNode-neuter> @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
+_property: hdNode.derivePath(path) => [[HDNode]]  @<HDNode-derivePath> @SRC<hdnode>
+Return a new [[HDNode]] which is the child of //hdNode// found
 by deriving //path//.
 
 
 
-_subsection: Other Functions
+_subsection: Other Functions  @<HDNode--utilities>
 
-_property: ethers.utils.mnemonicToSeed(phrase [ , password]) => string<[[datahexstring]]<64>>  @SRC<hdnode>
+_property: ethers.utils.mnemonicToSeed(phrase [ , password]) => string<[[DataHexString]]<64>>  @<utils-mnemonicToSeed> @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>
+_property: ethers.utils.mnemonicToEntropy(phrase [ , wordlist ]) => string<[[DataHexString]]>  @<utils-mnemonicToEntropy> @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>
+_property: ethers.utils.isValidMnemonic(phrase [ , wordlist ]) => boolean  @<utils-isValidMnemonic> @SRC<hdnode>
 Returns true if //phrase// is a valid mnemonic phrase, by
 testing the checksum.

docs.wrm/api/utils/logger.wrm

@@ -3,21 +3,21 @@ _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
+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
+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>
+_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>
+_property: Logger.globalLogger() => [[Logger]] @SRC<logger>
 Returns the singleton global logger.
 
 
@@ -35,7 +35,7 @@ Log warnings.
 
 _heading: Errors
 
-These functions honor the current [Censorship](logger-censorship) and help create
+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>
@@ -48,7 +48,7 @@ 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//.
+Throw an [INVALID_ARGUMENT](errors-InvalidArgument) Error with //name// and //value//.
 
 
 _heading: Usage Validation
@@ -61,24 +61,24 @@ 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.
+If //count// is not equal to //expectedCount//, throws a [MISSING_ARGUMENT](errors-MissingArgument)
+or [UNEXPECTED_ARGUMENT](errors-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
+[MISSING_NEW](errors-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.
+[UNSUPPORTED_OPERATION](errors-UnsupportedOperation) 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.
+[NUMERIC_FAULT](errors-NumericFault) error.
 
 
-_heading: Censorship @<logger-censorship>
+_heading: Censorship @<Logger--censorship>
 
 _property: Logger.setCensorship(censor [ , permanent = false ]) => void @SRC<logger>
 Set error censorship, optionally preventing errors from being uncensored.
@@ -89,7 +89,7 @@ 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).
+Set the log level, to suppress logging output below a [particular log level](Logger-levels).
 
 
 _subsection: Errors @<errors>
@@ -106,13 +106,13 @@ The operation is not implemented.
 _property: Logger.errors.SERVER_ERROR
 There was an error communicating with a server.
 
-_property: Logger.errors.TIMEOUT @<error-timeout>
+_property: Logger.errors.TIMEOUT @<errors-Timeout>
 A timeout occurred.
 
-_property: Logger.errors.UNKNOWN_ERROR @<error-unknown>
+_property: Logger.errors.UNKNOWN_ERROR @<errors-UnknownError>
 A generic unknown error.
 
-_property: Logger.errors.UNSUPPORTED_OPERATION @<error-unsupported>
+_property: Logger.errors.UNSUPPORTED_OPERATION @<errors-UnsupportedOperation>
 The operation is not supported.
 
 
@@ -122,7 +122,7 @@ _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>
+_property: Logger.errors.NUMERIC_FAULT @<errors-NumericFault>
 There was an invalid operation done on numeric values.
 
 Common cases of this occur when there is [[link-wiki-overflow]],
@@ -131,19 +131,19 @@ Common cases of this occur when there is [[link-wiki-overflow]],
 
 _heading: Usage Error Codes
 
-_property: Logger.errors.INVALID_ARGUMENT @<error-invalidargument>
+_property: Logger.errors.INVALID_ARGUMENT @<errors-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>
+_property: Logger.errors.MISSING_ARGUMENT @<errors-MissingArgument>
 An expected parameter was not specified.
 
-_property: Logger.errors.MISSING_NEW @<error-missingnew>
+_property: Logger.errors.MISSING_NEW @<errors-MissingNew>
 An object is a Class, but is now being called with ``new``.
 
-_property: Logger.errors.UNEXPECTED_ARGUMENT @<error-unexpectedargument>
+_property: Logger.errors.UNEXPECTED_ARGUMENT @<errors-UnexpectedArgument>
 Too many parameters we passed into a function.
 
 
@@ -190,7 +190,7 @@ 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>
+_subsection: Log Levels @<Logger-levels>
 
 _property: Logger.levels.DEBUG
 Log all output, including debugging information.

docs.wrm/api/utils/properties.wrm

@@ -1,6 +1,6 @@
 _section: Property Utilities
 
-_property: ethers.utils.checkPropertoes() => void
+_property: ethers.utils.checkProperties() => void
 
 _property: ethers.utils.deepCopy(anObject) => any
 _property: ethers.utils.defineReadOnly(anObject, name, value) => void

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

@@ -1,23 +1,23 @@
-_section: Signing Key @<utils-signingkey>
+_section: Signing Key @<SigningKey>
 
-_property: new ethers.utils.SigningKey(privateKey)
+_property: new ethers.utils.SigningKey(privateKey)  @<SigningKey-constructor> @src<signing-key:constructor.SigningKey>
 Create a new SigningKey for //privateKey//.
 
-_property: signingKey.privateKey => string<[[datahexstring]]<32>>
+_property: signingKey.privateKey => string<[[DataHexString]]<32>>
 The private key for this Signing Key.
 
-_property: signingKey.publicKey => string<[[datahexstring]]<65>>
+_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>>
+_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]]
+_property: signingKey.signDigest(digest) => [[Signature]]
 Sign the //digest// and return the signature.
 
-_property: signingKey.computeSharedSecret(otherKey) => string<[[datahexstring]]<32>>
+_property: signingKey.computeSharedSecret(otherKey) => string<[[DataHexString]]<32>>  @SRC<signing-key>
 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.
@@ -25,13 +25,13 @@ 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
+_property: SigningKey.isSigningKey(anObject) => boolean  @SRC<signing-key>
 Returns true if //anObject// is a SigningKey.
 
 
 _subsection: Other Functions
 
-_property: ethers.utils.verifyMessage(message, signature) => string<[[address]]>  @<utils-verifymessage> @SRC<wallet>
+_property: ethers.utils.verifyMessage(message, signature) => string<[[address]]>  @<utils-verifyMessage> @SRC<wallet>
 Returns the address that signed //message// producing //signature//. The
 signature may have a non-canonical v (i.e. does not need to be 27 or 28),
 in which case it will be normalized to compute the `recoveryParam` which
@@ -39,9 +39,9 @@ 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.recoverPublicKey(digest, signature) => string<[[DataHexString]]<65>> @<utils-recoverPublicKey>
 
-_property: ethers.utils.computePublicKey(key [, compressed = false ]) => string<[[datahexstring]]> @<utils-computepublickey>
+_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,9 +1,9 @@
-_section: Strings
+_section: Strings  @<strings>
 
 Tra la la
 
 
-_subsection: Bytes32String @<bytes32-string>
+_subsection: Bytes32String @<Bytes32String>
 
 A string in Solidity is length prefixed with its 256-bit (32 byte)
 length, which means that even short strings require 2 words (64 bytes)
@@ -19,23 +19,23 @@ _note: Note
 Strings that are 31 __//bytes//__ long may contain fewer than 31 __//characters//__,
 since UTF-8 requires multiple bytes to encode international characters.
 
-_property: ethers.utils.parseBytes32String(aBytesLike) => string  @<utils-parsebytes32> @SRC<strings>
+_property: ethers.utils.parseBytes32String(aBytesLike) => string  @<utils-parseBytes32> @SRC<strings>
 Returns the decoded string represented by the ``Bytes32`` encoded data.
 
-_property: ethers.utils.formatBytes32String(text) => string<[[datahexstring]]<32>>  @<utils-formatbytes32> @SRC<strings>
+_property: ethers.utils.formatBytes32String(text) => string<[[DataHexString]]<32>>  @<utils-formatBytes32> @SRC<strings>
 Returns a ``bytes32`` string representation of //text//. If the
 length of //text// exceeds 31 bytes, it will throw an error.
 
 
-_subsection: UTF-8 Strings @<utf8-string>
+_subsection: UTF-8 Strings @<strings-utf8>
 
-_property: ethers.utils.toUtf8Bytes(text [ , form = current ] ) => Uint8Array  @<utils-toutf8bytes> @SRC<strings>
+_property: ethers.utils.toUtf8Bytes(text [ , form = current ] ) => Uint8Array  @<utils-toUtf8Bytes> @SRC<strings>
 Returns the UTF-8 bytes of //text//, optionally normalizing it using the
-[[unicode-normalization-form]] //form//.
+[[strings--unicode-normalization-form]] //form//.
 
-_property: ethers.utils.toUtf8CodePoints(text [ , form = current ] ) => Array<number>  @<utils-toutf8codepoints> @SRC<strings>
+_property: ethers.utils.toUtf8CodePoints(text [ , form = current ] ) => Array<number>  @<utils-toUtf8CodePoints> @SRC<strings>
 Returns the Array of codepoints of //text//, optionally normalized using the
-[[unicode-normalization-form]] //form//.
+[[strings--unicode-normalization-form]] //form//.
 
 _note: Note
 This function correctly splits each **user-perceived character** into
@@ -43,14 +43,14 @@ its codepoint, accounting for surrogate pairs. This should not be confused with
 ``string.split("")``, which destroys surrogate pairs, spliting between each UTF-16
 codeunit instead.
 
-_property: ethers.utils.toUtf8String(aBytesLike [ , onError = error ] ) => string  @<utils-toutf8string> @SRC<strings>
+_property: ethers.utils.toUtf8String(aBytesLike [ , onError = error ] ) => string  @<utils-toUtf8String> @SRC<strings>
 Returns the string represented by the UTF-8 bytes of //aBytesLike//.
 
-The //onError// is a [Custom UTF-8 Error function](utf8error) and if not specified
-it defaults to the [error](utf8error-error) function, which throws an error
+The //onError// is a [Custom UTF-8 Error function](strings--error-handling) and if not specified
+it defaults to the [error](strings--Utf8Error) function, which throws an error
 on **any** UTF-8 error.
 
-_subsection: UnicodeNormalizationForm @<unicode-normalization-form> @SRC<strings/utf8:enum.UnicodeNormalizationForm>
+_subsection: UnicodeNormalizationForm @<strings--unicode-normalization-form> @SRC<strings/utf8:enum.UnicodeNormalizationForm>
 
 There are several [commonly used forms](link-wiki-unicode-equivalence)
 when normalizing UTF-8 data, which allow strings to be compared or hashed in a stable
@@ -91,7 +91,8 @@ Only certain specified characters are folded in Canonical Equivalence, and thus
 it should **not** be considered a method to acheive //any// level of security from
 [homoglyph attacks](link-wiki-homoglyph).
 
-_subsection: Custom UTF-8 Error Handling @<utf8error>
+
+_subsection: Custom UTF-8 Error Handling @<strings--error-handling>
 
 When converting a string to its codepoints, there is the possibility
 of invalid byte sequences. Since certain situations may need specific
@@ -99,7 +100,7 @@ ways to handle UTF-8 errors, a custom error handling function can be used,
 which has the signature:
 
 _property: errorFunction(reason, offset, bytes, output [ , badCodepoint ]) => number
-The //reason// is one of the [UTF-8 Error Reasons](utf8error-reasons), //offset// is the index
+The //reason// is one of the [UTF-8 Error Reasons](strings--error-reasons), //offset// is the index
 into //bytes// where the error was first encountered, output is the list
 of codepoints already processed (and may be modified) and in certain Error
 Reasons, the //badCodepoint// indicates the currently computed codepoint,
@@ -108,7 +109,8 @@ but which would be rejected because its value is invalid.
 This function should return the number of bytes to skip past keeping in
 mind the value at //offset// will already be consumed.
 
-_heading: UTF-8 Error Reasons @<utf8error-reasons> @SRC<strings/utf8:Utf8ErrorReason>
+
+_heading: UTF-8 Error Reasons @<strings--error-reasons> @SRC<strings/utf8:Utf8ErrorReason>
 
 _property: ethers.utils.Utf8ErrorReason.BAD_PREFIX
 A byte was encountered which is invalid to begin a UTF-8 byte
@@ -166,16 +168,16 @@ _heading: Provided UTF-8 Error Handling Functions
 There are already several functions available for the  most common
 situations.
 
-_property: ethers.utils.Utf8ErrorFuncs.error @<utf8error-error> @SRC<strings/utf8:errorFunc>
+_property: ethers.utils.Utf8ErrorFuncs.error @<strings--Utf8Error> @SRC<strings/utf8:errorFunc>
 The will throw an error on **any** error with a UTF-8 sequence, including
 invalid prefix bytes, overlong sequences, UTF-16 surrogate pairs.
 
-_property: ethers.utils.Utf8ErrorFuncs.ignore @<utf8error-ignore> @SRC<strings/utf8:ignoreFunc>
+_property: ethers.utils.Utf8ErrorFuncs.ignore @<strings--Utf8Ignore> @SRC<strings/utf8:ignoreFunc>
 This will drop all invalid sequences (by consuming invalid prefix bytes and
 any following continuation bytes) from the final string as well as permit
 overlong sequences to be converted to their equivalent string.
 
-_property: ethers.utils.Utf8ErrorFuncs.replace @<utf8error-replace> @SRC<strings/utf8:replaceFunc>
+_property: ethers.utils.Utf8ErrorFuncs.replace @<strings--Utf8Replace> @SRC<strings/utf8:replaceFunc>
 This will replace all invalid sequences (by consuming invalid prefix bytes and
 any following continuation bytes) with the
 [UTF-8 Replacement Character](link-wiki-utf8-replacement),

docs.wrm/api/utils/transactions.wrm

@@ -1,8 +1,8 @@
-_section: Transactions @<utils-transactions>
+_section: Transactions @<transactions>
 
-_subsection: Types
+_subsection: Types @<transactions--types>
 
-_heading: UnsignedTransaction @<types-unsignedtransaction>
+_heading: UnsignedTransaction @<UnsignedTransaction>
 An unsigned transaction represents a transaction that has not been
 signed and its values are flexible as long as they are not ambiguous.
 
@@ -12,16 +12,16 @@ The addres this transaction is to.
 _property: unsignedTransaction.nonce => number
 The nonce of this transaction.
 
-_property: unsignedTransaction.gasLimit => [[bignumberish]]
+_property: unsignedTransaction.gasLimit => [[BigNumberish]]
 The gas limit for this transaction.
 
-_property: unsignedTransaction.gasPrice => [[bignumberish]]
+_property: unsignedTransaction.gasPrice => [[BigNumberish]]
 The gas price for this transaction.
 
-_property: unsignedTransaction.data => [[byteslike]]
+_property: unsignedTransaction.data => [[BytesLike]]
 The data for this transaction.
 
-_property: unsignedTransaction.value => [[bignumberish]]
+_property: unsignedTransaction.value => [[BigNumberish]]
 The value (in wei) for this transaction.
 
 _property: unsignedTransaction.chainId => number
@@ -30,10 +30,10 @@ then [[link-eip-155]] is disabled and legacy signing is
 used, unless overridden in a signature.
 
 
-_heading: Transaction @<types-transaction>
+_heading: Transaction @<Transaction>
 A generic object to represent a transaction.
 
-_property: transaction.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//.
@@ -50,20 +50,20 @@ 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: transaction.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: transaction.gasPrice => [[bignumber]]
+_property: transaction.gasPrice => [[BigNumber]]
 The price (in wei) per unit of gas for //transaction//.
 
-_property: transaction.data => [[byteslike]]
+_property: transaction.data => [[BytesLike]]
 The data for //transaction//. In a contract this is the call data.
 
-_property: transaction.value => [[bignumber]]
+_property: transaction.value => [[BigNumber]]
 The value (in wei) for //transaction//.
 
 _property: transaction.chainId => number
@@ -80,12 +80,12 @@ 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: transaction.r => string<[[datahexstring]]<32>>
+_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>>
+_property: transaction.s => string<[[DataHexString]]<32>>
 The s portion of the elliptic curve signatures for //transaction//.
 
 _property: transaction.v => number
@@ -95,20 +95,12 @@ x-coordinate can have, and in [[link-eip-155]] is additionally
 used to encode the chain ID into the serialized transaction.
 
 
-_subsection: Functions
+_subsection: Functions  @<transactions--functions>
 
-_property: ethers.utils.computeAddress(publicOrPrivateKey) => string<[Address](address)>  @<utils-computeaddress> @SRC<transactions>
-Compute the address of //publicOrPrivateKey//. If a public key is
-provided, it may be either compressed or uncompressed.
-
-_property: ethers.utils.parse(aBytesLike) => [[types-transaction]]  @<utils-parse> @SRC<transactions>
+_property: ethers.utils.parseTransaction(aBytesLike) => [[Transaction]]  @<utils-parseTransaction> @SRC<transactions:parse>
 Parses the transaction properties from a serialized transactions.
 
-_property: ethers.utils.recoverAddress(digest, aSignatureLike) => string<[Address](address)>  @<utils-recoveraddress> @SRC<transactions>
-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>
+_property: ethers.utils.serializeTransaction(tx [ , signature ]) => string<[[DataHexString]]>  @<utils-serializeTransaction> @SRC<transactions:serialize>
 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

docs.wrm/api/utils/web.wrm

@@ -1,17 +1,17 @@
-_section: Web Utilities
+_section: Web Utilities  @<web>
 
 
-_property: ethers.utils.fetchJson(urlOrConnectionInfo [, json [ , processFunc ] ]) => Promise<any> @<web-fetchjson>
+_property: ethers.utils.fetchJson(urlOrConnectionInfo [, json [ , processFunc ] ]) => Promise<any> @<utils-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
+_property: ethers.utils.poll(pollFunc [, options ]) => Promise<any> @<utils-poll>
+Repeatedly call pollFunc using the [[PollOptions]] until it returns a
 value other than undefined.
 
 
-_heading: Connection Info @<web-connectioninfo>
+_heading: ConnectionInfo @<ConnectionInfo>
 
 _property: connection.url => string
 The URL to connect to.
@@ -34,7 +34,7 @@ _property: connection.headers => { [ key: string]: string }
 Additional headers to include in the connection.
 
 
-_heading: Poll Options @<web-polloptions>
+_heading: PollOptions @<PollOptions>
 
 _property: options.timeout => number
 The amount of time allowed to ellapse before triggering a timeout
@@ -59,6 +59,11 @@ _property: options.retryLimit => number
 The number of times to retry in the event of an error or //undefined// is
 returned.
 
-_property: options.onceBlock => [[provider]]
+_property: options.onceBlock => [[Provider]]
 If this is specified, the polling will wait on new blocks from
 //provider// before attempting the //pollFunc// again.
+
+_property: options.oncePoll => [[Provider]]
+If this is specified, the polling will occur on each poll
+cycle of //provider// before attempting the //pollFunc//
+again.

docs.wrm/api/utils/wordlists.wrm

@@ -1,6 +1,6 @@
 _section: Wordlists @<wordlists>
 
-_subsection: Wordlist @<wordlist>
+_subsection: Wordlist @<Wordlist>
 
 _property: wordlist.locale => string
 The locale for this wordlist.
@@ -19,7 +19,7 @@ _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>>
+_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.
@@ -28,31 +28,36 @@ _property: Wordlist.register(wordlist [ , name ]) => void
 Register a wordlist with the list of wordlists, optionally overriding
 the registered //name//.
 
-_subsection: Languages @<wordlist-languages>
+_subsection: Languages @<wordlists--languages>
+
+The [official wordlists](link-bip39-wordlists) availalbe in at
+`ethers.wordlists`. In the browser, only the english langauge is
+available by default; to include the others (which increases the
+size of the library), see the dist files in the `ethers` package.
 
 _property: ethers.wordlists.cz => Wordlist
-The Czech [[wordlist]].
+The Czech [[Wordlist]].
 
 _property: ethers.wordlists.en => Wordlist
-The English [[wordlist]].
+The English [[Wordlist]].
 
 _property: ethers.wordlists.es => Wordlist
-The Spanish [[wordlist]].
+The Spanish [[Wordlist]].
 
 _property: ethers.wordlists.fr => Wordlist
-The French [[wordlist]].
+The French [[Wordlist]].
 
 _property: ethers.wordlists.it => Wordlist
-The Italian [[wordlist]].
+The Italian [[Wordlist]].
 
 _property: ethers.wordlists.ja => Wordlist
-The Japanese [[wordlist]].
+The Japanese [[Wordlist]].
 
 _property: ethers.wordlists.ko => Wordlist
-The Korean [[wordlist]].
+The Korean [[Wordlist]].
 
 _property: ethers.wordlists.zh_cn => Wordlist
-The Simplified Chinese [[wordlist]].
+The Simplified Chinese [[Wordlist]].
 
 _property: ethers.wordlists.zh_tw => Wordlist
-The Traditional Chinese [[wordlist]].
+The Traditional Chinese [[Wordlist]].

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

@@ -1,11 +0,0 @@
-/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

@@ -1,57 +0,0 @@
-/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

@@ -1,14 +0,0 @@
-Usage:
-   ethers-asm [ FILENAME ] [ OPTIONS ]
-
-OPTIONS
-  --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
-  --help                      Show this usage and exit
-  --version                   Show this version and exit

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

@@ -1,48 +0,0 @@
-; 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

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

docs.wrm/cli/asm.wrm

@@ -7,18 +7,88 @@ and disassemle EVM bytecode into human-readable mnemonics.
 
 _subsection: Help
 
-_code: asm-help.txt
+_code: @lang<text>
+
+Usage:
+   ethers-asm [ FILENAME ] [ OPTIONS ]
+
+OPTIONS
+  --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
+  --help                      Show this usage and exit
+  --version                   Show this version and exit
 
 
 _subsection: Example Input Files
 
-_definition: **SimpleStore.asm**
+_code: SimpleStore.asm  @lang<asm>
 
-_code: asm-simplestore-asm.txt
+; SimpleStore (uint)
 
-_definition: **SimpleStore.bin**
+; 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")
+        }}
+    ]
+}
+
+
+_code: SimpleStore.bin  @lang<text>
+
+0x602a6000556044601160003960446000f334601e5760003560e01c8063209652
+0x5514602457806355241077146030575b60006000fd5b60005460005260206000
+0xf35b6024361415601e5760043560005560006000f3
 
-_code: asm-simplestore-bin.txt
 
 _note: Note: Bytecode File Syntax
 A bin file may be made up of multiple blocks of bytecode, each may
@@ -38,7 +108,19 @@ 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
+_code: @lang<shell>
+
+/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
+
 
 _heading: Options
 
@@ -77,5 +159,62 @@ 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
+_code: @lang<shell>
 
+/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/ens-help.txt

@@ -1,69 +0,0 @@
-Usage:
-   ethers-ens COMMAND [ ARGS ] [ OPTIONS ]
-
-COMMANDS
-   lookup [ NAME | ADDRESS [ ... ] ]
-                              Lookup a name or address
-   commit NAME                Submit a pre-commitment
-      [ --duration DAYS ]        Register duration (default: 365 days)
-      [ --salt SALT ]            SALT to blind the commit with
-      [ --secret SECRET ]        Use id(SECRET) as the salt
-      [ --owner OWNER ]          The target owner (default: current account)
-   reveal NAME                Reveal a previous pre-commitment
-      [ --duration DAYS ]        Register duration (default: 365 days)
-      [ --salt SALT ]            SALT to blind the commit with
-      [ --secret SECRET ]        Use id(SECRET) as the salt
-      [ --owner OWNER ]          The target owner (default: current account)
-   set-controller NAME        Set the controller (default: current account)
-      [ --address ADDRESS ]      Specify another address
-   set-subnode NAME           Set a subnode owner (default: current account)
-      [ --address ADDRESS ]      Specify another address
-   set-resolver NAME          Set the resolver (default: resolver.eth)
-      [ --address ADDRESS ]      Specify another address
-   set-addr NAME              Set the addr record (default: current account)
-      [ --address ADDRESS ]      Specify another address
-   set-text NAME KEY VALUE    Set a text record
-   set-email NAME EMAIL       Set the email text record
-   set-website NAME URL       Set the website text record
-   set-content NAME HASH      Set the IPFS Content Hash
-   migrate-registrar NAME     Migrate from the Legacy to the Permanent Registrar
-   transfer NAME NEW_OWNER    Transfer registrant ownership
-   reclaim NAME               Reset the controller by the registrant
-      [ --address ADDRESS ]      Specify another address
-
-ACCOUNT OPTIONS
-  --account FILENAME          Load from a file (JSON, RAW or mnemonic)
-  --account RAW_KEY           Use a private key (insecure *)
-  --account 'MNEMONIC'        Use a mnemonic (insecure *)
-  --account -                 Use secure entry for a raw key or mnemonic
-  --account-void ADDRESS      Use an address as a void signer
-  --account-void ENS_NAME     Add the resolved address as a void signer
-  --account-rpc ADDRESS       Add the address from a JSON-RPC provider
-  --account-rpc INDEX         Add the index from a JSON-RPC provider
-  --mnemonic-password         Prompt for a password for mnemonics
-  --xxx-mnemonic-password     Prompt for a (experimental) hard password
-
-PROVIDER OPTIONS (default: all + homestead)
-  --alchemy                   Include Alchemy
-  --etherscan                 Include Etherscan
-  --infura                    Include INFURA
-  --nodesmith                 Include nodesmith
-  --rpc URL                   Include a custom JSON-RPC
-  --offline                   Dump signed transactions (no send)
-  --network NETWORK           Network to connect to (default: homestead)
-
-TRANSACTION OPTIONS (default: query network)
-  --gasPrice GWEI             Default gas price for transactions(in wei)
-  --gasLimit GAS              Default gas limit for transactions
-  --nonce NONCE               Initial nonce for the first transaction
-  --yes                       Always accept Siging and Sending
-
-OTHER OPTIONS
-  --wait                      Wait until transactions are mined
-  --debug                     Show stack traces for errors
-  --help                      Show this usage and exit
-  --version                   Show this version and exit
-
-(*) By including mnemonics or private keys on the command line they are
-    possibly readable by other users on your system and may get stored in
-    your bash history file. This is NOT recommended.

docs.wrm/cli/ens.wrm

@@ -2,7 +2,78 @@ _section: Ethereum Naming Service @NAV<ENS>
 
 _subsection: Help
 
-_code: ens-help.txt
+_code: @lang<text>
+
+Usage:
+   ethers-ens COMMAND [ ARGS ] [ OPTIONS ]
+
+COMMANDS
+   lookup [ NAME | ADDRESS [ ... ] ]
+                              Lookup a name or address
+   commit NAME                Submit a pre-commitment
+      [ --duration DAYS ]        Register duration (default: 365 days)
+      [ --salt SALT ]            SALT to blind the commit with
+      [ --secret SECRET ]        Use id(SECRET) as the salt
+      [ --owner OWNER ]          The target owner (default: current account)
+   reveal NAME                Reveal a previous pre-commitment
+      [ --duration DAYS ]        Register duration (default: 365 days)
+      [ --salt SALT ]            SALT to blind the commit with
+      [ --secret SECRET ]        Use id(SECRET) as the salt
+      [ --owner OWNER ]          The target owner (default: current account)
+   set-controller NAME        Set the controller (default: current account)
+      [ --address ADDRESS ]      Specify another address
+   set-subnode NAME           Set a subnode owner (default: current account)
+      [ --address ADDRESS ]      Specify another address
+   set-resolver NAME          Set the resolver (default: resolver.eth)
+      [ --address ADDRESS ]      Specify another address
+   set-addr NAME              Set the addr record (default: current account)
+      [ --address ADDRESS ]      Specify another address
+   set-text NAME KEY VALUE    Set a text record
+   set-email NAME EMAIL       Set the email text record
+   set-website NAME URL       Set the website text record
+   set-content NAME HASH      Set the IPFS Content Hash
+   migrate-registrar NAME     Migrate from the Legacy to the Permanent Registrar
+   transfer NAME NEW_OWNER    Transfer registrant ownership
+   reclaim NAME               Reset the controller by the registrant
+      [ --address ADDRESS ]      Specify another address
+
+ACCOUNT OPTIONS
+  --account FILENAME          Load from a file (JSON, RAW or mnemonic)
+  --account RAW_KEY           Use a private key (insecure *)
+  --account 'MNEMONIC'        Use a mnemonic (insecure *)
+  --account -                 Use secure entry for a raw key or mnemonic
+  --account-void ADDRESS      Use an address as a void signer
+  --account-void ENS_NAME     Add the resolved address as a void signer
+  --account-rpc ADDRESS       Add the address from a JSON-RPC provider
+  --account-rpc INDEX         Add the index from a JSON-RPC provider
+  --mnemonic-password         Prompt for a password for mnemonics
+  --xxx-mnemonic-password     Prompt for a (experimental) hard password
+
+PROVIDER OPTIONS (default: all + homestead)
+  --alchemy                   Include Alchemy
+  --etherscan                 Include Etherscan
+  --infura                    Include INFURA
+  --nodesmith                 Include nodesmith
+  --rpc URL                   Include a custom JSON-RPC
+  --offline                   Dump signed transactions (no send)
+  --network NETWORK           Network to connect to (default: homestead)
+
+TRANSACTION OPTIONS (default: query network)
+  --gasPrice GWEI             Default gas price for transactions(in wei)
+  --gasLimit GAS              Default gas limit for transactions
+  --nonce NONCE               Initial nonce for the first transaction
+  --yes                       Always accept Siging and Sending
+
+OTHER OPTIONS
+  --wait                      Wait until transactions are mined
+  --debug                     Show stack traces for errors
+  --help                      Show this usage and exit
+  --version                   Show this version and exit
+
+(*) By including mnemonics or private keys on the command line they are
+    possibly readable by other users on your system and may get stored in
+    your bash history file. This is NOT recommended.
+
 
 _subsection: Examples
 

docs.wrm/cli/ethers-help.txt

@@ -1,65 +0,0 @@
-Usage:
-   ethers [ COMMAND ] [ ARGS ] [ OPTIONS ]
-
-COMMANDS (default: sandbox)
-   sandbox                    Run a REPL VM environment with ethers
-   init FILENAME              Create a new JSON wallet
-      [ --force ]                Overwrite any existing files
-   fund TARGET                Fund TARGET with testnet ether
-   info [ TARGET ... ]        Dump info for accounts, addresses and ENS names
-   send TARGET ETHER          Send ETHER ether to TARGET form accounts[0]
-      [ --allow-zero ]           Allow sending to the address zero
-      [ --data DATA ]            Include data in the transaction
-   sweep TARGET               Send all ether from accounts[0] to TARGET
-   sign-message MESSAGE       Sign a MESSAGE with accounts[0]
-      [ --hex ]                  The message content is hex encoded
-   eval CODE                  Run CODE in a VM with ethers
-   run FILENAME               Run FILENAME in a VM with ethers
-   wait HASH                  Wait for a transaction HASH to be mined
-   wrap-ether VALUE           Deposit VALUE into Wrapped Ether (WETH)
-   unwrap-ether VALUE         Withdraw VALUE from Wrapped Ether (WETH)
-   send-token TOKEN ADDRESS VALUE
-                              Send VALUE tokens (at TOKEN) to ADDRESS
-   compile FILENAME           Compiles a Solidity contract
-      [ --no-optimize ]          Do not optimize the compiled output
-      [ --warnings ]             Error on any warning
-   deploy FILENAME            Compile and deploy a Solidity contract
-      [ --no-optimize ]          Do not optimize the compiled output
-      [ --contract NAME ]        Specify the contract to deploy
-
-ACCOUNT OPTIONS
-  --account FILENAME          Load from a file (JSON, RAW or mnemonic)
-  --account RAW_KEY           Use a private key (insecure *)
-  --account 'MNEMONIC'        Use a mnemonic (insecure *)
-  --account -                 Use secure entry for a raw key or mnemonic
-  --account-void ADDRESS      Use an address as a void signer
-  --account-void ENS_NAME     Add the resolved address as a void signer
-  --account-rpc ADDRESS       Add the address from a JSON-RPC provider
-  --account-rpc INDEX         Add the index from a JSON-RPC provider
-  --mnemonic-password         Prompt for a password for mnemonics
-  --xxx-mnemonic-password     Prompt for a (experimental) hard password
-
-PROVIDER OPTIONS (default: all + homestead)
-  --alchemy                   Include Alchemy
-  --etherscan                 Include Etherscan
-  --infura                    Include INFURA
-  --nodesmith                 Include nodesmith
-  --rpc URL                   Include a custom JSON-RPC
-  --offline                   Dump signed transactions (no send)
-  --network NETWORK           Network to connect to (default: homestead)
-
-TRANSACTION OPTIONS (default: query network)
-  --gasPrice GWEI             Default gas price for transactions(in wei)
-  --gasLimit GAS              Default gas limit for transactions
-  --nonce NONCE               Initial nonce for the first transaction
-  --yes                       Always accept Siging and Sending
-
-OTHER OPTIONS
-  --wait                      Wait until transactions are mined
-  --debug                     Show stack traces for errors
-  --help                      Show this usage and exit
-  --version                   Show this version and exit
-
-(*) By including mnemonics or private keys on the command line they are
-    possibly readable by other users on your system and may get stored in
-    your bash history file. This is NOT recommended.

docs.wrm/cli/ethers-init.txt

@@ -1,14 +0,0 @@
-/home/ethers> ethers init wallet.json
-Creating a new JSON Wallet - wallet.json
-Keep this password and file SAFE!! If lost or forgotten
-it CANNOT be recovered, by ANYone, EVER.
-Choose a password: ******
-Confirm password: ******
-Encrypting... 100%
-New account address: 0x485bcC23ae2E5038ec7ec9b8DCB2A6A6291cC003
-Saved:               wallet.json
-
-
-# If you are planning to try out the Ropsten testnet...
-/home/ethers> ethers --network ropsten fund 0x485bcC23ae2E5038ec7ec9b8DCB2A6A6291cC003
-Transaction Hash: 0x8dc55b8f8dc8076acded97f9e3ed7d6162460c0221e2769806006b6d7d1156e0

docs.wrm/cli/ethers-mnemonic-hard.txt

@@ -1,8 +0,0 @@
-/home/ricmoo> ethers --account mnemonic.txt --xxx-mnemonic-password
-Password (mnemonic; experimental - hard): ******
-Decrypting... 100%
-network: homestead (chainId: 1)
-homestead> accounts[0].getAddress()
-<Promise id=0 resolved>
-'0x56FC8792cC17971C19bEC4Ced978beEA44711EeD'
-homestead> 

docs.wrm/cli/ethers-mnemonic.txt

@@ -1,7 +0,0 @@
-/home/ricmoo> ethers --account public-mnemonic.txt --mnemonic-password
-Password (mnemonic): ******
-network: homestead (chainId: 1)
-homestead> accounts[0].getAddress()
-<Promise id=0 resolved>
-'0x6d3F723EC1B73141AA4aC248c3ab34A5a1DAD776'
-homestead> 

docs.wrm/cli/ethers-script.txt

@@ -1,19 +0,0 @@
-# Get the formatted balance of an account
-/home/ethers> ethers --network ropsten --account wallet.json eval 'accounts[0].getBalance().then(b => formatEther(b))'
-3.141592653589793238
-
-# Get the current block number
-/home/ethers> ethers --network rinkeby eval "provider.getBlockNumber()"
-5761009
-
-# Convert a Solidity signature to JSON
-/home/ethers> ethers eval 'utils.Fragment.from("function balanceOf(address owner) view returns (uint)").format("json")' 
-{"type":"function","name":"balanceOf","constant":true,"stateMutability":"view","payble":false,"inputs":[{"type":"address","name":"owner"}],"ouputs":[{"type":"uint256"}]}
-
-# Compute a topic hash
-/home/ricmoo> ethers eval 'id("Transfer(address,address,uint256")'
-0xd99659a21de82e379975ce8df556f939a4ccb95e92144f38bb0dd35730ffcdd5
-
-# Create a random mnemonic
-/home/ricmoo> ethers eval 'Wallet.createRandom().mnemonic'
-useful pond inch knock ritual matrix giggle attend dilemma convince coach amazing

docs.wrm/cli/ethers-send.txt

@@ -1,44 +0,0 @@
-# Sending ether
-/home/ricmoo> ethers --account wallet.json send ricmoo.firefly.eth 0.123
-Password (wallet.json): ******
-Decrypting... 100%
-Transaction:
-  To:         0x8ba1f109551bD432803012645Ac136ddd64DBA72
-  From:       0xaB7C8803962c0f2F5BBBe3FA8bf41cd82AA1923C
-  Value:      0.123 ether
-  Nonce:      96
-  Data:       0x
-  Gas Limit:  21000
-  Gas Price:  1.2 gwei
-  Chain ID:   1
-  Network:    homestead
-Send Transaction? (y/N/a) y
-Response:
-  Hash:  0xc4adf8b379033d7ab679d199aa35e6ceee9a802ca5ab0656af067e911c4a589a
-
-
-# Sending a token (SAI)
-# NOTE: the contract address could be used instead but
-#       popular token contract addresses are also managed
-#       by ethers
-/home/ricmoo> ethers --account wallet.json send-token sai.tokens.ethers.eth ricmoo.firefly.eth 1.0
-Sending Tokens:
-  To:              0x8ba1f109551bD432803012645Ac136ddd64DBA72
-  Token Contract:  0x89d24A6b4CcB1B6fAA2625fE562bDD9a23260359
-  Value:           1.0
-Password (wallet.json): ******
-Decrypting... 100%
-Transaction:
-  To:         0x89d24A6b4CcB1B6fAA2625fE562bDD9a23260359
-  From:       0xaB7C8803962c0f2F5BBBe3FA8bf41cd82AA1923C
-  Value:      0.0 ether
-  Nonce:      95
-  Data:       0xa9059cbb0000000000000000000000008ba1f109551bd432803012645ac136ddd64dba720000000000000000000000000000000000000000000000000de0b6b3a7640000
-  Gas Limit:  37538
-  Gas Price:  1.0 gwei
-  Chain ID:   1
-  Network:    homestead
-Send Transaction? (y/N/a) y
-Response:
-  Hash:  0xd609ecb7e3b5e8d36fd781dffceede3975ece6774b6322ea56cf1e4d0a17e3a1
-

docs.wrm/cli/ethers-sign.txt

@@ -1,14 +0,0 @@
-/home/ethers> ethers --account wallet.json sign-message 'Hello World'
-Password (wallet.json): ******
-Decrypting... 100%
-Message:
-  Message:        "Hello World"
-  Message (hex):  0x48656c6c6f20576f726c64
-Sign Message? (y/N/a) y
-Signature
-  Flat:   0xca3f0b32a22a5ab97ca8be7e4a36b1e81d565c6822465d769f4faa4aa24539fb122ee5649c8a37c9f5fc8446593674159e3a7b039997cd6ee697a24b787b1a161b
-  r:      0xca3f0b32a22a5ab97ca8be7e4a36b1e81d565c6822465d769f4faa4aa24539fb
-  s:      0x122ee5649c8a37c9f5fc8446593674159e3a7b039997cd6ee697a24b787b1a16
-  vs:     0x122ee5649c8a37c9f5fc8446593674159e3a7b039997cd6ee697a24b787b1a16
-  v:      27
-  recid:  0

docs.wrm/cli/ethers.wrm

@@ -9,21 +9,157 @@ of the ethers utilities already exposed.
 
 _subsection: Help
 
-_code: ethers-help.txt
+_code: @lang<text>
+Usage:
+   ethers [ COMMAND ] [ ARGS ] [ OPTIONS ]
+
+COMMANDS (default: sandbox)
+   sandbox                    Run a REPL VM environment with ethers
+   init FILENAME              Create a new JSON wallet
+      [ --force ]                Overwrite any existing files
+   fund TARGET                Fund TARGET with testnet ether
+   info [ TARGET ... ]        Dump info for accounts, addresses and ENS names
+   send TARGET ETHER          Send ETHER ether to TARGET form accounts[0]
+      [ --allow-zero ]           Allow sending to the address zero
+      [ --data DATA ]            Include data in the transaction
+   sweep TARGET               Send all ether from accounts[0] to TARGET
+   sign-message MESSAGE       Sign a MESSAGE with accounts[0]
+      [ --hex ]                  The message content is hex encoded
+   eval CODE                  Run CODE in a VM with ethers
+   run FILENAME               Run FILENAME in a VM with ethers
+   wait HASH                  Wait for a transaction HASH to be mined
+   wrap-ether VALUE           Deposit VALUE into Wrapped Ether (WETH)
+   unwrap-ether VALUE         Withdraw VALUE from Wrapped Ether (WETH)
+   send-token TOKEN ADDRESS VALUE
+                              Send VALUE tokens (at TOKEN) to ADDRESS
+   compile FILENAME           Compiles a Solidity contract
+      [ --no-optimize ]          Do not optimize the compiled output
+      [ --warnings ]             Error on any warning
+   deploy FILENAME            Compile and deploy a Solidity contract
+      [ --no-optimize ]          Do not optimize the compiled output
+      [ --contract NAME ]        Specify the contract to deploy
+
+ACCOUNT OPTIONS
+  --account FILENAME          Load from a file (JSON, RAW or mnemonic)
+  --account RAW_KEY           Use a private key (insecure *)
+  --account 'MNEMONIC'        Use a mnemonic (insecure *)
+  --account -                 Use secure entry for a raw key or mnemonic
+  --account-void ADDRESS      Use an address as a void signer
+  --account-void ENS_NAME     Add the resolved address as a void signer
+  --account-rpc ADDRESS       Add the address from a JSON-RPC provider
+  --account-rpc INDEX         Add the index from a JSON-RPC provider
+  --mnemonic-password         Prompt for a password for mnemonics
+  --xxx-mnemonic-password     Prompt for a (experimental) hard password
+
+PROVIDER OPTIONS (default: all + homestead)
+  --alchemy                   Include Alchemy
+  --etherscan                 Include Etherscan
+  --infura                    Include INFURA
+  --nodesmith                 Include nodesmith
+  --rpc URL                   Include a custom JSON-RPC
+  --offline                   Dump signed transactions (no send)
+  --network NETWORK           Network to connect to (default: homestead)
+
+TRANSACTION OPTIONS (default: query network)
+  --gasPrice GWEI             Default gas price for transactions(in wei)
+  --gasLimit GAS              Default gas limit for transactions
+  --nonce NONCE               Initial nonce for the first transaction
+  --yes                       Always accept Siging and Sending
+
+OTHER OPTIONS
+  --wait                      Wait until transactions are mined
+  --debug                     Show stack traces for errors
+  --help                      Show this usage and exit
+  --version                   Show this version and exit
+
+(*) By including mnemonics or private keys on the command line they are
+    possibly readable by other users on your system and may get stored in
+    your bash history file. This is NOT recommended.
 
 _subsection: Examples
 
-_heading: Creating Wallets  @<cliex-init>
+_code: Creating New Wallets @lang<shell> @<cliex-init>
 
-_code: ethers-init.txt
+/home/ethers> ethers init wallet.json
+Creating a new JSON Wallet - wallet.json
+Keep this password and file SAFE!! If lost or forgotten
+it CANNOT be recovered, by ANYone, EVER.
+Choose a password: ******
+Confirm password: ******
+Encrypting... 100%
+New account address: 0x485bcC23ae2E5038ec7ec9b8DCB2A6A6291cC003
+Saved:               wallet.json
 
-_heading: Sending Ether and Tokens  @<cliex-send>
 
-_code: ethers-send.txt
+# If you are planning to try out the Ropsten testnet...
+/home/ethers> ethers --network ropsten fund 0x485bcC23ae2E5038ec7ec9b8DCB2A6A6291cC003
+Transaction Hash: 0x8dc55b8f8dc8076acded97f9e3ed7d6162460c0221e2769806006b6d7d1156e0
 
-_heading: Signing Messages  @<cliex-signing>
 
-_code: ethers-sign.txt
+_code: Sending Ether and Tokens  @<cliex-send> @lang<shell>
+
+# Sending ether
+/home/ricmoo> ethers --account wallet.json send ricmoo.firefly.eth 0.123
+Password (wallet.json): ******
+Decrypting... 100%
+Transaction:
+  To:         0x8ba1f109551bD432803012645Ac136ddd64DBA72
+  From:       0xaB7C8803962c0f2F5BBBe3FA8bf41cd82AA1923C
+  Value:      0.123 ether
+  Nonce:      96
+  Data:       0x
+  Gas Limit:  21000
+  Gas Price:  1.2 gwei
+  Chain ID:   1
+  Network:    homestead
+Send Transaction? (y/N/a) y
+Response:
+  Hash:  0xc4adf8b379033d7ab679d199aa35e6ceee9a802ca5ab0656af067e911c4a589a
+
+
+# Sending a token (SAI)
+# NOTE: the contract address could be used instead but
+#       popular token contract addresses are also managed
+#       by ethers
+/home/ricmoo> ethers --account wallet.json send-token sai.tokens.ethers.eth ricmoo.firefly.eth 1.0
+Sending Tokens:
+  To:              0x8ba1f109551bD432803012645Ac136ddd64DBA72
+  Token Contract:  0x89d24A6b4CcB1B6fAA2625fE562bDD9a23260359
+  Value:           1.0
+Password (wallet.json): ******
+Decrypting... 100%
+Transaction:
+  To:         0x89d24A6b4CcB1B6fAA2625fE562bDD9a23260359
+  From:       0xaB7C8803962c0f2F5BBBe3FA8bf41cd82AA1923C
+  Value:      0.0 ether
+  Nonce:      95
+  Data:       0xa9059cbb0000000000000000000000008ba1f109551bd432803012645ac136ddd64dba720000000000000000000000000000000000000000000000000de0b6b3a7640000
+  Gas Limit:  37538
+  Gas Price:  1.0 gwei
+  Chain ID:   1
+  Network:    homestead
+Send Transaction? (y/N/a) y
+Response:
+  Hash:  0xd609ecb7e3b5e8d36fd781dffceede3975ece6774b6322ea56cf1e4d0a17e3a1
+
+
+_code: Signing Messages  @<cliex-signing> @lang<shell>
+
+/home/ethers> ethers --account wallet.json sign-message 'Hello World'
+Password (wallet.json): ******
+Decrypting... 100%
+Message:
+  Message:        "Hello World"
+  Message (hex):  0x48656c6c6f20576f726c64
+Sign Message? (y/N/a) y
+Signature
+  Flat:   0xca3f0b32a22a5ab97ca8be7e4a36b1e81d565c6822465d769f4faa4aa24539fb122ee5649c8a37c9f5fc8446593674159e3a7b039997cd6ee697a24b787b1a161b
+  r:      0xca3f0b32a22a5ab97ca8be7e4a36b1e81d565c6822465d769f4faa4aa24539fb
+  s:      0x122ee5649c8a37c9f5fc8446593674159e3a7b039997cd6ee697a24b787b1a16
+  vs:     0x122ee5649c8a37c9f5fc8446593674159e3a7b039997cd6ee697a24b787b1a16
+  v:      27
+  recid:  0
+
 
 _heading: Scripting  @<cliex-scripting>
 
@@ -31,7 +167,50 @@ The ``eval`` command can be used to execute simple one-line scripts from
 the command line to be passed into other commands or stored in script
 environment variables.
 
-_code: ethers-script.txt
+_code: Get the formatted balance of an account  @lang<shell>
+/home/ethers> ethers --network ropsten \
+               --account wallet.json \
+               eval \
+               'accounts[0].getBalance().then(b => formatEther(b))'
+3.141592653589793238
+
+_code: Get the current block number  @lang<shell>
+/home/ethers> ethers --network rinkeby \
+               eval "provider.getBlockNumber()"
+5761009
+
+_code: Convert a Solidity signature to JSON  @lang<shell>
+/home/ethers> ethers eval 'utils.Fragment.from(
+               "function balanceOf(address) view returns (uint)"
+              ).format("json")' | json_pp
+{
+   "inputs" : [
+      {
+         "type" : "address",
+         "name" : "owner"
+      }
+   ],
+   "type" : "function",
+   "payble" : false,
+   "stateMutability" : "view",
+   "ouputs" : [
+      {
+         "type" : "uint256"
+      }
+   ],
+   "name" : "balanceOf",
+   "constant" : true
+}
+
+
+_code: Compute a topic hash  @lang<shell>
+/home/ricmoo> ethers eval 'id("Transfer(address,address,uint256")'
+0xd99659a21de82e379975ce8df556f939a4ccb95e92144f38bb0dd35730ffcdd5
+
+_code: Create a random mnemonic  @lang<shell>
+/home/ricmoo> ethers eval 'Wallet.createRandom().mnemonic'
+useful pond inch knock ritual matrix giggle attend dilemma convince coach amazing
+
 
 _heading: Using Mnemonics (with a password)  @<cliex-mnemonicpassword>
 
@@ -40,7 +219,16 @@ string (i.e. ``""``) as the password. If you have a password on your
 mnemonic, the ``-\-mnemonic-password`` will prompt for the password to
 use to decrypt the account.
 
-_code: ethers-mnemonic.txt
+_code: @lang<shell>
+
+/home/ricmoo> ethers --account mnemonic.txt --mnemonic-password
+Password (mnemonic): ******
+network: homestead (chainId: 1)
+homestead> accounts[0].getAddress()
+<Promise id=0 resolved>
+'0x6d3F723EC1B73141AA4aC248c3ab34A5a1DAD776'
+homestead>
+
 
 _heading: Using Mnemonics (with experimental memory-hard passwords)  @<cliex-mnemonicpassword-xxx>
 
@@ -50,7 +238,16 @@ the password through the [scrypt](link-wiki-scrypt)
 //password-based key derivation function// first, which is intentionally slow and makes
 a brute-force attack far more difficult.
 
-_code: ethers-mnemonic-hard.txt
+_code: @lang<shell>
+
+/home/ricmoo> ethers --account mnemonic.txt --xxx-mnemonic-password
+Password (mnemonic; experimental - hard): ******
+Decrypting... 100%
+network: homestead (chainId: 1)
+homestead> accounts[0].getAddress()
+<Promise id=0 resolved>
+'0x56FC8792cC17971C19bEC4Ced978beEA44711EeD'
+homestead>
 
 _warning: Note
 This is still an experimental feature (hence the ``xxx``).

docs.wrm/cli/plugin.txt

@@ -1,10 +0,0 @@
-/home/ethers> ethers --account wallet.json --yes send ricmoo.eth 1.0
-#  An Option ----------^                     ^   ^
-#    - name =  "account"                     |   |
-#    - value = "wallet.json"                 |   |
-#  A Flag -----------------------------------+   |
-#    - name  = "yes"                             |
-#    - value = true                              |
-#  Arguments ------------------------------------+
-#    - count = 3
-#    - [ "send", "ricmoo.eth", "1.0" ]

docs.wrm/cli/plugin.wrm

@@ -54,20 +54,20 @@ make sense.
 Once the prepareArguments is complete (the returned promise is resolved), the ``run``
 is called.
 
-_property: plugin.network => [[provider-network]]
+_property: plugin.network => [[providers-Network]]
 The network this plugin is running for.
 
-_property: plugin.provider => [[provider]]
+_property: plugin.provider => [[Provider]]
 The provider for this plugin is running for.
 
-_property: plugin.accounts => Array<[[signer]]>
+_property: plugin.accounts => Array<[[Signer]]>
 The accounts passed into the plugin using ``--account``,
 ``--account-rpc`` and ``--account-void`` which this plugin can use.
 
-_property: plugin.gasLimit => [[bignumber]]
+_property: plugin.gasLimit => [[BigNumber]]
 The gas limit this plugin should use. This is null if unspecified.
 
-_property: plugin.gasPrice => [[bignumber]]
+_property: plugin.gasPrice => [[BigNumber]]
 The gas price this plugin should use. This is null if unspecified.
 
 _property: plugin.nonce => number
@@ -114,7 +114,20 @@ _subsection: ArgParser @<cli-argparser> @SRC<cli:class.ArgParser>
 The **ArgParser** is used to parse a command line into flags, options
 and arguments.
 
-_code: plugin.txt
+_code: @lang<shell>
+
+/home/ethers> ethers --account wallet.json --yes send ricmoo.eth 1.0
+#  An Option ----------^                     ^   ^
+#    - name =  "account"                     |   |
+#    - value = "wallet.json"                 |   |
+#  A Flag -----------------------------------+   |
+#    - name  = "yes"                             |
+#    - value = true                              |
+#  Arguments ------------------------------------+
+#    - count = 3
+#    - [ "send", "ricmoo.eth", "1.0" ]
+
+_null:
 
 Flags are simple binary options (such as the ``--yes``), which are true if present
 otherwise false.

docs.wrm/cli/typescript-help.txt

@@ -1,19 +0,0 @@
-Usage:
-   ethers-ts FILENAME [ ... ] [ OPTIONS ]
-
-OPTIONS
-  --output FILENAME           Write the output to FILENAME (default: stdout)
-  --force                     Overwrite files if they already exist
-  --no-optimize               Do not run the solc optimizer
-  --no-bytecode               Do not include bytecode and Factory methods
-
-OTHER OPTIONS
-  --debug                     Show stack traces for errors
-  --help                      Show this usage and exit
-  --version                   Show this version and exit
-
-(*) By including mnemonics or private keys on the command line they are
-    possibly readable by other users on your system and may get stored in
-    your bash history file. This is NOT recommended.
-
-

docs.wrm/cli/typescript.wrm

@@ -2,7 +2,26 @@ _section: TypeScript
 
 _subsection: Help
 
-_code: typescript-help.txt
+_code: @lang<text>
+
+Usage:
+   ethers-ts FILENAME [ ... ] [ OPTIONS ]
+
+OPTIONS
+  --output FILENAME           Write the output to FILENAME (default: stdout)
+  --force                     Overwrite files if they already exist
+  --no-optimize               Do not run the solc optimizer
+  --no-bytecode               Do not include bytecode and Factory methods
+
+OTHER OPTIONS
+  --debug                     Show stack traces for errors
+  --help                      Show this usage and exit
+  --version                   Show this version and exit
+
+(*) By including mnemonics or private keys on the command line they are
+    possibly readable by other users on your system and may get stored in
+    your bash history file. This is NOT recommended.
+
 
 _subsection: Examples
 

docs.wrm/concepts/best-practices.wrm

@@ -0,0 +1,39 @@
+_section: Best Practices @<best-practices>
+
+_subsection: Network Changes
+
+Handling a change in the network (e.g. Ropsten vs Mainnet) is
+incredibly complex and a slight failure can at best make your
+application seem confusing and at worst cause the loss of funds,
+leak private data or misrepresent what an action performed.
+
+Luckily, standard users should likely never change their networks
+unless tricked to do so or they make a mistake.
+
+This is a problem you mainly need to worry about for developers, and
+most developers should understand the vast array of issues surrounding
+a network change during application operation and will understand the
+page reloading (which is already the default behaviour in many clients).
+
+So, the best practice when a network change occurs is to simply
+refresh the page. This should cause all your UI components to
+reset to a known-safe state, including any banners and warnings
+to your users if they are on an unsupported network.
+
+This can be acomplished by using the following function:
+
+_code: Automatically Refresh on Network Change @lang<script>
+
+// Force page refreshes on network changes
+{
+    // The "any" network will allow spontaneous network changes
+    const provider = new ethers.providers.Web3Provider(window.ethereum, "any");
+    provider.on("network", (newNetwork, oldNetwork) => {
+        // When a Provider makes its initial connection, it emits a "network"
+        // event with a null oldNetwork along with the newNetwork. So, if the
+        // oldNetwork exists, it represents a changing network
+        if (oldNetwork) {
+            window.location.reload();
+        }
+    });
+}

docs.wrm/concepts/events.wrm

@@ -5,3 +5,153 @@ Explain how topics and such work
 _subsection: Solidity Topics
 
 How to compute the topic...
+
+_subsection: Logs and Filtering
+
+Example hog logs are used.
+
+Link to provider.getLogs and contract.on
+
+_heading: Filters
+
+Filter are used as a way to query ... efficient, explain bloom filters lightly
+
+A filter may have up to 4 topic-sets, where each topic-set refers
+to a condition that must match the log topic in that position (i.e. each
+condition is ``AND``-ed together).
+
+If a topic-set is ``null``, a log topic in that position is not filtered
+at all and **any value** matches.
+
+If a topic-set is a single topic, a log topic in that position must match
+**that topic**.
+
+If a topic-set is an array of topics, a log topic in that position must
+match any **one** of topics (i.e. the topic in thie position are ``OR``-ed).
+
+
+_table: Example Log Matching @style<full>
+
+$TopicABaCD: **[** (topic[0] = A) **OR** (topic[0] = B) **]** **AND**
+             **[** (topic[1] = C) **OR** (topic[1] = D) **]**
+
+|  **Topic-Sets**           |  **Matching Logs**                    <<|
+|   [ A ]                   | topic[0] = A                          <<|
+|   [ A, null ]             |   ^                                     |
+|   [ null, B ]             | topic[1] = B                          <<|
+|   [ null, [ B ] ]         |   ^                                     |
+|   [ null, [ B ], null ]   |   ^                                     |
+|   [ A, B ]                | (topic[0] = A) **AND** (topic[1] = B) <<|
+|   [ A, [ B ] ]            |   ^                                     |
+|   [ A, [ B ], null ]      |   ^                                     |
+|   [ [ A, B ] ]            | (topic[0] = A) **OR** (topic[0] = B)  <<|
+|   [ [ A, B ], null ]      |   ^                                     |
+|   [ [ A, B ], [ C, D ] ]  | $TopicABaCD                       <<|
+
+
+_code: ERC-20 Transfer Filter Examples @lang<javascript>
+
+// <hide>
+const tokenAddress = ethers.constants.AddressZero;
+const myAddress = ethers.constants.AddressZero;
+const myOtherAddress = ethers.constants.AddressZero;
+const id = ethers.utils.id;
+const hexZeroPad = ethers.utils.hexZeroPad;
+// </hide>
+
+// Short example of manually creating filters for an ERC-20
+// Transfer event.
+//
+// Most users should generally use the Contract API to
+// compute filters, as it is much simpler, but this is
+// provided as an illustration for those curious. See
+// below for examples of the equivalent Contract API.
+
+// ERC-20:
+//   Transfer(address indexed src, address indexed dst, uint val)
+//
+// -------------------^
+// ----------------------------------------^
+//
+// Notice that only *src* and *dst* are *indexed*, so ONLY they
+// qualify for filtering.
+//
+// Also, note that in Solidity an Event uses the first topic to
+// identify the Event name; for Transfer this will be:
+//   id("Transfer(address,address,uint256)")
+//
+// Other Notes:
+//  - A topic must be 32 bytes; so shorter types must be padded
+
+// List all token transfers  *from*  myAddress
+filter = {
+    address: tokenAddress,
+    topics: [
+        id("Transfer(address,address,uint256)"),
+        hexZeroPad(myAddress, 32)
+    ]
+}
+
+// List all token transfers  *to*  myAddress:
+filter = {
+    address: tokenAddress,
+    topics: [
+        id("Transfer(address,address,uint256)"),
+        null,
+        hexZeroPad(myAddress, 32)
+    ]
+}
+
+// List all token transfers  *to*  myAddress or myOtherAddress:
+filter = {
+    address: tokenAddress,
+    topics: [
+        id("Transfer(address,address,uint256)"),
+        null,
+        [
+            hexZeroPad(myAddress, 32),
+            hexZeroPad(myOtherAddress, 32),
+        ]
+    ]
+}
+
+_null:
+
+To simplify life, ..., explain here, the contract API
+
+
+_code: ERC-20 Contract Filter Examples @lang<javascript>
+
+// <hide>
+const tokenAddress = "0x6B175474E89094C44Da98b954EedeAC495271d0F"; // DAI
+const myAddress = "0x8ba1f109551bD432803012645Ac136ddd64DBA72";
+const otherAddress = "0xEA517D5a070e6705Cc5467858681Ed953d285Eb9";
+const provider = ethers.getDefaultProvider();
+const Contract = ethers.Contract;
+// </hide>
+
+const abi = [
+  "event Transfer(address indexed src, address indexed dst, uint val)"
+];
+
+const contract = new Contract(tokenAddress, abi, provider);
+
+// List all token transfers *from* myAddress
+contract.filters.Transfer(myAddress)
+//!
+
+// List all token transfers *to* myAddress:
+contract.filters.Transfer(null, myAddress)
+//!
+
+// List all token transfers *from* myAddress *to* otherAddress:
+contract.filters.Transfer(myAddress, otherAddress)
+//!
+
+// List all token transfers *to* myAddress OR otherAddress:
+contract.filters.Transfer(null, [ myAddress, otherAddress ])
+//!
+
+_heading: Other Things? TODO
+
+Explain what happens to strings and bytes, how to filter and retain the value

docs.wrm/concepts/index.wrm

@@ -1,9 +1,13 @@
-_section: Concepts
+_section: Ethereum Basics
 
 This is a very breif overview of some aspects of //Ethereum//
 and blockchains which developers can make use of or should
 be aware of.
 
+This section is fairly sparse at the moment, but will be expanded
+as time goes on.
+
 _toc:
     events
     gas
+    security

docs.wrm/concepts/security/index.wrm

@@ -0,0 +1,85 @@
+_section: Security @<security>
+
+_subsection: Key Derivation Functions @<security--pbkdf>
+
+This is not specific to Ethereum, but is a useful technique
+to understand and has some implications on User Experience.
+
+Many people are concerned that encrypting and decrypting an
+Ethereum wallet is quite slow and can take quite some time.
+It is important to understand this is intentional and provides
+much stronger security.
+
+The algorithm usually used for this process is [scrypt](link-wiki-scrypt),
+which is a memory and CPU intensive algorithm which computes
+a key (fixed-length psudo-random series of bytes) for a given
+password.
+
+
+_heading: Why does it take so long?
+
+The goal is to use as much CPU and memory as possible during
+this algorithm, so that a single computer can only compute a
+very small number of results for some fixed amount of time. To
+scale up an attack, the attacker requires additional compuers,
+increasing the cost to [brute-force attack](link-wiki-bruteforce)
+to guess the password.
+
+For example, if a user knows their correct password, this process
+may take 10 seconds for them to unlock their own wallet and proceed.
+
+But since an attacker does not know the password, they must guess; and
+each guess also requires 10 seconds. So, if they wish to try guessing 1
+million passwords, their computer would be completely tied up for 10
+million seconds, or around 115 days.
+
+Without using an algorithm like this, a user would be able
+to log in instantly, however, 1 million passwords would only
+take a few seconds to attempt. Even secure passwords would
+likely be broken within a short period of time. There is no way
+the algorithm can be faster for a legitimate user without also
+being faster for an attacker.
+
+_heading: Mitigating the User Experience
+
+Rather than reducing the security (see below), a better practice is to make
+the user feel better about waiting. The Ethers encryption and decryption
+API allows the developer to incorporate a progress bar, by passing in a
+progress callback which will be periodically called with a number between
+0 and 1 indication percent completion.
+
+In general a progress bar makes the experience feel faster, as well as
+more comfortable since there is a clear indication how much (relative) time
+is remaining. Additionally, using language like //"decrpyting..."// in
+a progress bar makes a user feel like there time is not being //needlessly//
+wasted.
+
+_heading: Work-Arounds (not recommended)
+
+There are ways to reduce the time required to decrypt an Ethereum JSON
+Wallet, but please keep in mind that doing so **discards nearly all security**
+on that wallet.
+
+The scrypt algorithm is designed to be tuned. The main purpose of this is
+to increase the difficulty as time goes on and computers get faster, but
+it can also be tuned down in situations where the security is less important.
+
+_code: @LANG<javascript>
+
+// Our wallet object
+const wallet = Wallet.createRandom();
+
+// The password to encrypt with
+const password = "password123";
+
+// WARNING: Doing this substantially reduces the security
+//          of the wallet. This is highly NOT recommended.
+
+// We override the default scrypt.N value, which is used
+// to indicate the difficulty to crack this wallet.
+const json = wallet.encrypt(password, {
+  scrypt: {
+    // The number must be a power of 2 (default: 131072)
+    N: 64
+  }
+});

docs.wrm/config.js

@@ -115,37 +115,89 @@ const getSourceUrl = (function(path, include, exclude) {
     }
 })("../packages/", new RegExp("packages/.*/src.ts/.*\.ts$"), new RegExp("/node_modules/|src.ts/.*browser.*"));
 
+function codeContextify(context) {
+    const { inspect } = require("util");
+    const ethers = context.require("./packages/ethers");
+
+    context.ethers = ethers;
+    context.BigNumber = ethers.BigNumber;
+    context.constants = ethers.constants;
+    context.utils = ethers.utils;
+    context.arrayify = ethers.utils.arrayify;
+    context.hexlify = ethers.utils.hexlify;
+    context.hexValue = ethers.utils.hexValue;
+    context.Wallet = ethers.Wallet;
+    context.provider = new ethers.providers.InfuraProvider();
+
+    context.BigNumber.prototype[inspect.custom] = function(depth, options) {
+        return `{ BigNumber: ${JSON.stringify(this.toString()) } }`;
+    }
+
+
+    context._inspect = function(value, depth) {
+        if (value && value.constructor && value.constructor.name === "Uint8Array") {
+            return `Uint8Array [ ${ Array.prototype.join.call(value, ", ") } ]`;
+        }
+
+        //return JSON.stringify(value);
+        return inspect(value, {
+            compact: false,
+            breakLength: Infinity,
+            sorted: true,
+        });
+    }
+}
+
+
 module.exports = {
   title: "ethers",
   subtitle: "v5.0-beta",
   logo: "logo.svg",
 
-  link: "https://docs-beta.ethers.io",
+  prefix: "/v5",
+
+  link: "https:/\/docs-beta.ethers.io",
+  copyright: "The content of this site is licensed under the [Creative Commons License](https:/\/choosealicense.com/licenses/cc-by-4.0/). Generated on &$now;.",
 
   markdown: {
       "banner": "-----\n\nDocumentation: [html](https://docs-beta.ethers.io/)\n\n-----\n\n"
   },
 
+  codeContextify: codeContextify,
+
   getSourceUrl: getSourceUrl,
 
-  externalLinks: {
-      "link-alchemy": "https:/\/alchemyapi.io",
-      "link-cloudflare": "https:/\/developers.cloudflare.com/distributed-web/ethereum-gateway/",
-      "link-ethereum": "https:/\/ethereumorg",
-      "link-etherscan": "https:/\/etherscan.io",
-      "link-etherscan-api": "https:/\/etherscan.io/apis",
-      "link-flatworm": "https:/\/github.com/ricmoo/flatworm",
-      "link-geth": "https:/\/geth.ethereum.org",
-      "link-infura": "https:/\/infura.io",
-      "link-ledger": "https:/\/www.ledger.com",
-      "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/",
+  codeRoot: "../",
 
-      "link-legacy-docs3": "https:/\/docs.ethers.io/ethers.js/v3.0/html/",
-      "link-legacy-docs4": "https:/\/docs.ethers.io/ethers.js",
+  externalLinks: {
+      "link-alchemy": { name: "Alchemy", url: "https:/\/alchemyapi.io" },
+      "link-cloudflare": { name: "Cloudflare", url: "https:/\/developers.cloudflare.com/distributed-web/ethereum-gateway/" },
+      "link-ens": { name: "ENS", url: "https:/\/ens.domains/" },
+      "link-ethereum": { name: "Ethereum", url: "https:/\/ethereumorg" },
+      "link-etherscan": { name: "Etherscan", url: "https:/\/etherscan.io" },
+      "link-etherscan-api": "https:/\/etherscan.io/apis",
+      "link-flatworm": { name: "Flatworm", url: "https:/\/github.com/ricmoo/flatworm" },
+      "link-geth": { name: "Geth", url: "https:/\/geth.ethereum.org" },
+      "link-infura": { name: "INFURA", url: "https:/\/infura.io" },
+      "link-ledger": "https:/\/www.ledger.com",
+      "link-metamask": { name: "Metamask", url: "https:/\/metamask.io/" },
+      "link-parity": { name: "Parity", url: "https:/\/www.parity.io" },
+      "link-rtd": "https:/\/github.com/readthedocs/sphinx_rtd_theme",
+      "link-semver": { name: "semver", url: "https:/\/semver.org" },
+      "link-solidity": { name: "Solidity" , url: "https:/\/solidity.readthedocs.io/en/v0.6.2/" },
+      "link-sphinx": { name: "Sphinx", url: "https:/\/www.sphinx-doc.org/" },
+
+      "link-json-rpc": "https:/\/github.com/ethereum/wiki/wiki/JSON-RPC",
+      "link-web3-send": "https:/\/github.com/ethereum/web3.js/blob/1.x/packages/web3-providers-http/types/index.d.ts#L57",
+      "link-parity-trace": "https:/\/openethereum.github.io/wiki/JSONRPC-trace-module",
+      "link-parity-rpc": "https:/\/openethereum.github.io/wiki/JSONRPC",
+      "link-geth-debug": "https:/\/github.com/ethereum/go-ethereum/wiki/Management-APIs#debug",
+      "link-geth-rpc": "https:/\/github.com/ethereum/go-ethereum/wiki/Management-APIs",
+
+      "link-legacy-docs3": "https:/\/docs.ethers.io/v3/",
+      "link-legacy-docs4": "https:/\/docs.ethers.io/v4/",
+
+      "link-infura-secret": "https:/\/infura.io/docs/gettingStarted/authentication",
 
       "link-web3": "https:/\/github.com/ethereum/web3.js",
       "link-web3-http": "https:/\/github.com/ethereum/web3.js/tree/1.x/packages/web3-providers-http",
@@ -153,11 +205,12 @@ module.exports = {
       "link-web3-ws": "https:/\/github.com/ethereum/web3.js/tree/1.x/packages/web3-providers-ws",
 
       "link-solc-output": "https:/\/solidity.readthedocs.io/en/v0.6.0/using-the-compiler.html#output-description",
+      "link-bip39-wordlists": "https:/\/github.com/bitcoin/bips/blob/master/bip-0039/bip-0039-wordlists.md",
 
       "link-icap": "https:/\/github.com/ethereum/wiki/wiki/Inter-exchange-Client-Address-Protocol-%28ICAP%29",
       "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-mit": { name: "MIT License", url: "https:/\/en.m.wikipedia.org/wiki/MIT_License" },
+      "link-namehash": { name: "namehash", url: "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/",
@@ -168,13 +221,15 @@ module.exports = {
 
       "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-eip-609": { name: "EIP-609", url: "https:/\/eips.ethereum.org/EIPS/eip-609" },
+      "link-eip-1014": { name: "EIP-1014", url: "https:/\/eips.ethereum.org/EIPS/eip-1014" },
+      "link-eip-1193": { name: "EIP-1193", url: "https:/\/eips.ethereum.org/EIPS/eip-1193" },
+      "link-eip-2098": { name: "EIP-2098", url: "https:/\/eips.ethereum.org/EIPS/eip-2098" },
+      "link-bip-39": { name: "BIP-39", url: "https:/\/en.bitcoin.it/wiki/BIP_0039" },
+      "link-bip-32": { name: "BIP-32", url: "https:/\/github.com/bitcoin/bips/blob/master/bip-0032.mediawiki" },
 
       "link-npm-elliptic": { name: "elliptic", url: "https:/\/www.npmjs.com/package/elliptic" },
+      "link-npm-events": { name: "EventEmitter", url: "https:/\/nodejs.org/dist/latest-v13.x/docs/api/events.html#events_class_eventemitter" },
       "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",
 
@@ -189,7 +244,9 @@ module.exports = {
       "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-bruteforce": "https:/\/en.wikipedia.org/wiki/Brute-force_attack",
       "link-wiki-cryptographichash": "https:/\/en.wikipedia.org/wiki/Cryptographic_hash_function",
+      "link-wiki-ecrecover": { name: "ECDSA Public Key Recovery", url: "https:/\/en.wikipedia.org/wiki/Elliptic_Curve_Digital_Signature_Algorithm#Public_key_recovery" },
       "link-wiki-homoglyph": "https:/\/en.wikipedia.org/wiki/IDN_homograph_attack",
       "link-wiki-hmac": "https:/\/en.wikipedia.org/wiki/HMAC",
       "link-wiki-iban": "https:/\/en.wikipedia.org/wiki/International_Bank_Account_Number",
@@ -205,5 +262,5 @@ module.exports = {
       "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

@@ -27,7 +27,48 @@ have a public discussion and figure out the best way to address to problem/featu
 
 _subsection: Building
 
-use npm run auto-build
+If you wish to modify the source code, there are a few steps involved in setting up
+your environment.
 
-use npm run update-version
+_code: Preparing the Package @lang<shell>
+
+# Clone the REPO
+/home/ricmoo> git clone git@github.com:ethers-io/ethers.js.git
+/home/ricmoo> cd ethers.js
+
+# Install the base dependencies
+/home/ricmoo/ethers.js> npm install
+
+# Install each module's dependencies and link the libraries
+# internally, so they reference each other
+/home/ricmoo/ethers.js> npm run bootstrap
+
+
+_code: Watching and Building @lang<shell>
+
+# Begin watching the files and re-building whenever they change
+/home/ricmoo/ethers.js> npm run auto-build
+
+
+# Sometimes the issue only affects the ESM modules
+/home/ricmoo/ethers.js> npm run auto-build-esm
+
+
+# Or if you only need to run a single build
+/home/ricmoo/ethers.js> npm run _build-cjs
+/home/ricmoo/ethers.js> npm run _build-esm
+
+
+_code: Testing @lang<shell>
+
+# Rebuilds all files and bundles testcases up for testing
+/home/ricmoo/ethers.js> npm test
+
+# Often you don't need the full CI experience
+/home/ricmoo/ethers.js> npm run _test-node
+
+
+_code: Preparing the Distribution @lang<shell>
+
+/home/ricmoo/ethers.js> npm run update-version
 

docs.wrm/documentation.wrm

@@ -0,0 +1,469 @@
+_section: Flatworm Docs
+
+The //Flatworm Docs// rendering engine is designed to be **very**
+simple, but provide enough formatting necessary for documenting
+JavaScript libraries.
+
+A lot of its inspiration came from [Read the Docs](link-rtd) and
+the [Sphinx](link-sphinx) project.
+
+
+_subsection: Fragments @<flatworm-fragments>
+
+Each page is made up of fragments. A fragment is a [directive](flatworm-directive),
+with an value and optional //link//, //extensions// and a body.
+
+Many directives support [markdown](flatworm-markdown) in their value and body.
+
+A fragment's body continues until another fragment is encountered.
+
+
+_heading: Directive Format
+
+_code: @lang<text>
+
+\_DIRECTIVE: VALUE @<LINK> @EXTENSION<PARAMETER>
+BODY
+
+MORE BODY
+
+DIRECTIVE:  The directive name
+VALUE:      Optional; the value to pass to the directive
+LINK:       Optional; a name for internal linking
+EXTENSION:  Optional; extended directive functionality
+PARAMETER:  Optional; value to pass to extended directive functions
+BODY:       Optional; the directive body (certain directives only)
+
+
+_heading: Flatworm Directives @<flatworm-directive>
+
+_definition: **_section:** //TITLE//
+A //section// has its **TITLE** in an H1 font. Sections are linked
+to in //Table of Contents// and have a dividing line drawn above
+them.
+
+The body supports markdown.
+
+There should only be one ``_section:`` per page.
+
+**Extensions:** [@inherit](flatworm--ext-inherit), [@src](flatworm--ext-src), [@nav](flatworm--ext-nav), [@note](flatworm--ext-note)
+
+_definition: **_subsection:** //TITLE//
+A //subsection// has its **TITLE** in an H2 font. Subsections are linked
+to in //Table of Contents// and have a dividing line drawn above
+them.
+
+The title and body support markdown.
+
+**Extensions:** [@inherit](flatworm--ext-inherit), [@src](flatworm--ext-src), [@note](flatworm--ext-note)
+
+_definition: **_heading:** //TITLE//
+A //heading// has its **TITLE** in an H3 font.
+
+The title and body support markdown.
+
+**Extensions:** [@inherit](flatworm--ext-inherit), [@src](flatworm--ext-src), [@note](flatworm--ext-note)
+
+_definition: **_definition:** //TERM//
+A //definition// has its **TERM** in normal text and the body is
+indented.
+
+The title and body support markdown.
+
+_definition: **_property:** //SIGNATURE//
+A //property// has its JavaScript **SIGNATURE** formatted.
+
+The body supports markdown and the return portion of the signature
+support markdown links.
+
+**Extensions:** [@src](flatworm--ext-src)
+
+_definition: **_note:** //BANNER//
+A //note// is placed in a blue bordered-box to draw attention to it.
+
+The body supports markdown.
+
+_definition: **_warning:** //BANNER//
+A //warning// is placed in an orange bordered-box to draw attention to it.
+
+The body supports markdown.
+
+_definition: **_code:** //CAPTION//
+Creates a [Code](flatworm--code) block.
+
+The body does **not** support markdown, and will be output exactly as
+is, with the exception of [Code Evaluation](flatworm--code-eval).
+
+If a line begins with a ``"_"``, it should be escaped with a ``"\\"``.
+
+**Extensions:** [@lang](flatworm--ext-lang)
+
+_definition: **_table:** //FOOTER//
+
+Creates a [Table](flatworm--table) structured according to the body.
+
+Each cell support and variables support markdown.
+
+**Extensions:** [@style](flatworm--ext-style)
+
+_definition: **_toc:**
+A //toc// injects a Table of Contents, loading each line of the
+body as a filename and recursively loads the //toc// if present,
+otherwise all the //sections// and //subsections//.
+
+The body does **not** support markdown, as it is interpreted as
+a list of files and directories to process.
+
+_definition: **_null:**
+A //null// is used to terminated a directive. For example, after
+a //definition//, the bodies are indented, so a //null// can be
+used to reset the indentation.
+
+The body supports markdown.
+
+_code: Example @lang<text>
+
+\_section: Hello World @<link-main>
+Body for section...
+
+
+\_subsection: Some Example @<link-secondary>
+Body for subsection...
+
+
+\_heading: Large Bold Text @<link-here>
+Body for heading...
+
+
+\_definition: Flatworm
+A phylum of relatively **simple** bilaterian, unsegmented,
+soft-bodied invertebrates.
+
+
+\_property: String.fromCharCode(code) => string
+Returns a string created from //code//, a sequence of
+UTF-16 code units.
+
+
+\_code: heading
+
+// Some code goes here
+while(1);
+
+
+\_table: Table Footer
+
+|  **Name**  |  **Color**  |
+|   Apple    |   Red       |
+|   Banana   |   Yellow    |
+|   Grape    |   Purple    |
+
+
+\_toc:
+    some-file
+    some-directory
+
+
+\_note: Title
+This is placed in a blue box.
+
+
+\_warning: Title
+This is placed in an orange box.
+
+
+\_null:
+This breaks out of a directive. For example, to end a
+
+
+_subsection: Markdown @<flatworm-markdown>
+
+The markdown is simple and does not have the flexibility of
+other dialects, but allows for **bold**, //italic//,
+__underlined__, ``monospaced``, super^^script^^ and ~~strike~~
+text, supporting [links](flatworm-markdown) and lists.
+
+Lists are rendered as blocks of a body, so cannot be used within
+a title or within another list.
+
+_code: @lang<text>
+
+**bold text**
+
+//italic text//
+
+__underlined text__
+
+``monospace code``
+
+^^superscript text^^
+
+~~strikeout text~~
+
+- This is a list
+- With bullet points
+- With a total of three items
+
+This is a [Link to Ethereum](https://ethereum.org) and this
+is an [Internal Link](some-link).
+
+This is a self-titled link [[https://ethereumorg]] and this
+[[some-link]] will use the title from its directives value.
+
+
+_subsection: Code @<flatworm--code>
+
+The code directive creates a monospace, contained block useful
+for displaying code samples.
+
+_heading: JavaScript Evaluation @<flatworm--code-eval>
+
+For JavaScript files, the file is executed with some simple substitution.
+
+A bare ``\/\/!`` on a line is replaced with the result of the last
+statement. Building will fail if an error is thrown.
+
+A bare ``\/\/!error`` is replaced with the throw error. Building will
+fail if an error is not thrown.
+
+Also any code included between the lines **``\/\/ <hide>``** and
+**``\/\/ </hide>``** will be omitted from the output, which can be used
+to setup variables.
+
+_code: Code Evaluation Example @lang<text>
+
+\_code: Result of Code Example  @lang<javascript>
+
+// <hide>
+const url = require("url");
+// </hide>
+
+url.parse("https://www.ricmoo.com/").protocol
+//!
+
+url.parse(45)
+//! error
+
+// You want to assign (doesn't emit eval) AND display the value
+const foo = 4 + 5;
+// <hide>
+foo
+// </hide>
+//!
+
+
+_code: Result of Code Example  @lang<javascript>
+
+// <hide>
+const url = require("url");
+// </hide>
+
+url.parse("https://www.ricmoo.com/").protocol
+//!
+
+url.parse(45)
+//! error
+
+// You want to assign (doesn't emit eval) AND display the value
+const foo = 4 + 5;
+// <hide>
+foo
+// </hide>
+//!
+
+
+_heading: Languages
+
+The language can be specified using the [@lang extension](flatworm--ext-lang).
+
+_table:
+
+|  **Language**  |                             **Notes**                                    |
+|   javascript   | Syntax highlights and [evaluates](flatworm--code-eval) the JavaScipt     |
+|   script       | Same as ``javascript``, but does not evaluate the results                |
+|   shell        | Shell scripts or command-line                                            |
+|   text         | Plain text with no syntax highlighting                                   |
+
+_subsection: Tables @<flatworm--table>
+
+The table directive consumes the entire body up until the next
+directive. To terminate a table early to begin a text block,
+use a **_null:** directive.
+
+Each line of the body should be [Row Data](flatworm--table-row) or a
+[Variable Declaration](flatworm--table-variable) (or continuation of
+a //Variable Declaration//). Blank lines are ignored.
+
+_heading: Row Data @<flatworm--table-row>
+
+Each **Row Data** line must begin and end with a **``"|"``**, with each
+gap representing the cell data, [alignment](flatworm--table-alignment)
+with optional [column and row spanning](flatworm--table-spanning).
+
+
+_heading: Alignment @<flatworm--table-alignment>
+
+The alignment for a cell is determined by the whitespace surrounding the
+cell data.
+
+_table: Alignment Conditions (higher precedence listed first)
+
+|   **Alignment**   |                    **Whitespace**                     |
+|    //Left//       | 1 or fewer spaces before the content                  |
+|    //Right//      | 1 or fewer spaces after the content                   |
+|    //Center//     | 2 or more space **both** before and after the content |
+
+
+_code: Alignment Example @lang<text>
+
+\_table: Result of Alignment Example @style<compact>
+
+|   center    |
+
+| left        |
+|left         |
+
+|       right |
+|        right|
+
+_table: Result of Alignment Example @style<compact>
+
+|   center    |
+
+| left        |
+|left         |
+
+|       right |
+|        right|
+
+
+_heading: Row and Column Spanning @<flatworm--table-spanning>
+
+A column may end its content with any number of **``"<"``** which indicates
+how many //additional// columns to extend into.
+
+If the cell content contains only a **``"^"``**, then the row above is
+extended into this cell (into the same number of columns).
+
+_code: Cell Spanning Example @lang<text>
+
+\_table: Result of Cell Spanning Example @style<compact>
+
+|  (1x1)  |  (1x2)      <|  (2x1)  |
+|  (2x2)      <|  (2x1)  |    ^    |
+|    ^         |    ^    |  (1x1)  |
+
+_table: Result of Cell Spanning Example @style<compact>
+
+|  (1x1)  |  (1x2)      <|  (2x1)  |
+|  (2x2)      <|  (2x1)  |    ^    |
+|    ^         |    ^    |  (1x1)  |
+
+
+_heading: Styles  @<flatworm--table-style>
+
+The [@style extension](flatworm--ext-style) for a table can be used to control its
+appearance.
+
+_table:
+
+|   **Name**    |    **Width**    |  **Columns**       |
+|  //minimal//  |   minimum size  |    best fit        |
+|  //compact//  |     40%         |    evenly spaced   |
+|   //wide//    |     67%         |    evenly spaced   |
+|   //full//    |    100%         |    evenly spaced   |
+
+
+_heading: Variables  @<flatworm--table-variable>
+
+Often the layout of a table is easier to express and maintain without
+uneven or changing content within it. So the content can be defined
+separately within a table directive using **variables**. A varaible
+name must being with a letter and must only contain letters and numbers.
+
+Variables are also useful when content is repeated throughout a table.
+
+A variable is declared by starting a line with ``"$NAME:"``, which
+consumes all lines until the next variable declaration or until the
+next table row line.
+
+A variable name must start with a letter and may consist of letters and
+numbers. (i.e. ``/[a-z][a-z0-9]*/i``)
+
+_code: Variables Example @lang<text>
+
+\_table: Result of Variables Example
+
+$Yes:    This option is supported.
+$No:     This option is **not** supported
+$bottom: This just represents an example of
+         what is possible. Notice that variable
+         content can span multiple lines.
+
+|  **Feature**     |  **Supported**  |
+|  Dancing Monkey  |      $Yes       |
+|  Singing Turtle  |      $No        |
+|  Newt Hair       |      $Yes       |
+|        $bottom                    <|
+
+_table: Result of Variables Example
+
+$Yes: This option is supported.
+$No:  This option is **not** supported.
+$bottom: This just represents an example of
+         what is possible. Notice that variable
+         content can span multiple lines.
+
+|  **Feature**     |  **Supported**  |
+|  Dancing Monkey  |      $Yes       |
+|  Singing Turtle  |      $No        |
+|  Newt Hair       |      $Yes       |
+|        $bottom                    <|
+
+
+_subsection: Configuration @<flatworm-config>
+
+Configuration is optional (but highly recommended) and may be either
+a simple JSON file (config.json) or a JS file (config.js) placed in
+the top  of the source folder.
+
+TODO:  example JSON and example JS
+
+
+_subsection: Extensions @<flatworm-extensions>
+
+_heading: @inherit\< //markdown// >  @<flatworm--ext-inherit>
+
+Adds an inherits description to a directive. The //markdown// may contain links.
+
+
+_heading: @lang\< //text// >  @<flatworm--ext-lang>
+
+Set the language a [code directive](flatworm--code) should be
+syntax-highlighted for. If "javascript", the code will be evaluated.
+
+
+_heading: @nav\< //text// >  @<flatworm--ext-nav>
+
+Sets the name in the breadcrumbs when not the current node.
+
+
+_heading: @note\<// markdown// >  @<flatworm--ext-note>
+
+Adds a note to a directive. The //markdown// may contain links. If the directive
+already has an @INHERIT extension, that will be used instead and the @NOTE will
+be ignored.
+
+
+_heading: @src\< //key// >  @<flatworm--ext-src>
+
+Calls the configuration ``getSourceUrl(key, VALUE)`` to get a URL which
+will be linked to by a link next to the //directive//.
+
+This extended directive function requires an advanced ``config.js`` [[flatworm-config]]
+file since it requires a JavaScript function.
+
+
+_heading: @style\< //text// >  @<flatworm--ext-style>
+
+The [Table Style](flatworm--table-style) to use for a table directive.

docs.wrm/documentation/examples.txt

@@ -1,30 +0,0 @@
-_section: Hello World @<link-to-this-section>
-
-_subsection: Some Example @<link-to-this-subsection>
-
-_heading: Large Bold Text @<link-to-this-heading>
-
-_definition: Flatworm
-A phylum of relatively **simple** bilaterian, unsegmented,
-soft-bodied invertebrates.
-
-_property: String.fromCharCode(code) => string
-Returns a string created from //code//, a sequence of
-UTF-16 code units.
-
-_code: filename.js
-
-_toc:
-    some-file
-    some-directory
-
-_definition and reset the indentation.
-
-_note: Title
-This is placed in a blue box.
-
-_warning: Title
-This is placed in an orange box.
-
-_null:
-This breaks out of a directive. For example, to end a

docs.wrm/documentation/fragment.txt

@@ -1,9 +0,0 @@
-_DIRECTIVE: VALUE @<LINK> @META<PARAMETER>
-BODY
-
-DIRECTIVE:  The directive name
-VALUE:      Optional; the value to pass to the directive
-LINK:       Optional; a name for internal linking
-META:       Optional; extended directive functionality
-PARAMETER:  Optional; value to pass to extended directive functions
-BODY:       Optional; the directive body (certain directives only)

docs.wrm/documentation/index.wrm

@@ -1,134 +0,0 @@
-_section: Flatworm Docs
-
-The //Flatworm Docs// rendering script is designed to be **very**
-simple, but provide enough formatting necessary for documenting
-JavaScript libraries.
-
-A lot of its inspiration came from [Read the Docs](link-rtd) and
-the [Sphinx](link-sphinx) project.
-
-
-_subsection: Fragments @<flatworm-fragments>
-
-Flatworm Docs are made up of fragments. A fragment is either a lone
-body of [markdown](flatworm-markdown) text, or a
-[directive](flatworm-directive) for specialized formatting, which may
-itself have body.
-
-
-_heading: Directive Format
-
-_code: fragment.txt
-
-
-_heading: Flatworm Directives @<flatworm-directive>
-
-_definition: **_section:** //TITLE//
-A //section// has its **TITLE** in an H1 font. Sections are linked
-to in //Table of Contents// and have a dividing line drawn above
-them. If an option is specified, it is avaialble as a name for
-intern linking. There should only be one ``_section:`` per page.
-
-_definition: **_subsection:** //TITLE//
-A //subsection// has its **TITLE** in an H2 font. Subsections are linked
-to in //Table of Contents// and have a dividing line drawn above
-them. If an option is specified, it is avaialble as a name for
-internal linking.
-
-_definition: **_heading:** //TITLE//
-A //heading// has its **TITLE** in an H3 font. If an option is specified,
-it is available as a name for internal linking.
-
-_definition: **_definition:** //TERM//
-A //definition// has its **TERM** bolded and the markdown body is
-indented.
-
-_definition: **_property:** //SIGNATURE//
-A //property// has its JavaScript **SIGNATURE** formatted and the
-markdown body is indented.
-
-_definition: **_note:** //TITLE//
-A //note// is placed in a blue bordered-box to draw attention to it.
-
-_definition: **_warning:** //TITLE//
-A //warning// is placed in an orange bordered-box to draw attention to it.
-
-_definition: **_code:** //FILENAME//
-A //code// reads the **FILENAME** and depending on the extension
-adjusts it.
-
-For JavaScript files, the file is executed, with ``\/\/!`` replaced
-with the result of the last statement and ``\/\/!error`` is replaced
-with the throw error. If the error state does not agree, rendering
-fails.
-
-_definition: **_toc:**
-A //toc// injects a Table of Contents, loading each line of the
-body as a filename and recursively loads the //toc// if present,
-otherwise all the //sections// and //subsections//.
-
-_definition: **_null:**
-A //null// is used to terminated a directive. For example, after
-a //definition//, the bodies are indented, so a //null// can be
-used to reset the indentation.
-
-
-_heading: Examples @<>
-
-_code: examples.txt
-
-_subsection: Markdown @<flatworm-markdown>
-
-The markdown is simple and does not have the flexibility of
-other dialects, but allows for **bold**, //italic//,
-__underlined__, ``monospaced``, ^^super-scripted^^ text,
-supporting [links](flatworm-markdown) and lists.
-
-_code: markdown.txt
-
-
-_subsection: Configuration @<flatworm-config>
-
-Configuration is optional (but highly recommended) and may be either
-a simple JSON file (config.json) or a JS file (config.js) placed in
-the top  of the source folder.
-
-TODO:  example JSON and example JS
-
-
-_subsection: Extended Directive Functions @<flatworm-extended-directive-functions>
-
-_heading: @INHERIT\<markdown>
-
-Adds an inherits description to a directive. The //markdown// may contain links.
-
-This extended directive function is available for:
-
-- _section
-- _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
-will be linked to by a link next to the //directive//.
-
-This extended directive function requires an advanced ``config.js`` [[flatworm-config]]
-file since it requires a JavaScript function.
-
-This extended directive function is available for:
-
-- _section
-- _subsetion
-- _heading
-- _property

docs.wrm/documentation/markdown.txt

@@ -1,23 +0,0 @@
-**bold text**
-
-//italic text//
-
-__underlined text__
-
-``monospace code``
-
-^^superscript text^^
-
-- This is a list
-- With bullet points
-- With a total of three items
-
-This is separated by -- an en-dash.
-
-This is separated by --- an em-dash.
-
-This is a [Link to Ethereum](https://ethereum.org) and this
-is an [Internal Link](some-link).
-
-This is a self-titled link [[https://ethereumorg]] and this
-[[some-link]] will use the title from its directives value.

docs.wrm/generate-redirects.js

@@ -0,0 +1,113 @@
+const fs = require("fs");
+const { resolve } = require("path");
+
+const Content = `
+<html>
+  <head>
+    <title>ethers.js - Legacy Documentation</title>
+    <style type="text/css">
+      html {
+        font-family: sans-serif;
+      }
+      h1 {
+        opacity: 0.8;
+      }
+      .content {
+        border: 2px solid #000;
+        border-radius: 7px;
+        box-shadow: 5px 5px 10px #aaa;
+        left: 50%;
+        padding: 20px;
+        position: absolute;
+        text-align: center;
+        transform: translate(-50%, 30px);
+        width: 700px;
+      }
+      .hr {
+        border-top: 1px solid black;
+        margin: 4px 10px 40px;
+      }
+      span.v5 {
+        font-size: 24px;
+        margin-bottom: 40px;
+      }
+      span.v4 {
+        opacity: 0.7;
+      }
+    </style>
+  </head>
+  <body>
+    <div class="content">
+      <h1>This link is out-of-date <i>and</i> has moved.</h1>
+      <div class="hr"></div>
+      <span class="v5">Click <a id="link-v5" href="%%DEFAULT%%">here</a> to visit the updated documentation</span>
+      <br />
+      <br />
+      <br />
+      <span class="v4">or continue to the historic <a id="link-v4" href="%%LEGACY%%">legacy documentation</a>.</span>
+    </div>
+    <script type="text/javascript">
+      var redirects = %%REDIRECTS%%;
+      var hash = location.hash;
+      if (hash && hash !== "#") {
+        hash = hash.substring(1);
+        var v4 = document.getElementById("link-v4");
+        v4.setAttribute("href", v4.getAttribute("href").split("#")[0] + "#" + hash);
+        var target = redirects[hash];
+        if (target) {
+          var v5 = document.getElementById("link-v5");
+          v5.setAttribute("href", target);
+        }
+      }
+    </script>
+  </body>
+</html>`
+
+const redirects = require("./redirects.json");
+const links = require("../docs/v5/metadata.json").links;
+
+const result = { };
+
+const prefix = "ethers.js/html/";
+Object.keys(redirects).forEach((uri) => {
+    if (uri.substring(0, prefix.length) !== prefix) { return; }
+
+    const comps = uri.substring(prefix.length).split("#");
+    const filename = comps[0];
+    const hash = comps[1] || "_";
+    const tag = redirects[uri];
+
+    let path = null;
+    if (tag.path) {
+        path = tag.path;
+    } else if (tag.tag) {
+        path = links[tag.tag] || null;
+    } else {
+        console.log("Missing tag:", uri);
+        return;
+    }
+
+    if (!path) {
+        console.log("Missing path:", uri);
+        return;
+    }
+
+    if (!result[filename]) { result[filename] = {
+        "_legacy": `/v4/${ filename }`
+    }; }
+    result[filename][hash] = path;
+});
+
+function generateOutput(filename) {
+    const page = result[filename];
+    return Content.replace("%%DEFAULT%%", page._ || "/v5/")
+                  .replace("%%LEGACY%%", page._legacy || "/v4/")
+                  .replace("%%REDIRECTS%%", JSON.stringify(page));
+}
+
+Object.keys(result).forEach((filename) => {
+    const output = generateOutput(filename);
+    const path = resolve(__dirname, "../docs/ethers.js/html", filename);
+    fs.writeFileSync(path, output);
+});
+

docs.wrm/getting-started.wrm

@@ -1,21 +1,30 @@
-_section: Getting Started
+_section: Getting Started @<getting-started>
 
 
-_subsection: Installing
+_subsection: Installing @<installing>
 
 The various Classes and Functions are available to be imported
 manually from sub-packages under the [@ethersproject](link-ethers-npm)
-but for most projects, the umbrella package is the easiest way to
-get started.
+organization but for most projects, the umbrella package is the
+easiest way to get started.
 
-_code: installing.txt
+_code: @lang<shell>
+
+/home/ricmoo> npm install --save ethers@next
 
 
-_subsection: Importing
+_subsection: Importing @<importing>
 
 _heading: Node.js
 
-_code: importing-node.source
+_code: node.js require @lang<script>
+
+const { ethers } = require("ethers");
+
+_code: ES6 or TypeScript @lang<script>
+
+import { ethers } from "ethers";
+
 
 _heading: Web Browser
 
@@ -26,4 +35,319 @@ yourself.
 For quick demos or prototyping though, it can be loaded in your
 Web Applications from our CDN.
 
-_code: importing-browser.txt
+
+_code: ES6 in the Browser @lang<html>
+
+<script src="https://cdn.ethers.io/lib/ethers-5.0.esm.min.js"
+        type="application/javascipt"></script>
+
+
+_code: ES3 (UMD) in the Browser @lang<html>
+
+<script src="https://cdn.ethers.io/lib/ethers-5.0.umd.min.js"
+        type="application/javascipt"></script>
+
+
+_subsection: Common Terminology @<getting-started--glossary>
+
+This section needs work...
+
+_table: Common Terms
+
+$Provider:  A Provider (in ethers) is a class which provides an abstraction
+            for a connection to the Ethereum Network. It provides read-only
+            access to the Blockchain and its status.
+$Signer:    A Signer is a class which (usually) in some way directly or
+            indirectly has access to a private key, which can sign messages
+            and transactions to authorize the network to charge your account
+            ether to perform operations.
+$Contract:  A Contract is an abstraction which represents a connection to a
+            specific contract on the Ethereum Network, so that it can be
+            used like a normal JavaScipt object.
+
+
+| **Provider**     | $Provider      |
+| **Signer**       | $Signer        |
+| **Contract**     | $Contract      |
+
+
+_subsection: Connecting to Ethereum: Metamask @<getting-started--connecting>
+
+The quickest and easiest way to experiment and begin developing on
+Ethereum is to use [[link-metamask]], which is a browser extension
+that provides:
+
+- A connection to the Ethereum network (a [[Provider]])
+- Holds your private key and can sign thing (a [[Signer]])
+
+_code: Connecting to Metamask @lang<script>
+
+// A Web3Provider wraps a standard Web3 provider, which is
+// what Metamask injects as window.ethereum into each page
+const provider = new ethers.providers.Web3Provider(window.ethereum)
+
+// The Metamask plugin also allows signing transactions to
+// send ether and pay to change state within the blockchain.
+// For this, we need the account signer...
+const signer = provider.getSigner()
+
+
+_heading: Querying the Blockchain @<getting-started--querying>
+
+Once you have a [[Provider]], you have a read-only connection to the
+blockchain, which can be used to query the current state, fetch historic
+logs, look up deployed code and so on.
+
+_code: Basic Queries @lang<javascript>
+
+// Look up the current block number
+provider.getBlockNumber()
+//!
+
+// Get the balance of an account (by address or ENS name)
+balance = await provider.getBalance("ethers.eth")
+//! async balance
+
+// Often you will need to format the output for the user
+// which prefer to see values in ether (instead of wei)
+ethers.utils.formatEther(balance)
+//!
+
+// Or if a user enters a string in an input field, you may need
+// to convert it from ether (as a string) to wei (as a BigNumber)
+ethers.utils.parseEther("1.0")
+//!
+
+
+_heading: Writing to the Blockchain @<getting-started--sending>
+
+_code: Sending Ether @lang<script>
+
+// Send 1 ether to an ens name.
+const tx = signer.sendTransaction({
+    to: "ricmoo.firefly.eth",
+    value: ethers.utils.parseEther("1.0")
+});
+
+
+_subsection: Contracts @<getting-started--contracts>
+
+A Contract is an abstraction of program code which lives on the
+Ethereum blockchain.
+
+The [[Contract]] object makes it easier to use an on-chain
+Contract as a normal JavaScript object, with the method all
+mapped to encoding and decoding data for you.
+
+If you are familiar with Databases, this is similar to ORM.
+
+In order to communicate with the Contract on-chain, this class
+needs to know what methods are available and how to encode and
+decode the data, which is what the //Application Binary Interface// (API)
+provides.
+
+This class is a meta-class, which means its methods are constructed
+at runtime, when you pass in the ABI to the constructor it uses that
+to determine which methods to add.
+
+While a on-chain Contract may have many methods available, you can safely ignore
+any methods you don't need or use, providing a smaller subset of the ABI to
+the contract.
+
+An ABI often comes from the Solidity or Vyper compiler, but may also be
+placed in the code easily using the Human-Readable ABI, which the following
+examples use.
+
+_code: Connecting to the DAI Contract @lang<javascript>
+
+// We can use an ENS name for the contract address
+const daiAddress = "dai.tokens.ethers.eth";
+
+// The ERC-20 Contract ABI, which is a common contract interface
+// for tokens (this is the Human-Readable ABI format)
+const daiAbi = [
+  // Some simple details about the token
+  "function name() view returns (string)",
+  "function symbol() view returns (string)",
+
+  // Get the account balance
+  "function balanceOf(address) view returns (uint)",
+
+  // Send some of your tokens to someone else
+  "function transfer(address to, uint amount)",
+
+  // An event triggered whenever anyone transfers to someone else
+  "event Transfer(address indexed from, address indexed to, uint amount)"
+];
+
+// The Contract object
+const daiContract = new ethers.Contract(daiAddress, daiAbi, provider);
+
+
+_heading: Read-Only Methods @<getting-started--reading>
+
+_code: Querying the DAI Contract @lang<javascript>
+
+// <hide>
+const daiAbi = [
+  // Some simple details about the token
+  "function name() view returns (string)",
+  "function symbol() view returns (string)",
+
+  // Get the account balance
+  "function balanceOf(address) view returns (uint)",
+];
+const daiContract = new ethers.Contract("dai.tokens.ethers.eth", daiAbi, provider);
+// </hide>
+
+// Get the ERC-20 token name
+daiContract.name()
+//!
+
+// Get the ERC-20 token synbol (for tickers and UIs)
+daiContract.symbol()
+//!
+
+// Get the balance of an address
+balance = await daiContract.balanceOf("ricmoo.firefly.eth")
+//! async balance
+
+// Format the DAI for displaying to the user
+ethers.utils.formatUnits(balance, 18)
+//!
+
+
+_heading: State Changing Methods @<getting-started--writing>
+
+_code: Sending DAI @lang<script>
+
+// The DAI Contract is currently connected to the Provider,
+// which is read-only. We need to connect to a Signer, so
+// that we can pay to send state-changing transactions.
+const daiWithSigner = contract.connect(signer);
+
+// Each DAI has 18 decimal places
+const dai = ethers.utils.parseUnits("1.0", 18);
+
+// Send 1 DAI to "ricmoo.firefly.eth"
+tx = daiWithSigner.transfer("ricmoo.firefly.eth", dai);
+
+
+_heading: Listening to Events @<getting-started--events>
+
+_code: Listening to Events @lang<javascript>
+
+// <hide>
+const daiAbi = [
+  "event Transfer(address indexed, address indexed, uint256)"
+];
+const daiContract = new ethers.Contract("dai.tokens.ethers.eth", daiAbi, provider);
+const formatEther = ethers.utils.formatEther;
+// </hide>
+
+// Receive an event when ANY transfer occurs
+daiContract.on("Transfer", (from, to, amount, event) => {
+    console.log(`${ from } sent ${ formatEther(amount) } to ${ to}`);
+    // The event object contains the verbatim log data, the
+    // EventFragment and functions to fetch the block,
+    // transaction and receipt and event functions
+});
+
+// A filter for when a specific address receives tokens
+myAddress = "0x8ba1f109551bD432803012645Ac136ddd64DBA72";
+filter = daiContract.filters.Transfer(null, myAddress)
+// <hide>
+filter
+// </hide>
+//!
+
+// Receive an event when that filter occurs
+daiContract.on(filter, (from, to, amount, event) => {
+    // The to will always be "address"
+    console.log(`I got ${ formatEther(amount) } from ${ from }.`);
+});
+
+// <hide>
+// Don't want to block the docs from compiling...
+daiContract.removeAllListeners();
+// </hide>
+
+
+_heading: Query Historic Events @<getting-started--history>
+
+_code: Filtering Historic Events @lang<javascript>
+
+// <hide>
+const signer = new ethers.VoidSigner("0x8ba1f109551bD432803012645Ac136ddd64DBA72");
+const daiAbi = [
+  "event Transfer(address indexed, address indexed, uint256)"
+];
+const daiContract = new ethers.Contract("dai.tokens.ethers.eth", daiAbi, provider);
+//!
+// </hide>
+
+// Get the address of the Signer
+myAddress = await signer.getAddress()
+//! async myAddress
+
+// Filter for all token transfers to me
+filterFrom = daiContract.filters.Transfer(myAddress, null);
+// <hide>
+filterFrom
+// </hide>
+//!
+
+// Filter for all token transfers from me
+filterTo = daiContract.filters.Transfer(null, myAddress);
+// <hide>
+filterTo
+// </hide>
+//!
+
+// List all transfers sent from me a specific block range
+daiContract.queryFilter(filterFrom, 9843470, 9843480)
+//!
+
+//
+// The following have had the results omitted due to the
+// number of entries; but they provide some useful examples
+//
+
+// List all transfers I sent in the last 10,000 blocks
+daiContract.queryFilter(filterFrom, -10000)
+
+// List all transfers ever sent to me
+daiContract.queryFilter(filterTo)
+
+
+_subsection: Signing Messages @<getting-started--signing>
+
+_code: Signing Messages @lang<javascript>
+
+// <hide>
+const signer = ethers.Wallet.createRandom();
+//!
+// </hide>
+
+// To sign a simple string, which can often be used for
+// logging into a service, such as CryptoKitties simply
+// pass the string in.
+signature = await signer.signMessage("Hello World");
+//! async signature
+
+//
+// A common case is also signing a hash, which is 32
+// bytes. It is important to note, that to sign binary
+// data it MUST be an Array (or TypedArray)
+//
+
+// This string is 66 chacacters long
+message = "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"
+
+// This array representation is 32 bytes long
+messageBytes = ethers.utils.arrayify(message);
+//!
+
+// To sign a hash, you most often want to sign the bytes
+signature = await signer.signMessage(messageBytes)
+//! async signature

docs.wrm/importing-browser.txt

@@ -1,2 +0,0 @@
-<script src="https://cdn.ethers.io/lib/ethers-5.0.esm.min.js"
-        type="application/javascipt"></script>

docs.wrm/importing-node.source

@@ -1,5 +0,0 @@
-// CommonJS
-const { ethers } = require("ethers");
-
-// ES6 or TypeScript 
-const { ethers } = require("ethers");

docs.wrm/index.wrm

@@ -1,13 +1,13 @@
-_section: Documentation
+_section: Documentation @<documentation>
 
-_subsection: What is Ethers?
+_subsection: What is Ethers? @<preamble>
 
 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](link-ethersio) and
 has since expanded into a much more general-purpose library.
 
-_subsection: Features
+_subsection: Features @<features>
 
 - Keep your private keys in your client, **safe** and sound
 - Import and export **JSON wallets** (Geth, Parity and crowdsale)
@@ -46,9 +46,9 @@ _toc:
     contributing
     documentation
     license
-    
 
-_subsection: Legacy Documentation
+
+_subsection: Legacy Documentation @<documentation--legacy>
 
 This section will be kept up to date, linking to documentation of
 older versions of the library.

docs.wrm/installing.txt

@@ -1 +0,0 @@
-/home/ricmoo> npm install --save ethers@next

docs.wrm/migration/ethers-v4.wrm

@@ -1,27 +1,13 @@
------
+_section: Migration: From Ethers v4  @<migration-v4>
 
-Documentation: [html](https://docs-beta.ethers.io/)
+_subsection: BigNumber
 
------
-
-Migration: From Ethers v4
-=========================
-
-
-
-BigNumber
----------
-
-
-
-### Namespace
-
-
-Since [BigNumber](../../api/utils/bignumber) is used quite frequently, it has been moved to
+_heading: Namespace
+Since [[BigNumber]] is used quite frequently, it has been moved to
 the top level of the umbrella package.
 
+_code: @lang<script>
 
-```
 // v4
 ethers.utils.BigNumber
 ethers.utils.BigNumberish
@@ -29,20 +15,16 @@ ethers.utils.BigNumberish
 // v5
 ethers.BigNumber
 ethers.BigNumberish
-```
 
 
-
-### Creating Instances
-
-
-The `bigNumberify` method was always preferred over the constructor
-since it could short-circuit an object instantiation for [[bignumber]
+_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.
+``from`` class method.
 
+_code: @lang<script>
 
-```
 // v4
 new ethers.utils.BigNumber(someValue)
 ethers.utils.bigNumberify(someValue);
@@ -51,36 +33,26 @@ ethers.utils.bigNumberify(someValue);
 // - Constructor is private
 // - Removed `bigNumberify`
 ethers.BigNumber.from(someValue)
-```
 
 
+_subsection: Contracts
 
-Contracts
----------
+_code: @lang<script>
+
+// @TODO
 
 
-```
-TODO
-```
+_subsection: Errors
 
-
-
-Errors
-------
-
-
-
-### Namespace
-
-
-All errors now belong to the [Logger](../../api/utils/logger) class and the related functions
-have been moved to [Logger](../../api/utils/logger) instances, which can include a per-package
+_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](../../api/utils/logger) class methods.
+Global error fucntions have been moved [[Logger]] class methods.
 
+_code: @lang<script>
 
-```
 // v4
 ethers.errors.UNKNOWN_ERROR
 ethers.errors.*
@@ -109,25 +81,19 @@ logger.checkNormalize()
 logger.throwError(message, code, params)
 logger.warn(...)
 logger.info(...)
-```
 
 
-
-Interface
----------
-
-
-The [Interface](../../api/utils/abi/interface) object has undergone the most dramatic changes.
+_subsection: Interface
+The [[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
 
-### Functions
+_code: @lang<script>
 
-
-```
 // v4 (example: "transfer(address to, uint amount)")
 interface.functions.transfer.encode(to, amount)
 interface.functions.transfer.decode(callData)
@@ -141,14 +107,12 @@ interface.decodeResult("transfer", data)
 // e.g. "uint" and "uint256" will be automatically converted
 interface.encodeData("transfer(address,uint)", [ to, amount ])
 interface.decodeResult("transfer(address to, uint256 amount)", data)
-```
 
 
+_heading: Events
 
-### Events
+_code: @lang<script>
 
-
-```
 // v4 (example: Transfer(address indexed, address indexed, uint256)
 interface.events.Transfer.encodeTopics(values)
 interface.events.Transfer.decode(data, topics)
@@ -156,18 +120,14 @@ interface.events.Transfer.decode(data, topics)
 // v5
 interface.encodeFilterTopics("Transfer", values)
 interface.encodeEventLog("Transfer", data, topics)
-```
-
-
-
-### Inspection
 
 
+_heading: Inspection
 Interrogating properties about a function or event can now (mostly) be
-done directly on the [Fragment](../../api/utils/abi/fragments) object.
+done directly on the [[Fragment]] object.
 
+_code:
 
-```
 // v4
 interface.functions.transfer.name
 interface.functions.transfer.inputs
@@ -216,37 +176,24 @@ const sighash = interface.getSighash(functionFragment)
 
 const eventSig = eventFragment.format()
 const topic = interface.getTopic(eventFragment)
-```
 
 
+_subsection: Utilities
 
-Utilities
----------
+_heading: Renaming
 
+_code: @lang<script>
 
+// @TODO
 
-### Renaming
-
-
-```
-TODO
-```
-
-
-
-Wallet
-------
-
-
-
-### Mnemonic Phrases
-
+_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`.
+a single ``mnemonic`` object, which also now includes the ``locale``.
 
+_code: @lang<script>
 
-```
 // v4
 wallet.mnemonic
 wallet.path
@@ -256,10 +203,4 @@ wallet.path
 // - Note: wallet.mnemonic is null if there is no mnemonic
 wallet.mnemonic.phrase
 wallet.mnemonic.path
-```
 
-
-
-
------
-**Content Hash:** 27061bfb6d646d514915e15779b869747049a93a7f75eda79a9f92fdb81b41ae

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

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