From 381a72ddaa7fb59ef2ded84d228296d693df05c3 Mon Sep 17 00:00:00 2001 From: Richard Moore Date: Fri, 10 Jan 2020 01:01:00 -0500 Subject: [PATCH] Added more docs. --- docs.wrm/api/providers/api-providers.wrm | 10 +- docs.wrm/api/providers/jsonrpc-provider.wrm | 15 +- docs.wrm/api/providers/other.wrm | 14 +- docs.wrm/api/providers/provider.wrm | 52 ++--- docs.wrm/api/signer.wrm | 187 ++++++++++++++- docs.wrm/api/utils/abi.wrm | 242 ++++++++++++++++++++ docs.wrm/api/utils/address.wrm | 27 ++- docs.wrm/api/utils/bignumber.wrm | 40 ++-- docs.wrm/api/utils/bytes.wrm | 45 ++-- docs.wrm/api/utils/constants.wrm | 18 +- docs.wrm/api/utils/display-logic.wrm | 10 +- docs.wrm/api/utils/encoding.wrm | 21 ++ docs.wrm/api/utils/fixednumber.wrm | 73 ++++-- docs.wrm/api/utils/hashing.wrm | 24 +- docs.wrm/api/utils/index.wrm | 1 + docs.wrm/api/utils/signing-key.wrm | 12 + docs.wrm/api/utils/strings.wrm | 15 +- docs.wrm/cli/ens-help.txt | 69 ++++++ docs.wrm/cli/ens.wrm | 13 ++ docs.wrm/cli/ethers-help.txt | 65 ++++++ docs.wrm/cli/ethers-init.txt | 14 ++ docs.wrm/cli/ethers-mnemonic-hard.txt | 8 + docs.wrm/cli/ethers-mnemonic.txt | 7 + docs.wrm/cli/ethers-script.txt | 19 ++ docs.wrm/cli/ethers-send.txt | 44 ++++ docs.wrm/cli/ethers-sign.txt | 14 ++ docs.wrm/cli/ethers.wrm | 59 +++++ docs.wrm/cli/index.wrm | 9 + docs.wrm/cli/plugin.txt | 10 + docs.wrm/cli/plugin.wrm | 148 ++++++++++++ docs.wrm/cli/typescript-help.txt | 19 ++ docs.wrm/cli/typescript.wrm | 11 + docs.wrm/concepts/index.wrm | 3 +- docs.wrm/config.js | 129 +++++++++++ docs.wrm/documentation/examples.txt | 10 +- docs.wrm/documentation/fragment.txt | 12 +- docs.wrm/documentation/index.wrm | 45 +++- docs.wrm/index.wrm | 1 + 38 files changed, 1358 insertions(+), 157 deletions(-) create mode 100644 docs.wrm/api/utils/abi.wrm create mode 100644 docs.wrm/api/utils/encoding.wrm create mode 100644 docs.wrm/api/utils/signing-key.wrm create mode 100644 docs.wrm/cli/ens-help.txt create mode 100644 docs.wrm/cli/ens.wrm create mode 100644 docs.wrm/cli/ethers-help.txt create mode 100644 docs.wrm/cli/ethers-init.txt create mode 100644 docs.wrm/cli/ethers-mnemonic-hard.txt create mode 100644 docs.wrm/cli/ethers-mnemonic.txt create mode 100644 docs.wrm/cli/ethers-script.txt create mode 100644 docs.wrm/cli/ethers-send.txt create mode 100644 docs.wrm/cli/ethers-sign.txt create mode 100644 docs.wrm/cli/ethers.wrm create mode 100644 docs.wrm/cli/index.wrm create mode 100644 docs.wrm/cli/plugin.txt create mode 100644 docs.wrm/cli/plugin.wrm create mode 100644 docs.wrm/cli/typescript-help.txt create mode 100644 docs.wrm/cli/typescript.wrm create mode 100644 docs.wrm/config.js diff --git a/docs.wrm/api/providers/api-providers.wrm b/docs.wrm/api/providers/api-providers.wrm index 080a0a5f55..60bf3ff4ad 100644 --- a/docs.wrm/api/providers/api-providers.wrm +++ b/docs.wrm/api/providers/api-providers.wrm @@ -13,7 +13,7 @@ To mitigate these issues, it is recommended you use a [Default Provider](get-default-provider). -_subsection: EtherscanProvider +_subsection: EtherscanProvider @INHERIT<[[provider]]> The **EtherscanProvider** is backed by a combination of the various [Etherscan APIs](https://etherscan.io/apis). @@ -21,7 +21,7 @@ The **EtherscanProvider** is backed by a combination of the various _property: provider.getHistory(address) => Array -_subsection: InfuraProvider +_subsection: InfuraProvider @INHERIT<[[urljsonrpc-provider]]> The **InfuraProvider** is backed by the popular [INFURA](https://infura.io) Ethereum service. @@ -30,7 +30,7 @@ It supports Mainnet (homestead) and all common testnets (Ropsten, Rinkeby, Görli and Kovan). -_subsection: NodesmithProvider +_subsection: NodesmithProvider @INHERIT<[[urljsonrpc-provider]]> The **NodesmithProvider** is backed by [Nodesmith](https://nodesmith.io). @@ -38,7 +38,7 @@ It supports Mainnet (homestead) and all common testnets (Ropsten, Rinkeby, Görli and Kovan), as well as the Ethereum-like network [Aion](https://aion.network). -_subsection: AlchemyProvider +_subsection: AlchemyProvider @INHERIT<[[urljsonrpc-provider]]> The **AlchemtProvider** is backed by [Alchemy](https://alchemyapi.io). @@ -46,7 +46,7 @@ It supports Mainnet (homestead) and all common testnets (Ropsten, Rinkeby, Görli and Kovan). -_subsection: CloudfrontProvider +_subsection: CloudfrontProvider @INHERIT<[[urljsonrpc-provider]]> The CloudfrontProvider is backed by the [Cloudflare Ethereum Gateway](https://developers.cloudflare.com/distributed-web/ethereum-gateway/). diff --git a/docs.wrm/api/providers/jsonrpc-provider.wrm b/docs.wrm/api/providers/jsonrpc-provider.wrm index e0e9fc420e..40a7444b7d 100644 --- a/docs.wrm/api/providers/jsonrpc-provider.wrm +++ b/docs.wrm/api/providers/jsonrpc-provider.wrm @@ -4,19 +4,24 @@ _section: JSON-RPC Provider Explain here... -_subsection: JsonRpcProvider @ +_subsection: JsonRpcProvider @ @INHERIT<[[provider]]> TODO... -_property: provider.getSigner([ addressOrIndex ]) => [[jsonrpc-signer]] +_property: jsonRpcProvider.getSigner([ addressOrIndex ]) => [[jsonrpc-signer]] @ @SRC Returns a [[jsonrpc-signer]] which is managed by this Ethereum node, at //addressOrIndex//. If no //addressOrIndex// is provided, the first account (account #0) is used. -_property: provider.getUncheckSigner([ addressOrIndex ]) => [[jsonrpc-uncheckedsigner]] +_property: jsonRpcProvider.getUncheckedSigner([ addressOrIndex ]) => [[jsonrpc-uncheckedsigner]] @ @SRC -_subsection: JsonRpcSigner @ +_property: jsonRpcProvider.listAccounts() => Array @ @SRC + +_property: jsonRpcProvider.send(method, params) => Promise @ @SRC + + +_subsection: JsonRpcSigner @ @INHERIT<[[signer]]> TODO... Explain -_subsection: JsonRpcUncheckedSigner @ +_subsection: JsonRpcUncheckedSigner @ @INHERIT<[[signer]]> TODO... Explain diff --git a/docs.wrm/api/providers/other.wrm b/docs.wrm/api/providers/other.wrm index 39f1b132b2..a513010d89 100644 --- a/docs.wrm/api/providers/other.wrm +++ b/docs.wrm/api/providers/other.wrm @@ -4,7 +4,7 @@ _section: Other Providers Others... -_subsection: FallbackProvider @ +_subsection: FallbackProvider @ @INHERIT<[[provider]]> Explain... @@ -21,7 +21,17 @@ _property: provider.weights => Array The weight each of the Providers adds to a results acceptance. -_subsection: IpcProvider @ +_subsection: IpcProvider @ @INHERIT<[[jsonrpc-provider]]> Explain... +_subsection: UrlJsonRpcProvider @ @INHERIT<[[jsonrpc-provider]]> + +Tra la la + +_subsection: Web3Provider @ @INHERIT<[[jsonrpc-provider]]> + +Tra la la + + + diff --git a/docs.wrm/api/providers/provider.wrm b/docs.wrm/api/providers/provider.wrm index a2b1dd131a..6c021b8127 100644 --- a/docs.wrm/api/providers/provider.wrm +++ b/docs.wrm/api/providers/provider.wrm @@ -8,17 +8,17 @@ Explain what a provider is... _subsection: Accounts Methods -_property: provider.getBalance(address [ , blockTag = "latest" ]) => Promise<[[bignumber]]> +_property: provider.getBalance(address [ , blockTag = "latest" ]) => Promise<[[bignumber]]> @ @SRC Returns the balance of //address// as of the //blockTag// block height. -_property: provider.getCode(address [ , blockTag = "latest" ]) => Promise<[[hexstring]]> +_property: provider.getCode(address [ , blockTag = "latest" ]) => Promise> @ @SRC 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(address, position [ , blockTag = "latest" ]) => Promise<[[hexstring]]> -Returns the ``Bytes32`` value of the //position// at //address//, as of the //blockTag//. +_property: provider.getStorageAt(addr, pos [ , blockTag = "latest" ]) => Promise> @ @SRC +Returns the ``Bytes32`` value of the position //pos// at address //addr//, as of the //blockTag//. -_property: provider.getTransactionCount(address [ , blockTag = "latest" ]) => Promise +_property: provider.getTransactionCount(address [ , blockTag = "latest" ]) => Promise @ @SRC 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. @@ -30,11 +30,11 @@ _code: example-account.js _subsection: Blocks Methods -_property: provider.getBlock(block) => Promise<[[provider-block]]> +_property: provider.getBlock(block) => Promise<[[provider-block]]> @ @SRC Get the //block// from the network, where the ``result.transactions`` is a list of transaction hashes. -_property: provider.getBlockWithTransactions(block) => Promise<[[provider-blocktxs]]> +_property: provider.getBlockWithTransactions(block) => Promise<[[provider-blocktxs]]> @ @SRC Get the //block// from the network, where the ``result.transactions`` is an Array of [[provider-transactionresponse]] objects. @@ -43,12 +43,12 @@ _subsection: Ethereum Naming Service (ENS) Methods TODO: Explain ENS here... -_property: provider.lookupAddress(address) => Promise +_property: provider.lookupAddress(address) => Promise @ @SRC 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.resovleName(name) => Promise +_property: provider.resolveName(name) => Promise> @ @SRC 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. @@ -59,7 +59,7 @@ _code: example-ens.js _subsection: Logs Methods -_property: provider.getLogs(filter) => Promise> +_property: provider.getLogs(filter) => Promise> @ @SRC Returns the Array of [[provider-log]] matching the //filter//. Keep in mind that many backends will discard old events, and that requests @@ -69,24 +69,24 @@ execute the query. _subsection: Network Status Methods -_property: provider.getNetwork() => Promise<[[provider-network]]> +_property: provider.getNetwork() => Promise<[[provider-network]]> @ @SRC Returns the [[provider-network]] this Provider is connected to. -_property: provider.getBlockNumber() => Promise +_property: provider.getBlockNumber() => Promise @ @SRC Returns the block number (or height) of the most recently mined block. -_property: provider.getGasPrice() => Promise<[[bignumber]]> +_property: provider.getGasPrice() => Promise<[[bignumber]]> @ @SRC Returns a //best guess// of the [[gas-price]] to use in a transaction. _subsection: Transactions Methods -_property: provider.call(transaction [ , blockTag = "latest" ]) => Promise<[[hexstring]]> -Returns the result of executing the //transaction//, using //call//. A call +_property: provider.call(transaction [ , blockTag = "latest" ]) => Promise> @ @SRC +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]]> +_property: provider.estimateGas(transaction) => Promise<[[bignumber]]> @ @SRC Returns an estimate of the amount of gas that would be required to submit //transaction// to the network. @@ -94,12 +94,12 @@ 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]]> +_property: provider.sendTransaction(transaction) => Promise<[[provider-transactionresponse]]> @ @SRC 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-transactionreceipt]]> +_property: provider.waitForTransaction(transactionHash) => Promise<[[provider-transactionreceipt]]> @ @SRC Returns a Promise which will not resolve until //transactionHash// is mined. @@ -107,35 +107,35 @@ _subsection: Event Emitter Methods Explain events here... -_property: provider.on(eventName, listener) => this +_property: provider.on(eventName, listener) => this @ @SRC Add a //listener// to be triggered for each //eventName//. -_property: provider.once(eventName, listener) => this +_property: provider.once(eventName, listener) => this @ @SRC Add a //listener// to be triggered for only the next //eventName//, at which time it be removed. -_property: provider.emit(eventName, ...args) => boolean +_property: provider.emit(eventName, ...args) => boolean @ @SRC Notify all listeners of //eventName//, passing //args// to each listener. This is generally only used internally. -_property: provider.off(eventName [ , listener ]) => this +_property: provider.off(eventName [ , listener ]) => this @ @SRC Remove a //listener// for //eventName//. If no //listener// is provided, all listeners for //eventName// are removed. -_property: provider.removeAllListeners([ eventName ]) => this +_property: provider.removeAllListeners([ eventName ]) => this @ @SRC Remove all the listeners for //eventName//. If no //eventName// is provided, **all** events are removed. -_property: provider.listenerCount([ eventName ]) => number +_property: provider.listenerCount([ eventName ]) => number @ @SRC Returns the number of listeners for //eventName//. If no //eventName// is provided, the total number of listeners is returned. -_property: provider.listeners(eventName) => Array +_property: provider.listeners(eventName) => Array @ @SRC Returns the list of Listeners for //eventName//. _subsection: Inspection Methods -_property: Provider.isProvider(object) => boolean +_property: Provider.isProvider(object) => boolean @ @SRC Returns true if and only if //object// is a Provider. diff --git a/docs.wrm/api/signer.wrm b/docs.wrm/api/signer.wrm index 54a5a751f3..ad25cd33bc 100644 --- a/docs.wrm/api/signer.wrm +++ b/docs.wrm/api/signer.wrm @@ -2,32 +2,195 @@ _title: Signer _section: Signers -Tra la la... +A Signer represents... -_subsection: Signer @ +_subsection: Signer @ @SRC -_property: signer.connect(provider) => [[signer]] +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 [[jsonrpc-signer]]. + +_property: signer.connect(provider) => [[signer]] @ + +Sub-classes **must** implement this, however they may simply throw an error +if changing providers is not supported. + +_property: signer.getAddress() => Promise> @ @SRC +Returns a Promise that resolves to the account address. + +This is a Promise so that a **Signer** can be designed around an +asynchronous source, such as hardware wallets. + +Sub-classes **must** implement this. + +_property: Signer.isSigner(object) => boolean @ @SRC +Returns true if an only if //object// is a **Signer**. + +_heading: Blockchain Methods @ + +_property: signer.getBalance([ blockTag = "latest" ]) => Promise<[[bignumber]]> @ @SRC TODO -_heading: Blockchain Methods +_property: signer.getChainId() => Promise @ @SRC +TODO -_property: signer.getBalance([ blockTag = "latest" ]) => Promise<[[bignumber]]> +_property: signer.getGasPrice() => Promise<[[bignumber]]> @ @SRC TODO -_property: signer.getTransactionCount([ blockTag = "latest" ]) => Promise +_property: signer.getTransactionCount([ blockTag = "latest" ]) => Promise @ @SRC TODO +_property: signer.call(transactionRequest) => Promise> @ @SRC +TODO -_subsection: Wallet inherits Signer +_property: signer.estimateGas(transactionRequest) => Promise<[[bignumber]]> @ @SRC +TODO -The Wallet class inherits [[signer]] and can sign transactions and messages -using a private key as a standard Externally Owned Account (EOA). +_property: signer.resolveName(name) => Promise> @ @SRC +TODO + + +_heading: Signing + +_property: signer.signMessage(message) => Promise> @ +This returns a Promise which resolves to the [[signature-flat]] +of //message//. -_heading: Creating an Instance +Sub-classes **must** implement this, however they may throw if signing a +message is not supported. -_property: new ethers.Wallet(privateKey [ , provider ]) +_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 +binary data. + +For example, the string ``"0x1234"`` is 6 characters long (and in +this case 6 bytes long). This is **not** equivalent to the array +``[ 0x12, 0x34 ]``, which is 2 bytes long. + +A common case is to sign a hash. In this case, if the hash is a +string, it **must** be converted to an array first, using the +[arrayify](utils-arrayify) utility function. + +_null: + +_property: signer.signTransaction(transactionRequest) => Promise> @ +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. + +_property: signer.sendTransaction(transactionRequest) => Promise<[[provider-transactionresponse]]> @ +This method populates the transactionRequest with missing fields, using +[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. + +_heading: Sub-Classes @ + +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. + +A sub-class **must** call ``super()``. + +_property: signer.checkTransaction(transactionRequest) => [[provider-transactionrequest]] @ @SRC TODO -_property: Wallet.fromEncryptedJson(json, password) +_property: signer.populateTransaction(transactionRequest) => Promise<[[provider-transactionrequest]]> @ @SRC TODO + +_subsection: Wallet @ @INHERIT<[[externally-owned-account]] and [[signer]]> @SRC + +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 ]) @ @SRC +Create a new Wallet instance for //privateKey// and optionally +connected to the //provider//. + +_property: ethers.Wallet.createRandom( [ options = { } ]) => [[wallet]] @ @SRC +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]]> @ @SRC +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.fromMnemonic(mnemonic [ , path, [ wordlist ] ]) => [[wallet]] +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 wordlist is not specified, the English Wordlist is used. + +_heading: Properties + +_property: wallet.address => string<[Address](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]] +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 +to the desired provider. + +_property: wallet.publicKey => string<[[datahexstring]]<65>> +The uncompressed public key for this Wallet represents. + +_heading: Methods + +_property: wallet.encrypt(password, [ options = { }, [ progress ] ]) => Promise + +Encrypt the wallet using //password// returning a Promise which resolves +to a JSON wallet. + + +_subsection: VoidSigner @ @INHERIT<[[signer]]> @SRC + +A **VoidSigner** is a simple Signer which cannot sign. + +It is useful as a read-only signer, when an API requires a +Signer as a parameter, but it is known only read-only operations +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]] +Create a new instance of a **VoidSigner** for //address//. + +_property: voidSigner.address => string<[Address](address)> +The address of this **VoidSigner**. + + +_subsection: ExternallyOwnedAccount @ + +_property: eoa.address => string<[Address](address)> + +The [[address]] of this EOA. + +_property: eoa.privateKey => string<[[datahexstring]]<32>> + +The privateKey of this EOA + +_property: eoa.mnemonic => string + +//Optional//. The account HD mnemonic, if it has one and can be determined. + +_property: eoa.path => string + +//Optional//. The account HD path, if it has one and can be determined. diff --git a/docs.wrm/api/utils/abi.wrm b/docs.wrm/api/utils/abi.wrm new file mode 100644 index 0000000000..9068e63c96 --- /dev/null +++ b/docs.wrm/api/utils/abi.wrm @@ -0,0 +1,242 @@ +_title: Application Binary Interface + +_section: Application Binary Interface + +Explain an ABI. + +_subsection: Formats + +_heading: JSON String ABI (Solidity Output JSON) + +The **JSON ABI Format** is the format that is +[output from the Solidity compiler](https://solidity.readthedocs.io/en/v0.6.0/using-the-compiler.html#output-description). + +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. + +The deserialied JSON string (which is a normal JavaScript Object) may +also be passed into any function which accepts a JSON String ABI. + +_heading: Humanb-Readable ABI + +The Human-Readable ABI was + +[article](https://blog.ricmoo.com/human-readable-contract-abis-in-ethers-js-141902f4d917) + +_heading: Output Formats @ @src + +Each [[abi-fragment]] and [[abi-paramtype]] may be output using its ``format`` +method. + +_property: utils.FragmentTypes.full => string + +This is a full human-readable string, including all parameter names, any +optional modifiers (e.g. ``indexed``, ``public``, etc) and white-space +to aid in human readabiliy. + +_property: utils.FragmentTypes.minimal => string + +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 . from](abi-fragment-from). + +_property: utils.FragmentTypes.json => string + +This returns a JavaScript Object which is safe to call ``JSON.stringify`` +on to create a JSON string. + +_property: utils.FragmentTypes.sighash => string + +This is a minimal output format, which is used by Solidity when computing a +signature hash or an event topic hash. + +_warning: Note + +The ``sighash`` format is **insufficient** to re-create the original [[abi-fragment]], +since it discards modifiers such as indexed, anonymous, stateMutability, etc. + + +_subsection: Fragment @ @SRC + +An ABI is a collection of **Fragments**, where each fragment specifies: + +- An Event +- A Function +- A Constructor + +_heading: Properties + +_property: fragment.name => string + +This is the name of the Event or Function. This will be null for +a [[abi-constructorfragment]]. + +_property: fragment.type => string + +This is a string which indicates the type of the [[abi-fragment]]. This +will be one of: + +- ``constructor`` +- ``event`` +- ``function`` + +_property: fragment.inputs => Array<[[abi-paramtype]]> + +This is an array of of each [[abi-paramtype]] for the input parameters to +the Constructor, Event of Function. + +_heading: Methods + +_property: utils.Fragment.from(objectOrString) => [[abi-fragment]] @ @SRC + +Returns a + +_property: utils.Fragment.isFragment(object) => boolean @ @SRC + +Tra lal al + + +_subsection: ConstructorFragment @ @INHERIT<[[abi-fragment]]> @SRC + +_heading: Properties + +_property: fragment.gas => [[bignumber]] + +This is the gas limit that should be used during deployment. It may be +null. + +_property: fragment.payable => boolean + +This is whether the constructor may receive ether during deployment as +an endowment (i.e. msg.value != 0). + +_property: fragment.stateMutability => string + +This is the state mutability of the constructor. It can be any of: + +- ``nonpayable`` +- ``payable`` + +_heading: Methods + +_property: utils.ConstructorFragment.from(objectOrString) => [[abi-constructorfragment]] @ @SRC + +Tra la la... + +_property: utils.ConstructorFragment.isConstructorFragment(object) => boolean @ @SRC + +Tra lal al + + +_subsection: EventFragment @ @INHERIT<[[abi-fragment]]> @SRC + +_heading: Properties + +_property: fragment.anonymous => boolean + +This is whether the event is anonymous. An anonymous Event does not inject its +topic hash as topic0 when creating a log. + +_heading: Methods + +_property: utils.EventFragment.from(objectOrString) => [[abi-eventfragment]] @ @SRC + +Tra la la... + +_property: utils.EventFragment.isEventFragment(object) => boolean @ @SRC + +Tra lal al + + +_subsection: FunctionFragment @ @INHERIT<[[abi-constructorfragment]]> @SRC + +_heading: Properties + +_property: fragment.constant => boolean + +This is whether the function is constant (i.e. does not change state). This +is true if the state mutability is ``pure`` or ``view``. + +_property: fragment.stateMutability => string + +This is the state mutability of the constructor. It can be any of: + +- ``nonpayable`` +- ``payable`` +- ``pure`` +- ``view`` + +_property: fragment.outputs => Array<[[abi-paramtype]]> + +A list of the Function output parameters. + +_heading: Method + +_property: utils.FunctionFragment.from(objectOrString) => [[abi-functionfragment]] @ @SRC + +Tra la la... + +_property: utils.FunctionFragment.isFunctionFragment(object) => boolean @ @SRC + +Tra lal al + + +_subsection: ParamType @ @SRC + +The following examples will represent the Solidity parameter: + +``string foobar`` + +_heading: Properties + +_property: paramType.name => string @ + +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 @ + +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 @ + +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 +a tuple, it will be the string ``tuple``. + +_property: paramType.indexed => boolean @ + +Whether the parameter has been marked as indexed. This **only** applies +to parameters which are part of an [[abi-eventfragment]]. + +_property: paramType.arrayChildren => [[abi-paramtype]] @ + +The type of children of the array. This is null for for any parameter +wjhich is not an array. + +_property: paramType.arrayLength => number @ + +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]]> @ + +The components of a tuple. This is null for non-tuple parameters. + + +_heading: Methods + +Tra la la... + +_property: paramType.format([ outputType = "sighash" ]) + +Tra la la... + +_property: utils.ParamType.from(objectOrString) => [[abi-paramtype]] @ @SRC + +Tra la la... + +_property: utils.ParamType.isParamType(object) => boolean @ @SRC + +Tra la la... diff --git a/docs.wrm/api/utils/address.wrm b/docs.wrm/api/utils/address.wrm index 97a675a1ac..7ac22405de 100644 --- a/docs.wrm/api/utils/address.wrm +++ b/docs.wrm/api/utils/address.wrm @@ -1,15 +1,22 @@ _title: Addresses -_section: Addresses +_section: Addresses @ Explain addresses,formats and checksumming here. Also see: [constants.AddressZero](constants) -_heading: Functions +_subsection: Address Formats @ +_heading: Checksum Address @
+TODO -_property: utils.getAddress(address) => string @ @TS +_heading: ICAP Address @ +TODO + +_subsection: Functions + +_property: utils.getAddress(address) => string<[Address](address)> @ @SRC
Returns //address// as a Checksum Address. If //address// is an invalid 40-nibble [[hexstring]] or if it contains mixed case and @@ -18,13 +25,17 @@ the checksum is invalid, an InvalidArgument Error is throw. The value of //address// may be any supported address format. -_property: utils.isAddress(address) => boolean @ @TS +_property: utils.isAddress(address) => boolean @ @SRC
Returns true if //address// is valid (in any supported format). -_property: utils.getIcapAddress(address) => string @ @TS -Returns //address// as an ICAP address. Supports the same restrictions as -[utils.getAddress](utils-getAddress). +_property: utils.getIcapAddress(address) => string<[IcapAddress](address-icap)> @ @SRC
+Returns //address// as an [ICAP address](https://github.com/ethereum/wiki/wiki/Inter-exchange-Client-Address-Protocol-%28ICAP%29). +Supports the same restrictions as [utils.getAddress](utils-getAddress). -_property: utils.getContractAddress(transaction) => string @ @TS +_property: utils.getContractAddress(transaction) => string<[Address](address)> @ @SRC
Returns the contract address that would result if //transaction// was used to deploy a contract. + +_property: utils.getCreate2Address(from, salt, initCodeHash) => string<[Address](address)> @ @SRC
+Returns the contract address that would result from the given +[CREATE2](https://eips.ethereum.org/EIPS/eip-1014) call. diff --git a/docs.wrm/api/utils/bignumber.wrm b/docs.wrm/api/utils/bignumber.wrm index 42cd2492ce..b6864e0575 100644 --- a/docs.wrm/api/utils/bignumber.wrm +++ b/docs.wrm/api/utils/bignumber.wrm @@ -55,28 +55,28 @@ it represents. _heading: Math Operations -_property: bignumber.add(otherValue) => [[bignumber]] +_property: bignumber.add(otherValue) => [[bignumber]] @SRC Returns a BigNumber with the value of //bignumber// **+** //otherValue//. -_property: bignumber.sub(otherValue) => [[bignumber]] +_property: bignumber.sub(otherValue) => [[bignumber]] @SRC Returns a BigNumber with the value of //bignumber// **–** //otherValue//. -_property: bignumber.mul(otherValue) => [[bignumber]] +_property: bignumber.mul(otherValue) => [[bignumber]] @SRC Returns a BigNumber with the value of //bignumber// **×** //otherValue//. -_property: bignumber.div(divisor) => [[bignumber]] +_property: bignumber.div(divisor) => [[bignumber]] @SRC Returns a BigNumber with the value of //bignumber// **÷** //divisor//. -_property: bignumber.mod(divisor) => [[bignumber]] +_property: bignumber.mod(divisor) => [[bignumber]] @SRC Returns a BigNumber with the value of the **remainder** of //bignumber// ÷ //divisor//. -_property: bignumber.pow(exponent) => [[bignumber]] +_property: bignumber.pow(exponent) => [[bignumber]] @SRC Returns a BigNumber with the value of //bignumber// to the power of //exponent//. -_property: bignumber.abs() => [[bignumber]] +_property: bignumber.abs() => [[bignumber]] @SRC Returns a BigNumber with the absolute value of //bignumber//. -_property: bignumber.maskn(bitcount) => [[bignumber]] +_property: bignumber.maskn(bitcount) => [[bignumber]] @SRC Returns a BigNumber with the value of //bignumber// with bits beyond the //bitcount// least significant bits set to zero. @@ -88,53 +88,53 @@ 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]] +_property: bignumber.fromTwos(bitwidth) => [[bignumber]] @SRC Returns a BigNumber with the value of //bignumber// converted from twos-compliment with //bitwidth//. -_property: bignumber.toTwos(bitwidth) => [[bignumber]] +_property: bignumber.toTwos(bitwidth) => [[bignumber]] @SRC Returns a BigNumber with the value of //bignumber// converted to twos-compliment with //bitwidth//. _heading: Comparison and Equivalence -_property: bignumber.eq(otherValue) => boolean +_property: bignumber.eq(otherValue) => boolean @SRC Returns true if and only if the value of //bignumber// is equal to //otherValue//. -_property: bignumber.lt(otherValue) => boolean +_property: bignumber.lt(otherValue) => boolean @SRC Returns true if and only if the value of //bignumber// **<** //otherValue//. -_property: bignumber.lte(otherValue) => boolean +_property: bignumber.lte(otherValue) => boolean @SRC Returns true if and only if the value of //bignumber// **≤** //otherValue//. -_property: bignumber.gt(otherValue) => boolean +_property: bignumber.gt(otherValue) => boolean @SRC Returns true if and only if the value of //bignumber// **>** //otherValue//. -_property: bignumber.gte(otherValue) => boolean +_property: bignumber.gte(otherValue) => boolean @SRC Returns true if and only if the value of //bignumber// **≥** //otherValue//. -_property: bignumber.isZero() => boolean +_property: bignumber.isZero() => boolean @SRC Returns true if and only if the value of //bignumber// is zero. _heading: Conversion -_property: bignumber.toNumber() => number +_property: bignumber.toNumber() => number @SRC 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 +_property: bignumber.toString() => string @SRC Returns the value of //bignumber// as a base-10 string. -_property: bignumber.toHexString() => string +_property: bignumber.toHexString() => string<[[datahexstring]]> @SRC Returns the value of //bignumber// as a base-16, `0x`-prefixed [hexstring](hexstring). _heading: Inspection -_property: BigNumnber.isBigNumber(object) => boolean +_property: BigNumnber.isBigNumber(object) => boolean @SRC Returns true if and only if the //object// is a BigNumber object. diff --git a/docs.wrm/api/utils/bytes.wrm b/docs.wrm/api/utils/bytes.wrm index b59d7cf930..6ab39715a8 100644 --- a/docs.wrm/api/utils/bytes.wrm +++ b/docs.wrm/api/utils/bytes.wrm @@ -27,20 +27,27 @@ binary data as a string. _heading: Hexstring @ -A **hexstring** is a string which has a ``0x`` prefix followed by any +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 @ - **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](https://link_here) of the **(r, s)** and **v** +- **_vs** --- The [compact representation](https://eips.ethereum.org/EIPS/eip-2098) of the **s** and **v** - **recoveryParam** --- The normalized (i.e. 0 or 1) value of **v** +_heading: Flat-Format Signature @ + +A **Flat-Format Signature** is a common Signature format where +the r, s and v are concanenated into a 65 byte (130 nibble) +[[datahexstring]]. + + _heading: SignatureLike @ A **SignatureLike** is similar to a [[signature]], except redundant properties -may be omitted. +may be omitted or it may be a [[signature-flat]]. 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 @@ -49,13 +56,13 @@ missing values can be computed). _subsection: Inspection -_property: utils.isBytes(object) => boolean @ @TS +_property: utils.isBytes(object) => boolean @ @SRC Returns true if and only if //object// is a valid [[bytes]]. -_property: utils.isBytesLike(object) => boolean @ @TS +_property: utils.isBytesLike(object) => boolean @ @SRC Returns true if and only if //object// is a [[bytes]] or [[datahexstring]]. -_property: utils.isHexString(object, [ length ] ) => boolean @ @TS +_property: utils.isHexString(object, [ length ] ) => boolean @ @SRC Returns true if and only if //object// is a valid hex string. If //length// is specified and //object// is not a valid [[datahexstring]] of //length// bytes, an InvalidArgument error is thrown. @@ -63,13 +70,13 @@ If //length// is specified and //object// is not a valid [[datahexstring]] of _subsection: Converting between Arrays and Hexstrings -_property: utils.arrayify(datahexstringOrArrayish [ , options ]) => Uint8Array @ @TS +_property: utils.arrayify(datahexstringOrArrayish [ , options ]) => Uint8Array @ @SRC Converts //datahexstringOrArrayish// to a Uint8Array. -_property: utils.hexlify(hexstringOrArrayish) => string @ @TS +_property: utils.hexlify(hexstringOrArrayish) => string<[[datahexstring]]> @ @SRC Converts //hexstringOrArrayish// to a [[datahexstring]]. -_property: utils.hexValue(aBigNumberish) => string @ @TS +_property: utils.hexValue(aBigNumberish) => string<[[hexstring]]> @ @SRC Converts //aBigNumberish// to a [[hexstring]], with no __unnecessary__ leading zeros. @@ -80,13 +87,13 @@ _code: bytes-conversion.js _subsection: Array Manipulation -_property: utils.concat(arrayOfBytesLike) => Uint8Array @ @TS +_property: utils.concat(arrayOfBytesLike) => Uint8Array @ @SRC Concatenates all the [[byteslike]] in //arrayOfBytesLike// into a single Uint8Array. -_property: utils.stripZeros(aBytesLike) => Uint8Array @ @TS +_property: utils.stripZeros(aBytesLike) => Uint8Array @ @SRC Returns a Uint8Array with all leading ``0`` bytes of //aBtyesLike// removed. -_property: utils.zeroPad(aBytesLike, length) => Uint8Array @ @TS +_property: utils.zeroPad(aBytesLike, length) => Uint8Array @ @SRC Retutns a Uint8Array of the data in //aBytesLike// with ``0`` bytes prepended to //length// bytes long. @@ -96,22 +103,22 @@ error will be thrown. _subsection: Hexstring Manipulation -_property: utils.hexConcat(arrayOfBytesLike) => [[datahexstring]] @ @TS +_property: utils.hexConcat(arrayOfBytesLike) => string<[[datahexstring]]> @ @SRC Concatenates all the [[byteslike]] in //arrayOfBytesLike// into a single [[datahexstring]] -_property: utils.hexDataLength(aBytesLike) => [[datahexstring]] @ @TS +_property: utils.hexDataLength(aBytesLike) => string<[[datahexstring]]> @ @SRC Returns the length (in bytes) of //aBytesLike//. -_property: utils.hexDataSlice(aBytesLike, offset [ , endOffset ] ) => [[datahexstring]] @ @TS +_property: utils.hexDataSlice(aBytesLike, offset [ , endOffset ] ) => string<[[datahexstring]]> @ @SRC Returns a [[datahexstring]] representation of a slice of //aBytesLike//, from //offset// (in bytes) to //endOffset// (in bytes). If //endOffset// is omitted, the length of //aBytesLike// is used. -_property: utils.hexStripZeros(aBytesLike) => [[hexstring]] @ @TS +_property: utils.hexStripZeros(aBytesLike) => string<[[hexstring]]> @ @SRC Returns a [[hexstring]] representation of //aBytesLike// with all leading zeros removed. -_property: utils.hexZeroPad(aBytesLike, length) => [[datahexstring]] @ @TS +_property: utils.hexZeroPad(aBytesLike, length) => string<[[datahexstring]]> @ @SRC Returns a [[datahexstring]] representation of //aBytesLike// padded to //length// bytes. If //aBytesLike// is already longer than //length// bytes long, an InvalidArgument @@ -120,11 +127,11 @@ error will be thrown. _subsection: Signature Conversion -_property: utils.joinSignature(aSignatureLike) => [[datahexstring]] @ @TS +_property: utils.joinSignature(aSignatureLike) => string<[FlatSignature](signature-flat)> @ @SRC Return the flat-format of //aSignaturelike//, which is 65 bytes (130 nibbles) long, concatenating the **r**, **s** and (normalized) **v** of a Signature. -_property: utils.splitSignature(aSignatureLikeOrBytesLike) => [[signature]] @ @TS +_property: utils.splitSignature(aSignatureLikeOrBytesLike) => [[signature]] @ @SRC Return the full expanded-format of //aSignaturelike// or a flat-format [[datahexstring]]. Any missing properties will be computed. diff --git a/docs.wrm/api/utils/constants.wrm b/docs.wrm/api/utils/constants.wrm index 0823da578d..7c64c0e2bc 100644 --- a/docs.wrm/api/utils/constants.wrm +++ b/docs.wrm/api/utils/constants.wrm @@ -11,38 +11,38 @@ _code: constants-import.js _subsection: Bytes -_property: constants.AddressZero => [[datahexstring]] @ @TS +_property: constants.AddressZero => string<[Address](address)> @ @SRC The Address Zero, which is 20 bytes (40 nibbles) of zero. -_property: constants.HashZero => [[datahexstring]] @ @TS +_property: constants.HashZero => string<[[datahexstring]]<32>> @ @SRC The Hash Zero, which is 32 bytes (64 nibbles) of zero. _subsection: Strings -_property: constants.EtherSymbol => string @ @TS +_property: constants.EtherSymbol => string @ @SRC The Ether symbol, **Ξ**. _subsection: BigNumber -_property: constants.NegativeOne => [[bignumber]] @ @TS +_property: constants.NegativeOne => [[bignumber]] @ @SRC The BigNumber value representing ``"-1"``. -_property: constants.Zero => [[bignumber]] @ @TS +_property: constants.Zero => [[bignumber]] @ @SRC The BigNumber value representing ``"0"``. -_property: constants.One => [[bignumber]] @ @TS +_property: constants.One => [[bignumber]] @ @SRC The BigNumber value representing ``"1"``. -_property: constants.Two => [[bignumber]] @ @TS +_property: constants.Two => [[bignumber]] @ @SRC The BigNumber value representing ``"2"``. -_property: constants.WeiPerEther => [[bignumber]] @ @TS +_property: constants.WeiPerEther => [[bignumber]] @ @SRC The BigNumber value representing ``"1000000000000000000"``, which is the number of Wei per Ether. -_property: constants.MaxUint256 => [[bignumber]] @ @TS +_property: constants.MaxUint256 => [[bignumber]] @ @SRC The BigNumber value representing the maximum ``uint256`` value. diff --git a/docs.wrm/api/utils/display-logic.wrm b/docs.wrm/api/utils/display-logic.wrm index 560fc040c2..31af22d5ba 100644 --- a/docs.wrm/api/utils/display-logic.wrm +++ b/docs.wrm/api/utils/display-logic.wrm @@ -46,23 +46,23 @@ _subsection: Functions _heading: Formatting -_property: utils.commify(value) => string @ @TS +_property: utils.commify(value) => string @ @SRC Returns a string with value grouped by 3 digits, separated by ``,``. _heading: Conversion @ -_property: utils.formatUnits(value [ , unit = "ether" ] ) => string @ @TS +_property: utils.formatUnits(value [ , unit = "ether" ] ) => string @ @SRC Returns a string representation of //value// formatted with //unit// digits (if it is a number) or to the unit specified (if a string). -_property: utils.formatEther(value) => string @ @TS +_property: utils.formatEther(value) => string @ @SRC The equivalent to calling ``formatUnits(value, "ether")``. -_property: utils.parseUnits(value [ , unit = "ether" ] ) => [BigNumber](bignumber) @ @TS +_property: utils.parseUnits(value [ , unit = "ether" ] ) => [BigNumber](bignumber) @ @SRC Returns a [BigNumber](bignumber) representation of //value//, parsed with //unit// digits (if it is a number) or from the unit specified (if a string). -_property: utils.parseEther(value) => [BigNumber](bignumber) @ @TS +_property: utils.parseEther(value) => [BigNumber](bignumber) @ @SRC The equivalent to calling ``parseUnits(value, "ether")``. diff --git a/docs.wrm/api/utils/encoding.wrm b/docs.wrm/api/utils/encoding.wrm new file mode 100644 index 0000000000..a7c93169b9 --- /dev/null +++ b/docs.wrm/api/utils/encoding.wrm @@ -0,0 +1,21 @@ +_title: Encoding Utilies + +_section: Encoding Utilities + +_property: utils.base58.decode(textData) => Uin8Array + +Return a typed Uint8Array representation of //textData// decoded using +base-58 encoding. + +_property: utils.base58.encode(aBytesLike) => string + +Return //aBytesLike// encoded as a string using the base-58 encoding. + +_property: utils.base64.decode(textData) => Uin8Array + +Return a typed Uint8Array representation of //textData// decoded using +base-64 encoding. + +_property: utils.base64.encode(aBytesLike) => string + +Return //aBytesLike// encoded as a string using the base-64 encoding. diff --git a/docs.wrm/api/utils/fixednumber.wrm b/docs.wrm/api/utils/fixednumber.wrm index 4267212d46..48f005bd84 100644 --- a/docs.wrm/api/utils/fixednumber.wrm +++ b/docs.wrm/api/utils/fixednumber.wrm @@ -2,12 +2,51 @@ _title: Fixed Number _section: FixedNumber @ +_subsection: FixedFormat @ -_subsection: Types +A **FixedFormat** is a simple object which represents a decimal +(base-10) Fixed-Point data representation. Usually using this +class directly is uneccessary, as passing in a [[fixedformatstring]] +directly into the [[fixednumber]] will automatically create this. +_heading: Format Strings @ + +A format string is composed of three components, including signed-ness, +bit-width and number of decimals. + +A signed format string begins with ``fixed``, which an unsigned format +string begins with ``ufixed``, followed by the width (in bits) and the +number of decimals. + +The width must be conguent to 0 mod 8 (i.e. ``(width % 8) == 0``) and no +larger than 256 bits and the number of decimals must be no larger than 80. + +For example: + +- **fixed128x18** is signed, 128 bits wide and has 18 decimals; this is useful for most purposes +- **fixed32x0** is signed, 32 bits wide and has 0 decimals; this would be the same as a ``int32_t` in C +- **ufixed32x0** is unsigned, 32 bits wide and has 0 decimals; this would be the same as a ``uint32_t` in C +- **fixed** is shorthand for ``fixed128x18` +- **ufixed** is shorthand for ``ufixed128x18` + +_heading: Creating Instances + +_property: FixedFormat.from(value = "fixed128x18") => [[fixedformat]] @ @SRC + +Returns a new instance of a **FixedFormat** defined by //value//. Any valid [[fixedformatstring]] +may be passed in as well as any object which has any of ``signed``, ``width`` and ``decimals`` +defined, including a [[fixedformat]] object. + +_heading: Properties + +_property: fixedFormat.signed => boolean + +_property: fixedFormat.width => number + +_property: fixedFormat.decimals => number + +_property: fixedFormat.name => string -_heading: FixedFormat @ -TODO _definition: **//"fixed"//** A shorthand for ``fixed128x80``. @@ -17,17 +56,17 @@ _subsection: Creating Instances The FixedNumber constructor cannot be called directly. There are several static methods for creating a FixedNumber. -_property: BigNumber.from(value [ , format = "fixed" ] ) => [[fixednumber]] +_property: FixedNumber.from(value [ , format = "fixed" ] ) => [[fixednumber]] @SRC Returns an instance of a **FixedNumber** for //value// as a //format//. -_property: BigNumber.fromBytes(aBytesLike [ , format = "fixed" ] ) => [[fixednumber]] +_property: FixedNumber.fromBytes(aBytesLike [ , format = "fixed" ] ) => [[fixednumber]] @SRC Returns an instance of a **FixedNumber** for //value// as a //format//. -_property: BigNumber.fromString(value [ , format = "fixed" ] ) => [[fixednumber]] +_property: FixedNumber.fromString(value [ , format = "fixed" ] ) => [[fixednumber]] @SRC Returns an instance of a **FixedNumber** for //value// as a //format//. The //value// must not contain more decimals than the //format// permits. -_property: BigNumber.fromValue(value [ , decimals = 0 [ , format = "fixed" ] ] ) => [[fixednumber]] +_property: FixedNumber.fromValue(value [ , decimals = 0 [ , format = "fixed" ] ] ) => [[fixednumber]] @SRC Returns an instance of a **FixedNumber** for //value// with //decimals// as a //format//. @@ -41,40 +80,40 @@ _subsection: Methods _heading: Math Operations -_property: fixednumber.addUnsafe(otherValue) => [[fixednumber]] +_property: fixednumber.addUnsafe(otherValue) => [[fixednumber]] @SRC Returns a new FixedNumber with the value of //fixedvalue// **+** //otherValue//. -_property: fixednumber.subUnsafe(otherValue) => [[fixednumber]] +_property: fixednumber.subUnsafe(otherValue) => [[fixednumber]] @SRC Returns a new FixedNumber with the value of //fixedvalue// **–** //otherValue//. -_property: fixednumber.mulUnsafe(otherValue) => [[fixednumber]] +_property: fixednumber.mulUnsafe(otherValue) => [[fixednumber]] @SRC Returns a new FixedNumber with the value of //fixedvalue// **×** //otherValue//. -_property: fixednumber.divUnsafe(otherValue) => [[fixednumber]] +_property: fixednumber.divUnsafe(otherValue) => [[fixednumber]] @SRC Returns a new FixedNumber with the value of //fixedvalue// **÷** //otherValue//. -_property: fixednumber.round([ decimals = 0 ]) => [[fixednumber]] +_property: fixednumber.round([ decimals = 0 ]) => [[fixednumber]] @SRC Returns a new FixedNumber with the value of //fixedvalue// rounded to //decimals//. _heading: Conversion -_property: fixednumber.toFormat(format) => [[fixednumber]] +_property: fixednumber.toFormat(format) => [[fixednumber]] @SRC Returns a new FixedNumber with the value of //fixedvalue// with //format//. -_property: fixednumber.toHexString() => string +_property: fixednumber.toHexString() => string @SRC Returns a [Hexstring](hexstring) representation of //fixednumber//. -_property: fixednumber.toString() => string +_property: fixednumber.toString() => string @SRC Returns a string representation of //fixednumber//. -_property: fixednumber.toUnsafeFloat() => float +_property: fixednumber.toUnsafeFloat() => float @SRC Returns a floating-point JavaScript number value of //fixednumber//. Due to rounding in JavaScript numbers, the value is only approximate. _heading: Inspection -_property: BigNumber.isFixedNumber(value) => boolean +_property: FixedNumber.isFixedNumber(value) => boolean @SRC Returns true if and only if //value// is a **FixedNumber**. diff --git a/docs.wrm/api/utils/hashing.wrm b/docs.wrm/api/utils/hashing.wrm index 3f47bc36bb..65131f7a90 100644 --- a/docs.wrm/api/utils/hashing.wrm +++ b/docs.wrm/api/utils/hashing.wrm @@ -10,24 +10,24 @@ _subsection: Cryptographic Hashing The [Cryptographic Hash Functions](https://en.wikipedia.org/wiki/Cryptographic_hash_function) are a specific family of hash functions. -_property: utils.keccak256(aBytesLike) => [[datahexstring]] @ @TS +_property: utils.keccak256(aBytesLike) => string<[[datahexstring]]<32>> @ @SRC Returns the [KECCAK256](https://en.wikipedia.org/wiki/SHA-3) digest //aBytesLike//. -_property: utils.ripemd160(aBytesLike) => [[datahexstring]] @ @TS +_property: utils.ripemd160(aBytesLike) => string<[[datahexstring]]<20>> @ @SRC Returns the [RIPEMD-160](https://en.m.wikipedia.org/wiki/RIPEMD) digest of //aBytesLike//. -_property: utils.sha256(aBytesLike) => [[datahexstring]] @ @TS +_property: utils.sha256(aBytesLike) => string<[[datahexstring]]<32>> @ @SRC Returns the [SHA2-256](https://en.wikipedia.org/wiki/SHA-2) digest of //aBytesLike//. -_property: utils.sha512(aBytesLike) => [[datahexstring]] @ @TS +_property: utils.sha512(aBytesLike) => string<[[datahexstring]]<64>> @ @SRC Returns the [SHA2-512](https://en.wikipedia.org/wiki/SHA-2) digest of //aBytesLike//. -_property: utils.computeHmac(algorithm, key, data) => [[datahexstring]] @ @TS +_property: utils.computeHmac(algorithm, key, data) => string<[[datahexstring]]> @ @SRC Returns the [HMAC](https://en.wikipedia.org/wiki/HMAC) of //data// with //key// using the [Algorithm](supported-algorithm) //algorithm//. -_heading: HMAC Supported Algorithms @ +_heading: HMAC Supported Algorithms @ @SRC _property: utils.SupportedAlgorithms.sha256 => string Use the [SHA2-256](https://en.wikipedia.org/wiki/SHA-2) hash algorithm. @@ -38,15 +38,15 @@ Use the [SHA2-512](https://en.wikipedia.org/wiki/SHA-2) hash algorithm. _subsection: Common Hashing Helpers -_property: utils.hashMessage(message) => [[datahexstring]] @ @TS +_property: utils.hashMessage(message) => string<[[datahexstring]]<32>> @ @SRC Computes the Ethereum message digest of //message//. Ethereum messages are converted to UTF-8 bytes and prefixed with ``\x19Ethereum Signed Message:`` and the length of //message//. -_property: utils.id(text) => [[datahexstring]] @ @TS +_property: utils.id(text) => string<[[datahexstring]]<32>> @ @SRC The Ethereum Identity function computs the keccak256 hash of the //text// bytes. -_property: utils.namehash(name) => [[datahexstring]] @ @TS +_property: utils.namehash(name) => string<[[datahexstring]]<32>> @ @SRC Returns the [ENS Namehash](https://docs.ens.domains/contract-api-reference/name-processing#hashing-names) of //name//. @@ -56,15 +56,15 @@ 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: utils.solidityPack(arrayOfTypes, arrayOfValues) => [[datahexstring]] @ @TS +_property: utils.solidityPack(arrayOfTypes, arrayOfValues) => string<[[datahexstring]]> @ @SRC Returns the non-standard encoded //arrayOfValues// packed according to their respecive type in //arrayOfTypes//. -_property: utils.solidityKeccak256(arrayOfTypes, arrayOfValues) => [[datahexstring]] @ @TS +_property: utils.solidityKeccak256(arrayOfTypes, arrayOfValues) => string<[[datahexstring]]<32>> @ @SRC Returns the KECCAK256 of the non-standard encoded //arrayOfValues// packed according to their respective type in //arrayOfTypes//. -_property: utils.soliditySha256(arrayOfTypes, arrayOfValues) => [[datahexstring]] @ @TS +_property: utils.soliditySha256(arrayOfTypes, arrayOfValues) => string<[[datahexstring]]<32>> @ @SRC Returns the SHA2-256 of the non-standard encoded //arrayOfValues// packed according to their respective type in //arrayOfTypes//. diff --git a/docs.wrm/api/utils/index.wrm b/docs.wrm/api/utils/index.wrm index d84af62e6d..dad2863028 100644 --- a/docs.wrm/api/utils/index.wrm +++ b/docs.wrm/api/utils/index.wrm @@ -7,6 +7,7 @@ are also quite useful for application developers. _toc: address + abi bignumber bytes constants diff --git a/docs.wrm/api/utils/signing-key.wrm b/docs.wrm/api/utils/signing-key.wrm new file mode 100644 index 0000000000..89a728e908 --- /dev/null +++ b/docs.wrm/api/utils/signing-key.wrm @@ -0,0 +1,12 @@ +_title: Signing Keys + +_section: Signing Key + + +_property: ethers.utils.verifyMessage(message, signature) => string<[[address]]> @ @SRC +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 +will then be used to compute the address; this allows systems which use +the v to encode additional data (such as [EIP-155](https://eips.ethereum.org/EIPS/eip-155)) +to be used since the v parameter is still completely non-ambiguous. diff --git a/docs.wrm/api/utils/strings.wrm b/docs.wrm/api/utils/strings.wrm index e1522a9754..45c6a4319b 100644 --- a/docs.wrm/api/utils/strings.wrm +++ b/docs.wrm/api/utils/strings.wrm @@ -21,36 +21,37 @@ _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: utils.parseBytes32String(aBytesLike) => string @ @TS +_property: utils.parseBytes32String(aBytesLike) => string @ @SRC Returns the decoded string represented by the ``Bytes32`` encoded data. -_property: utils.formatBytes32String(text) => string @ @TS +_property: utils.formatBytes32String(text) => string<[[datahexstring]]<32>> @ @SRC Returns a ``bytes32`` string representation of //text//. If the length of //text// exceeds 31 bytes, it will throw an error. _subsection: UTF-8 Strings @ -_property: utils.toUtf8Bytes(text [ , form = current ] ) => Uint8Array @ @TS +_property: utils.toUtf8Bytes(text [ , form = current ] ) => Uint8Array @ @SRC Returns the UTF-8 bytes of //text//, optionally normalizing it using the [[unicode-normalization-form]] //form//. -_property: utils.toUtf8CodePoints(aBytesLike [ , form = current ] ) => Array @ @TS +_property: utils.toUtf8CodePoints(aBytesLike [ , form = current ] ) => Array @ @SRC Returns the Array of codepoints of //aBytesLike//, optionally normalizing it using the [[unicode-normalization-form]] //form//. -**Note:** This function correctly splits each user-perceived character into +_note: Note +This function correctly splits each **user-perceived character** into 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: utils.toUtf8String(aBytesLike [ , ignoreErrors = false ] ) => string @ @TS +_property: utils.toUtf8String(aBytesLike [ , ignoreErrors = false ] ) => string @ @SRC Returns the string represented by the UTF-8 bytes of //aBytesLike//. This will throw an error for invalid surrogates, overlong sequences or other UTF-8 issues, unless //ignoreErrors// is specified. -_heading: UnicodeNormalizationForm @ +_heading: UnicodeNormalizationForm @ @SRC There are several [commonly used forms](https://en.wikipedia.org/wiki/Unicode_equivalence) when normalizing UTF-8 data, which allow strings to be compared or hashed in a stable diff --git a/docs.wrm/cli/ens-help.txt b/docs.wrm/cli/ens-help.txt new file mode 100644 index 0000000000..be85a184a3 --- /dev/null +++ b/docs.wrm/cli/ens-help.txt @@ -0,0 +1,69 @@ +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. diff --git a/docs.wrm/cli/ens.wrm b/docs.wrm/cli/ens.wrm new file mode 100644 index 0000000000..a36279bf40 --- /dev/null +++ b/docs.wrm/cli/ens.wrm @@ -0,0 +1,13 @@ +_title: ENS + +_section: ENS + +_subsection: Help + +_code: ens-help.txt + +_heading: Examples + +TODO examples + + diff --git a/docs.wrm/cli/ethers-help.txt b/docs.wrm/cli/ethers-help.txt new file mode 100644 index 0000000000..6b698de791 --- /dev/null +++ b/docs.wrm/cli/ethers-help.txt @@ -0,0 +1,65 @@ +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. diff --git a/docs.wrm/cli/ethers-init.txt b/docs.wrm/cli/ethers-init.txt new file mode 100644 index 0000000000..49944e9537 --- /dev/null +++ b/docs.wrm/cli/ethers-init.txt @@ -0,0 +1,14 @@ +/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 diff --git a/docs.wrm/cli/ethers-mnemonic-hard.txt b/docs.wrm/cli/ethers-mnemonic-hard.txt new file mode 100644 index 0000000000..5188e3961b --- /dev/null +++ b/docs.wrm/cli/ethers-mnemonic-hard.txt @@ -0,0 +1,8 @@ +/home/ricmoo> ethers --account mnemonic.txt --xxx-mnemonic-password +Password (mnemonic; experimental - hard): ****** +Decrypting... 100% +network: homestead (chainId: 1) +homestead> accounts[0].getAddress() + +'0x56FC8792cC17971C19bEC4Ced978beEA44711EeD' +homestead> diff --git a/docs.wrm/cli/ethers-mnemonic.txt b/docs.wrm/cli/ethers-mnemonic.txt new file mode 100644 index 0000000000..40832c503f --- /dev/null +++ b/docs.wrm/cli/ethers-mnemonic.txt @@ -0,0 +1,7 @@ +/home/ricmoo> ethers --account public-mnemonic.txt --mnemonic-password +Password (mnemonic): ****** +network: homestead (chainId: 1) +homestead> accounts[0].getAddress() + +'0x6d3F723EC1B73141AA4aC248c3ab34A5a1DAD776' +homestead> diff --git a/docs.wrm/cli/ethers-script.txt b/docs.wrm/cli/ethers-script.txt new file mode 100644 index 0000000000..61fb235946 --- /dev/null +++ b/docs.wrm/cli/ethers-script.txt @@ -0,0 +1,19 @@ +# 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 diff --git a/docs.wrm/cli/ethers-send.txt b/docs.wrm/cli/ethers-send.txt new file mode 100644 index 0000000000..061430c432 --- /dev/null +++ b/docs.wrm/cli/ethers-send.txt @@ -0,0 +1,44 @@ +# 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 + diff --git a/docs.wrm/cli/ethers-sign.txt b/docs.wrm/cli/ethers-sign.txt new file mode 100644 index 0000000000..8668d8018f --- /dev/null +++ b/docs.wrm/cli/ethers-sign.txt @@ -0,0 +1,14 @@ +/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 diff --git a/docs.wrm/cli/ethers.wrm b/docs.wrm/cli/ethers.wrm new file mode 100644 index 0000000000..646df37891 --- /dev/null +++ b/docs.wrm/cli/ethers.wrm @@ -0,0 +1,59 @@ +_title: Sandbox Utility + +_section: Sandbox Utility + +The sandbox utility provides a simple way to use the most common +ethers utilities required during learning, debuging and managing +interactions with the Ethereum network. + +If no command is given, it will enter a REPL interface with many +of the ethers utilities already exposed. + +_subsection: Help + +_code: ethers-help.txt + +_subsection: Examples + +_heading: Creating Wallets @ + +_code: ethers-init.txt + +_heading: Sending Ether and Tokens @ + +_code: ethers-send.txt + +_heading: Signing Messages @ + +_code: ethers-sign.txt + +_heading: Scripting @ + +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 + +_heading: Using Mnemonics (with a password) @ + +All mnemonic phrases have a password, but the default is to use the empty +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 + +_heading: Using Mnemonics (with experimental memory-hard passwords) @ + +The ``-\-xxx-mnemonic-password`` is similar to the ``-\-mnemonic-password`` options, +which uses a password to decrypt the account for a mnemonic, however it passes +the password through the [scrypt](https:/\/en.wikipedia.org/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 + +_warning: Note +This is still an experimental feature (hence the ``xxx``). + diff --git a/docs.wrm/cli/index.wrm b/docs.wrm/cli/index.wrm new file mode 100644 index 0000000000..c74fd83408 --- /dev/null +++ b/docs.wrm/cli/index.wrm @@ -0,0 +1,9 @@ +_title: Command Line Interfaces + +_section: Command Line Interfaces + +_toc: + ethers + ens + typescript + plugin diff --git a/docs.wrm/cli/plugin.txt b/docs.wrm/cli/plugin.txt new file mode 100644 index 0000000000..b5f365d1e0 --- /dev/null +++ b/docs.wrm/cli/plugin.txt @@ -0,0 +1,10 @@ +/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" ] diff --git a/docs.wrm/cli/plugin.wrm b/docs.wrm/cli/plugin.wrm new file mode 100644 index 0000000000..1ceaf1ebc8 --- /dev/null +++ b/docs.wrm/cli/plugin.wrm @@ -0,0 +1,148 @@ +_title: Making Your Own + +_section: Making Your Own + +The //cli// library is meant to make it easy to create command +line utilities of your own. + +_subsection: CLI @ @SRC + +A **CLI** handles parsing all the command-line flags, options and arguments +and instantiates a [[cli-plugin]] to process the command. + +A **CLI** may support multiple [[cli-plugin]]'s in which case the first +argument is used to determine which to run (or if no arguments, the default +plugin will be selected) or may be designed to be standalone, in which case +exactly one [[cli-plugin]] will be used and no command argument is allowed. + + +_property: addPlugin(command, pluginClass) => void @ @SRC +Add a //plugin// class for the //command//. After all options and flags +have been consumed, the first argument will be consumed and the +associated plugin class will be instantiated and run. + +_property: setPlugin(pluginClass) => void @ @SRC +Set a dedicated [[cli-plugin]] class which will handle all input. This +may not be used in conjuction with addPlugin and will not automatically +accept a command from the arguments. + +_property: showUsage([ message = "" [ , status = 0 ] ]) => never @ @SRC +Shows the usage help screen for the CLI and terminates. + +_property: run(args) => Promise @ @SRC +Usually the value of //args// passed in will be ``process.argv.slice(2)``. + + +_subsection: Plugin @ @SRC + +Each **Plugin** manages each command of a CLI and is executed in phases. + +If the usage (i.e. help) of a CLI is requested, the static methods ``getHelp`` +and ``getOptionHelp`` are used to geneate the help screen. + +Otherwise, a plugin is instantiated and the ``prepareOptions`` is called. Each +plugin **must** call ``super.prepareOptions``, otherwise the basic options are +not yet processed. During this time a Plugin should consume all the flags and +options it understands, since any left over flags or options will cause the +CLI to bail and issue an //unknown option// error. This should throw if a value +for a given option is invalid or some combination of options and flags is not +allowed. + +Once the prepareOptions is complete (the returned promise is resolved), the ``prepareArguments`` +is called. This should validate the number of arguments is expected and throw +and error if there are too many or too few arguments or if any arguments do not +make sense. + +Once the prepareArguments is complete (the returned promise is resolved), the ``run`` +is called. + +_property: plugin.network => [[provider-network]] +The network this plugin is running for. + +_property: plugin.provider => [[provider]] +The provider for this plugin is running for. + +_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]] +The gas limit this plugin should use. This is null if unspecified. + +_property: plugin.gasPrice => [[bignumber]] +The gas price this plugin should use. This is null if unspecified. + +_property: plugin.nonce => number +The initial nonce for the account this plugin should use. + + +_heading: Methods + +_property: plugin.prepareOptions(argParser [ , verifyOnly = false ]) => Promise @ @SRC + +_property: plugin.prepareArgs(args) => Promise @ @SRC + +_property: plugin.run() => Promise @ @SRC + +_property: plugin.getAddress(addressOrName [ , message = "", [ allowZero = false ] ]) => Promise @ @SRC +A plugin should use this method to resolve an address. If the resovled address is +the zero address and //allowZero// is not true, an error is raised. + +_property: plugin.dump(header, info) => void @ @SRC +Dumps the contents of //info// to the console with a //header// in a nicely +formatted style. In the future, plugins may support a JSON output format +which will automatically work with this method. + +_property: plugin.throwUsageError([ message = "" ]) => never @ @SRC +Stops exectuion of the plugin and shows the help screen of the plugin with +the optional //message//. + +_property: plugin.throwError(message) => never @ @SRC +Stops execution of the plugin and shows //message//. + +_heading: Static Methods + +_property: Plugin.getHelp => Help @ @SRC +Each subclass should implement this static method which is used to +generate the help screen. + +_property: Plugin.getOptionHelp => Array @ @SRC +Each subclass should implement this static method if it supports +additional options which is used to generate the help screen. + + +_subsection: ArgParser @ @SRC + +The **ArgParser** is used to parse a command line into flags, options +and arguments. + +_code: plugin.txt + +Flags are simple binary options (such as the ``--yes``), which are true if present +otherwise false. + +Options require a single parameter follow them on the command line +(such as ``--account wallet.json``, which nhas the name ``account`` and the value +``wallet.json``) + +Arguments are all other values on the command line, and are not accessed through +the **ArgParser** directly. + +When a CLI is run, an **ArgParser** is used to validate the command line by using +prepareOptions, which consumes all flags and options leaving only the arguments +behind, which are then passed into prepareArgs. + +_property: argParser.consumeFlag(name) => boolean @ @SRC +Remove the flag //name// and return true if it is present. + +_property: argParser.consumeMultiOptions(names) => Array<{ name: string, value: string}> @ @SRC +Remove all options which match any name in the Array of //names// +with their values returning the list (in order) of values. + +_property: argParser.consumeOption(name) => string @ @SRC +Remove the option with its value for //name// and return the value. This +will throw a UsageError if the option is included multiple times. + +_property: argParser.consumeOptions(name) => Array @ @SRC +Remove all options with their values for //name// and return the list +(in order) of values. diff --git a/docs.wrm/cli/typescript-help.txt b/docs.wrm/cli/typescript-help.txt new file mode 100644 index 0000000000..9e98c6f2e6 --- /dev/null +++ b/docs.wrm/cli/typescript-help.txt @@ -0,0 +1,19 @@ +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. + + diff --git a/docs.wrm/cli/typescript.wrm b/docs.wrm/cli/typescript.wrm new file mode 100644 index 0000000000..47c72e9569 --- /dev/null +++ b/docs.wrm/cli/typescript.wrm @@ -0,0 +1,11 @@ +_title: TypeScript + +_section: TypeScript + +_subsection: Help + +_code: typescript-help.txt + +_subsection: Examples + +TODO diff --git a/docs.wrm/concepts/index.wrm b/docs.wrm/concepts/index.wrm index bf603b8496..82d15710d2 100644 --- a/docs.wrm/concepts/index.wrm +++ b/docs.wrm/concepts/index.wrm @@ -3,7 +3,8 @@ _title: Concepts _section: Concepts This is a very breif overview of some aspects of //Ethereum// -which developers can make use of or should be aware of. +and blockchains which developers can make use of or should +be aware of. _toc: events diff --git a/docs.wrm/config.js b/docs.wrm/config.js new file mode 100644 index 0000000000..74567fbbba --- /dev/null +++ b/docs.wrm/config.js @@ -0,0 +1,129 @@ +"use strict"; + +const { resolve } = require("path"); +const fs = require("fs"); + +const ts = require("typescript"); + +function getDefinitions(source) { + const sourceFile = ts.createSourceFile("filename.ts", source); + + const defs = [ ]; + + function add(type, name, pos) { + const lineNo = sourceFile.getLineAndCharacterOfPosition(pos).line + 1; + name = type + "." + name + defs.push({ type, name, lineNo }); + } + + let lastClass = null, lastEnum = null; + function visit(node, depth) { + if (ts.isConstructorDeclaration(node)) { + add("constructor", lastClass, node.body.pos); + } else if (ts.isFunctionDeclaration(node)) { + add("function", node.name.text, node.name.end); + } else if (ts.isConstructorDeclaration(node)) { + add("constructor", lastClass, node.pos); + } else if (ts.isClassDeclaration(node)) { + lastClass = node.name.escapedText; + add("class", lastClass, node.name.end); + } else if (ts.isMethodDeclaration(node)) { + if (lastClass == null) { throw new Error("missing class"); } + if (ts.hasStaticModifier(node)) { + add("staticmethod", (lastClass + "." + node.name.text), node.name.end); + } else { + add("method", (lastClass + "." + node.name.text), node.name.end); + } + } else if (ts.isEnumDeclaration(node)) { + lastEnum = node.name.escapedText; + add("enum", lastEnum, node.name.end); + } else if (ts.isEnumMember(node)) { + add("enum", (lastEnum + "." + node.name.escapedText), node.name.end); + } else if (ts.isVariableDeclaration(node)) { + if (depth === 3) { + add("var", node.name.escapedText, node.name.end); + } + } + ts.forEachChild(node, (node) => { return visit(node, depth + 1); }); + } + + visit(sourceFile, 0); + + return defs; +} + +const getSourceUrl = (function(path, include, exclude) { + console.log("Scanning TypeScript Sources..."); + const Link = "https://github.com/ethers-io/ethers.js/blob/ethers-v5-beta/packages$FILENAME#L$LINE"; + 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), defs: getDefinitions(source) } ] + } + + return [ ]; + } + + const defs = readdir(Root); + + return function getSourceUrl(key) { + const comps = key.split(":"); + if (comps.length !== 2) { throw new Error("unsupported key"); } + + const pathCheck = new RegExp("(^|[^a-zA-Z0-9_])" + comps[0].split("/").join("/(.*/)*") + "($|[^a-zA-Z0-9_])"); + + let match = comps[1]; + if (match.indexOf("(" /* fix: )*/)) { + match = new RegExp("(^|\\.)" + match.split("(" /* fix: ) */)[0] + "$"); + } else if (match[0] === "=") { + match = new RegExp("^" + match.substring(1) + "$"); + } else { + match = new RegExp("(^|\\.)" + match + "$"); + } + + const result = [ ]; + defs.forEach((def) => { + if (!def.filename.match(pathCheck)) { return; } + def.defs.forEach((d) => { + if (!d.name.match(match)) { return; } + result.push({ filename: def.filename, lineNo: d.lineNo }); + }); + }); + + if (result.length > 1) { + throw new Error(`Amibguous TypeScript link: ${ key } in [ ${ result.map((r) => JSON.stringify(r.filename + ":" + r.lineNo)).join(", ") }]`); + } else if (result.length === 0) { + throw new Error(`No matching TypeScript link: ${ key }`); + } + + return Link + .replace("$LINE", String(result[0].lineNo)) + .replace("$FILENAME", result[0].filename); + } +})("../packages/", new RegExp("packages/.*/src.ts/.*\.ts$"), new RegExp("/node_modules/|src.ts/.*browser.*")); + +module.exports = { + title: "ethers", + foo: "Bat", + subtitle: "v5.0-beta", + logo: "logo.svg", + link: "https://docs-beta.ethers.io", + markdown: { + "banner": "-----\n\nDocumentation: [html](https://docs-beta.ethers.io/)\n\n-----\n\n" + }, + getSourceUrl: getSourceUrl +}; diff --git a/docs.wrm/documentation/examples.txt b/docs.wrm/documentation/examples.txt index f9641fed20..c90639f0e2 100644 --- a/docs.wrm/documentation/examples.txt +++ b/docs.wrm/documentation/examples.txt @@ -18,7 +18,13 @@ _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 - -_definition and reset the indentation. diff --git a/docs.wrm/documentation/fragment.txt b/docs.wrm/documentation/fragment.txt index 8e7ad9cb74..ad28dc8305 100644 --- a/docs.wrm/documentation/fragment.txt +++ b/docs.wrm/documentation/fragment.txt @@ -1,7 +1,9 @@ -_DIRECTIVE: VALUE @ +_DIRECTIVE: VALUE @ @META BODY -DIRECTIVE: The directive name -VALUE: Optional; the value to pass to the directive -LINK: Optional; a name for internal linking -BODY: Optional; the directive body (certain directives only) +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) diff --git a/docs.wrm/documentation/index.wrm b/docs.wrm/documentation/index.wrm index aa08120026..3388748ff5 100644 --- a/docs.wrm/documentation/index.wrm +++ b/docs.wrm/documentation/index.wrm @@ -10,7 +10,7 @@ A lot of its inspiration came from [Read the Docs](https://github.com/readthedoc the [Sphinx](https://www.sphinx-doc.org/) project. -_subsection: Fragments +_subsection: Fragments @ Flatworm Docs are made up of fragments. A fragment is either a lone body of [markdown](flatworm-markdown) text, or a @@ -49,6 +49,12 @@ _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. @@ -73,7 +79,6 @@ _heading: Examples _code: examples.txt - _subsection: Markdown @ The markdown is simple and does not have the flexibility of @@ -83,3 +88,39 @@ supporting [links](flatworm-markdown) and lists. _code: markdown.txt + +_subsection: Configuration @ + +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 @ + +_heading: @INHERIT\ + +Adds an inherits description to a directive. The //markdown// may contain links. + +This extended directive function is available for: + +- _section +- _subsetion +- _heading + +_heading: @SRC\ + +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 diff --git a/docs.wrm/index.wrm b/docs.wrm/index.wrm index 5f01d4163f..f5c6023e10 100644 --- a/docs.wrm/index.wrm +++ b/docs.wrm/index.wrm @@ -42,6 +42,7 @@ _toc: getting-started concepts api + cli cookbook migration testing