Moved all flatworm docs to inline code.

docs.wrm/api/contract/example.wrm

@@ -2,7 +2,43 @@ _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]]>

docs.wrm/api/providers/provider.wrm

@@ -22,7 +22,27 @@ sent to the network.
 
 _heading: Examples
 
-_code: example-account.js
+_code: @lang<javascript>
+
+// <hide>
+const provider = ethers.getDefaultProvider()
+// </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");
+//!
 
 
 _subsection: Blocks Methods
@@ -52,7 +72,20 @@ not have an address configured, ``null`` is returned.
 
 _heading: Examples
 
-_code: example-ens.js
+_code: @lang<javascript>
+
+// <hide>
+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");
+//!
+
 
 _subsection: Logs Methods
 

docs.wrm/api/providers/types.wrm

@@ -240,7 +240,7 @@ 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)
+To compute a contract address, the [getContractAddress](utils-getContractAddress)
 utility function can also be used with a [[provider-transactionresponse]]
 object, which requires the transaction nonce and the address of the sender.
 

docs.wrm/api/utils/address.wrm

@@ -39,7 +39,7 @@ 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 @<urils--address-basic>
 
 _property: ethers.utils.getAddress(address) => string<[[address]]>  @<utils-getAddress> @SRC<address>
 Returns //address// as a Checksum Address.
@@ -49,18 +49,35 @@ 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-computation>
+
+_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.wrm

@@ -13,7 +13,23 @@ and parameters which accept values will generally accept them.
 
 _heading: Importing
 
-_code: bignumber-import.source
+_code: CommonJS @lang<script>
+
+// From the Umbrella ethers package...
+const { BigNumber } = require("ethers");
+
+// From the bignumber pacakge...
+const { BigNumber } = require("@ethersproject/bignumber");
+
+
+_code: ES6 and TypeScript CommonJS @lang<script>
+
+// From the Umbrella ethers package...
+import { BigNumber } from "ethers";
+
+// From the bignumber pacakge...
+import { BigNumber } from "@ethersproject/bignumber";
+
 
 _subsection: Types
 
@@ -50,7 +66,46 @@ 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
@@ -65,7 +120,7 @@ _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//.
+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//.
@@ -146,7 +201,13 @@ 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
@@ -171,7 +232,12 @@ 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).

docs.wrm/api/utils/bytes.wrm

@@ -79,7 +79,31 @@ zeros.
 
 _heading: Examples
 
-_code: bytes-conversion.js
+_code: @lang<javascript>
+
+// 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
@@ -139,3 +163,16 @@ Return a new Uint8Array of //length// random bytes.
 
 _property: ethers.utils.shuffled(array) => Array<any>  @<utils.shuffled> @SRC<random>
 Return a copy of //array// shuffled using [[link-wiki-shuffle]].
+
+_code: Examples @lang<javascript>
+
+utils.randomBytes(8)
+//!
+
+const foo = [ 1, 2, 3, 4, 5, 6, 7 ];
+utils.shuffled(foo);
+//!
+
+// The original array is unscathed...
+foo
+//!

docs.wrm/api/utils/constants.wrm

@@ -4,7 +4,10 @@ The **ethers.contants** Object contains commonly used values.
 
 _heading: Importing
 
-_code: constants-import.js
+_code: @lang<script>
+
+const { constants } = require("ethers");
+const { constants } = require("@ethersproject/constants");
 
 
 _subsection: Bytes

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

@@ -21,23 +21,29 @@ _subsection: Units
 
 _heading: Decimal Count
 
-The //unit// specified may be an integer, which indicates how
+A **Unit** can be specified as an number, which indicates the
-many decimal place the unit has. For example, 1 ether has 18 decimal
+number of decimal places that should be used.
-places for wei, and if this library were used with Bitcoin, 1 BTC
+
-has 8 decimal places for satoshis.
+**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
+There are also several common **Named Units**, in which case their name (as
-are several common units, which can be passed in as a string:
+a string) may be used.
 
-- **wei** --- 0
+_table: @STYLE<compact>
-- **kwei** --- 3
+
-- **mwei** --- 6
+|  **Name**    |  **Decimals**  |
-- **gwei** --- 9
+|  //wei//     |      0         |
-- **szabo** --- 12
+|  //kwei//    |      3         |
-- **finney** --- 15
+|  //mwei//    |      6         |
-- **ether** --- 18
+|  //gwei//    |      9         |
+|  //szabo//   |     12         |
+|  //finney//  |     15         |
+|  //ether//   |     18         |
 
 
 _subsection: Functions

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: asm-simplestore-asm.txt
+_code: @lang<asm>
+
+; 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") }}
+    ]
+}
+
 
 _definition: **SimpleStore.bin**
 
-_code: asm-simplestore-bin.txt
+_code: @lang<text>
+
+0x602a6000556044601160003960446000f334601e5760003560e01c8063209652
+0x5514602457806355241077146030575b60006000fd5b60005460005260206000
+0xf35b6024361415601e5760043560005560006000f3
+
 
 _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.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.wrm

@@ -9,21 +9,163 @@ 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: ethers-init.txt
+_code: @lang<shell>
+
+/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
+
 
 _heading: Sending Ether and Tokens  @<cliex-send>
 
-_code: ethers-send.txt
+_code: @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
+
 
 _heading: Signing Messages  @<cliex-signing>
 
-_code: ethers-sign.txt
+_code: @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 +173,28 @@ 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: @lang<shell>
+
+# 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
+
 
 _heading: Using Mnemonics (with a password)  @<cliex-mnemonicpassword>
 
@@ -40,7 +203,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 public-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 +222,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.wrm

@@ -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.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/security/index.wrm

@@ -64,5 +64,22 @@ 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: lightkdf.js
+_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,6 +115,31 @@ const getSourceUrl = (function(path, include, exclude) {
     }
 })("../packages/", new RegExp("packages/.*/src.ts/.*\.ts$"), new RegExp("/node_modules/|src.ts/.*browser.*"));
 
+function codeContextify(context) {
+    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._inspect = function(value) {
+        if (context.BigNumber.isBigNumber(value)) {
+            return `{ BigNumber: ${ JSON.stringify(value.toString()) } }`;
+        }
+
+        if (value && typeof(value.length) === "number" && typeof(value) !== "string") {
+            return "[ " + Array.prototype.map.call(value, (i) => context._inspect(i)).join(", ") + " ]";
+        }
+
+        return JSON.stringify(value);
+    }
+}
+
 module.exports = {
   title: "ethers",
   subtitle: "v5.0-beta",
@@ -127,6 +152,8 @@ module.exports = {
       "banner": "-----\n\nDocumentation: [html](https://docs-beta.ethers.io/)\n\n-----\n\n"
   },
 
+  codeContextify: codeContextify,
+
   getSourceUrl: getSourceUrl,
 
   codeRoot: "../",
@@ -197,6 +224,7 @@ module.exports = {
       "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",

docs.wrm/documentation/index.wrm

@@ -18,7 +18,17 @@ itself have body.
 
 _heading: Directive Format
 
-_code: fragment.txt
+_code: @lang<text>
+
+\_DIRECTIVE: VALUE @<LINK> @EXTENSION<PARAMETER>
+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>
@@ -29,16 +39,22 @@ 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.
 
+**Extensions:** @INHERIT, @SRC, @NAV, @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. If an option is specified, it is avaialble as a name for
 internal linking.
 
+**Extensions:** @INHERIT, @SRC, @NOTE
+
 _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.
 
+**Extensions:** @INHERIT, @SRC, @NOTE
+
 _definition: **_definition:** //TERM//
 A //definition// has its **TERM** bolded and the markdown body is
 indented.
@@ -47,15 +63,18 @@ _definition: **_property:** //SIGNATURE//
 A //property// has its JavaScript **SIGNATURE** formatted and the
 markdown body is indented.
 
+**Extensions:** @SRC
+
 _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//
+_definition: **_code:** //TITLE//
-A //code// reads the **FILENAME** and depending on the extension
+A //code// creates a code block.
-adjusts it.
+
+**Extensions:** @LANG
 
 For JavaScript files, the file is executed, with ``\/\/!`` replaced
 with the result of the last statement and ``\/\/!error`` is replaced
@@ -75,16 +94,73 @@ used to reset the indentation.
 
 _heading: Examples @<>
 
-_code: examples.txt
+_code: @lang<text>
+
+\_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: heading
+
+// Some code goes here
+while(1);
+
+\_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
+
 
 _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,
+__underlined__, ``monospaced``, super^^script^^ and ~~strike~~
-supporting [links](flatworm-markdown) and lists.
+text, supporting [links](flatworm-markdown) and lists.
 
-_code: markdown.txt
+_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: Configuration @<flatworm-config>
@@ -96,26 +172,34 @@ the top  of the source folder.
 TODO:  example JSON and example JS
 
 
-_subsection: Extended Directive Functions @<flatworm-extended-directive-functions>
+_subsection: Extensions @<flatworm-extensions>
 
 _heading: @INHERIT\<markdown>
 
 Adds an inherits description to a directive. The //markdown// may contain links.
 
-This extended directive function is available for:
 
-- _section
+_heading: @LANG\<text>
-- _subsetion
+
-- _heading
+Set the language the code should be syntax-highlighted for. If "javascript", the
+code will be evaluated.
+
+- javascript (will be evaluated)
+- script (useful for JavaScript but that should not be evaluated)
+- shell
+- text
 
 
 _heading: @NAV\<text>
 
 Sets the name in the breadcrumbs when not the current node.
 
-This extended directive function is available for:
 
-- _section
+_heading: @NOTE\<markdown>
+
+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\<text>
@@ -125,10 +209,3 @@ 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/getting-started.wrm

@@ -8,14 +8,23 @@ manually from sub-packages under the [@ethersproject](link-ethers-npm)
 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
 
 _heading: Node.js
 
-_code: importing-node.source
+_code: @lang<script>
+
+// CommonJS
+const { ethers } = require("ethers");
+
+// ES6 or TypeScript
+import { ethers } from "ethers";
+
 
 _heading: Web Browser
 
@@ -26,4 +35,7 @@ yourself.
 For quick demos or prototyping though, it can be loaded in your
 Web Applications from our CDN.
 
-_code: importing-browser.txt
+_code: @lang<html>
+
+<script src="https://cdn.ethers.io/lib/ethers-5.0.esm.min.js"
+        type="application/javascipt"></script>

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

@@ -5,18 +5,42 @@ _subsection: BigNumber
 _heading: Namespace
 Since [[bignumber]] is used quite frequently, it has been moved to
 the top level of the umbrella package.
-_code: bignumber-namespace.txt
+
+_code: @lang<script>
+
+// v4
+ethers.utils.BigNumber
+ethers.utils.BigNumberish
+
+// v5
+ethers.BigNumber
+ethers.BigNumberish
+
 
 _heading: Creating Instances
 The ``bigNumberify`` method was always preferred over the constructor
 since it could short-circuit an object instantiation for [[bignumber]
 objects (since they are immutable). This has been moved to a static
 ``from`` class method.
-_code: bignumber-creating.txt
+
+_code: @lang<script>
+
+// v4
+new ethers.utils.BigNumber(someValue)
+ethers.utils.bigNumberify(someValue);
+
+// v5
+// - Constructor is private
+// - Removed `bigNumberify`
+ethers.BigNumber.from(someValue)
 
 
 _subsection: Contracts
-_code: contracts.txt
+
+_code: @lang<script>
+
+// @TODO
+
 
 _subsection: Errors
 
@@ -26,7 +50,37 @@ have been moved to [[logger]] instances, which can include a per-package
 version string.
 
 Global error fucntions have been moved [[logger]] class methods.
-_code: errors.txt
+
+_code: @lang<script>
+
+// v4
+ethers.errors.UNKNOWN_ERROR
+ethers.errors.*
+
+errors.setCensorship(censorship, permanent)
+errors.setLogLevel(logLevel)
+
+errors.checkArgumentCount(count, expectedCount, suffix)
+errors.checkNew(self, kind)
+errors.checkNormalize()
+errors.throwError(message, code, params)
+errors.warn(...)
+errors.info(...)
+
+// v5
+ethers.utils.Logger.errors.UNKNOWN_ERROR
+ethers.utils.Logger.errors.*
+
+Logger.setCensorship(censorship, permanent)
+Logger.setLogLevel(logLevel)
+
+const logger = new ethers.utils.Logger(version);
+logger.checkArgumentCount(count, expectedCount, suffix)
+logger.checkNew(self, kind)
+logger.checkNormalize()
+logger.throwError(message, code, params)
+logger.warn(...)
+logger.info(...)
 
 
 _subsection: Interface
@@ -37,26 +91,116 @@ contract interface operations without the need for object inspection and
 special edge cases.
 
 _heading: Functions
-_code: interface-functions.txt
+
+_code: @lang<script>
+
+// v4 (example: "transfer(address to, uint amount)")
+interface.functions.transfer.encode(to, amount)
+interface.functions.transfer.decode(callData)
+
+// v5
+interface.encodeData("transfer", [ to, amount ])
+interface.decodeResult("transfer", data)
+
+// Or you can use any compatible signature or Fragment objects.
+// Notice that signature normalization is performed for you,
+// e.g. "uint" and "uint256" will be automatically converted
+interface.encodeData("transfer(address,uint)", [ to, amount ])
+interface.decodeResult("transfer(address to, uint256 amount)", data)
+
 
 _heading: Events
-_code: interface-events.txt
+
+_code: @lang<script>
+
+// v4 (example: Transfer(address indexed, address indexed, uint256)
+interface.events.Transfer.encodeTopics(values)
+interface.events.Transfer.decode(data, topics)
+
+// v5
+interface.encodeFilterTopics("Transfer", values)
+interface.encodeEventLog("Transfer", data, topics)
+
 
 _heading: Inspection
 Interrogating properties about a function or event can now (mostly) be
 done directly on the [[abi-fragment]] object.
-_code: interface-inspection.txt
+
+_code:
+
+// v4
+interface.functions.transfer.name
+interface.functions.transfer.inputs
+interface.functions.transfer.outputs
+interface.functions.transfer.payable
+interface.functions.transfer.gas
+
+// v5
+const functionFragment = interface.getFunction("transfer")
+functionFragment.name
+functionFragment.inputs
+functionFragment.outputs
+functionFragment.payable
+functionFragment.gas
+
+
+// v4; type is "call" or "transaction"
+interface.functions.transfer.type
+
+// v5; constant is true (i.e. "call") or false (i.e. "transaction")
+functionFragment.constant
+
+
+// v4
+interface.events.Transfer.anonymous
+interface.events.Transfer.inputs
+interface.events.Transfer.name
+
+// v5
+const eventFragment = interface.getEvent("Transfer");
+eventFragment.anonymous
+eventFragment.inputs
+eventFragment.name
+
+
+// v4
+const functionSig = interface.functions.transfer.signature
+const sighash = interface.functions.transfer.sighash
+
+const eventSig = interface.events.Transfer.signature
+const topic = interface.events.Transfer.topic
+
+// v5
+const functionSig = functionFragment.format()
+const sighash = interface.getSighash(functionFragment)
+
+const eventSig = eventFragment.format()
+const topic = interface.getTopic(eventFragment)
 
 
 _subsection: Utilities
 
 _heading: Renaming
-_code: utils.txt
 
+_code: @lang<script>
+
+// @TODO
 
 _subsection: Wallet
 
 _heading: Mnemonic Phrases
 The **mnemonic** phrase and related properties have been merged into
 a single ``mnemonic`` object, which also now includes the ``locale``.
-_code: wallet.txt
+
+_code: @lang<script>
+
+// v4
+wallet.mnemonic
+wallet.path
+
+// v5
+// - Mnemonic phrase and path are a Mnemonic object
+// - Note: wallet.mnemonic is null if there is no mnemonic
+wallet.mnemonic.phrase
+wallet.mnemonic.path
+