CHANGELOG.md

@@ -3,6 +3,19 @@ Changelog
 
 This change log is managed by `scripts/cmds/update-versions` but may be manually updated.
 
+ethers/v5.0.3 (2020-06-29 00:50)
+--------------------------------
+
+  - Fixed typo in error string. ([7fe702d](https://github.com/ethers-io/ethers.js/commit/7fe702d59b0b81d2812e407b99a1e98e0e18ba03))
+  - Updated elliptic package to address possible malleability issue; which should not affect Ethereum. ([9e14345](https://github.com/ethers-io/ethers.js/commit/9e1434503e2a0280e9918c4eadb4d972b062b3b0))
+  - Fixed FixedNumber unguarded constructor and added isZero. ([#898](https://github.com/ethers-io/ethers.js/issues/898); [08c74e9](https://github.com/ethers-io/ethers.js/commit/08c74e9a132f37ab8cc3fb5dab3bd1fd708ee702))
+  - Added StaticJsonRpcProvider for reducing calls to chainId in certain cases. ([#901](https://github.com/ethers-io/ethers.js/issues/901); [c53864d](https://github.com/ethers-io/ethers.js/commit/c53864de0af55dd8ec8ca5681e78da380d85250a))
+  - Allow getDefaultProvider to accept a URL as a network. ([8c1ff4c](https://github.com/ethers-io/ethers.js/commit/8c1ff4c862b8cecb04c98d71910870e0b73867a0))
+  - Make network an optional parameter to WebSocketProvider. ([987b535](https://github.com/ethers-io/ethers.js/commit/987b5354cc18ed41620c43910ac163f358d91b5d))
+  - Removed deprecated errors package. ([f9e9347](https://github.com/ethers-io/ethers.js/commit/f9e9347e69133354c3d65c1f47475ddac8a793cf))
+  - Updated badges in docs. ([d00362e](https://github.com/ethers-io/ethers.js/commit/d00362eb706cfbf9911611e8d934260061cfbbd2))
+  - Create security policy. Create security policy. ([88e6849](https://github.com/ethers-io/ethers.js/commit/88e68495b67d9268ee66362b08c9b691d03ab58a))
+
 ethers/v5.0.2 (2020-06-13 21:36)
 --------------------------------
 

README.md

@@ -1,7 +1,7 @@
 The Ethers Project
 ==================
 
-[![npm (tag)](https://img.shields.io/npm/v/ethers/next)](https://www.npmjs.com/package/ethers/v/next)
+[![npm (tag)](https://img.shields.io/npm/v/ethers)](https://www.npmjs.com/package/ethers)
 [![Node.js CI](https://github.com/ethers-io/ethers.js/workflows/Node.js%20CI/badge.svg?branch=ethers-v5-beta)](https://github.com/ethers-io/ethers.js/actions?query=workflow%3A%22Node.js+CI%22)
 
 A complete Ethereum wallet implementation and utilities in JavaScript (and TypeScript).
@@ -38,13 +38,13 @@ Installing
 **node.js**
 
 ```
-/home/ricmoo/some_project> npm install --save ethers@next
+/home/ricmoo/some_project> npm install --save ethers
 ```
 
 **browser (UMD)**
 
 ```
-<script src="https://cdn.ethers.io/lib/ethers-5.0.umd.min.js" type="text/javasctipt">
+<script src="https://cdn.ethers.io/lib/ethers-5.0.umd.min.js" type="text/javascript">
 </script>
 ```
 
@@ -60,13 +60,13 @@ Installing
 Documentation
 -------------
 
-Browse the documentation online:
+Browse the [documentation](https://docs.ethers.io/v5/) online:
 
-- [Getting Started](https://docs.ethers.io/)
-- [Full API Documentation](https://docs.ethers.io/)
+- [Getting Started](https://docs.ethers.io/v5/getting-started/)
+- [Full API Documentation](https://docs.ethers.io/v5/api/)
 - [Various Ethereum Articles](https://blog.ricmoo.com/)
 
-Or browser the entire documentations as a [single page](https://docs.ethers.io/single-page/).
+Or browser the entire documentations as a [single page](https://docs.ethers.io/single-page/) to make searching easier.
 
 
 Ancillary Packages

SECURITY.md

@@ -0,0 +1,33 @@
+# Security Policy
+
+## Supported Versions
+
+Maintaining multiple versions of the library is quite time consuming, so
+the majority of the effort is focused on the latest major release.
+
+If you do require a version outside of this chart updated with patch fix,
+please [contact me](mailto:github@ricmoo.com).
+
+| Version | Supported                                  | Initial Release   |
+| ------- | ------------------------------------------ | ----------------- |
+| 5.0.x   | :white_check_mark:                         | 2020-06-12        |
+| 4.0.x   | :white_check_mark: (security patches only) | 2018-10-01        |
+| 3.0.x   | :x:                                        | 2018-03-05        |
+| 2.2.x   | :x:                                        | 2018-01-11        |
+| 2.1.x   | :x:                                        | 2017-05-22        |
+| 2.0.x   | :x:                                        | 2017-04-05        |
+| 1.0.x   | :x:                                        | 2016-08-23        |
+| 0.0.x   | :x:                                        | 2016-07-14        |
+
+
+## Reporting a Vulnerability
+
+If you identify a security vulnerability with this library (or any dependency),
+please do not hesitate to contact [github@ricmoo.com](mailto:github@ricmoo.com)
+immediately.
+
+I try to respond within the same day and will address any concern as quickly
+as possible (including code fixes and publishing to NPM).
+
+Any vulnerability will also be published to this file, along with credits,
+pertinent information and links to fixes.

admin/cmds/serve-docs.js

@@ -0,0 +1,100 @@
+const fs = require("fs");
+const http = require("http");
+const path = require("path");
+
+function getMime(filename) {
+    const comps = filename.split('.');
+    const ext = comps[comps.length - 1];
+    switch (ext.toLowerCase()) {
+        case 'css':      return 'text/css';
+        case 'doctree':  return 'application/x-doctree';
+        case 'eot':      return 'application/vnd.ms-fontobject';
+        case 'gif':      return 'image/gif';
+        case 'html':     return 'text/html';
+        case 'js':       return 'application/javascript';
+        case 'jpg':      return 'image/jpeg';
+        case 'jpeg':     return 'image/jpeg';
+        case 'md':       return 'text/markdown';
+        case 'pickle':   return 'application/x-pickle';
+        case 'png':      return 'image/png';
+        case 'svg':      return 'image/svg+xml';
+        case 'ttf':      return 'application/x-font-ttf';
+        case 'txt':      return 'text/plain';
+        case 'woff':     return 'application/font-woff';
+    }
+    console.log('NO MIME', filename);
+    return undefined;
+}
+
+function start(root, options) {
+    if (root == null) { throw new Error("root required"); }
+    if (options == null) { options = { }; }
+    if (options.port == null) { options.port = 8000; }
+    root = path.resolve(root);
+
+    const server = http.createServer((req, resp) => {
+
+        // Follow redirects in options
+        if (options.redirects && options.redirects[req.url]) {
+            resp.writeHead(301, { Location: options.redirects[req.url] });
+            resp.end();
+            return;
+        }
+
+        let filename = path.resolve(root, "." + req.url);
+
+        // Make sure we aren't crawling out of our sandbox
+        if (req.url[0] !== "/" || filename.substring(0, filename.length) !== filename) {
+            resp.writeHead(403);
+            resp.end();
+            return;
+        }
+
+        try {
+            const stat = fs.statSync(filename);
+            if (stat.isDirectory()) {
+
+                // Redirect bare directory to its path (i.e. "/foo" => "/foo/")
+                if (req.url[req.url.length - 1] !== "/") {
+                    resp.writeHead(301, { Location: req.url + "/" });
+                    resp.end();
+                    return;
+                }
+
+                filename += "/index.html";
+            }
+
+            const content = fs.readFileSync(filename);
+
+            resp.writeHead(200, {
+                "Content-Length": content.length,
+                "Content-Type": getMime(filename)
+            });
+            resp.end(content);
+            return;
+
+        } catch (error) {
+            if (error.code === "ENOENT") {
+                resp.writeHead(404, { });
+                resp.end();
+                return;
+            }
+
+            resp.writeHead(500, { });
+            resp.end();
+            return;
+        }
+    });
+
+    server.listen(options.port, () => {
+        console.log(`Listening on port: ${ options.port }`);
+    });
+
+    return server;
+}
+
+start(path.resolve(__dirname, "../../docs"), {
+    redirects: {
+        "/": "/v5/"
+    }
+});

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

@@ -82,7 +82,7 @@ _subsection: InfuraProvider @<InfuraProvider> @INHERIT<[[UrlJsonRpcProvider]]> @
 The **InfuraProvider** is backed by the popular [INFURA](link-infura)
 Ethereum service.
 
-_property: new ethers.providers.InfuraProvider([ network = "homestead", [ apiKey ] ])
+_property: new ethers.providers.InfuraProvider([ network = "homestead", [ apiKey ] ]) @SRC<providers>
 Create a new **InfuraProvider** connected to //network// with
 the optional //apiKey//.
 
@@ -96,6 +96,12 @@ specify a [Project Secret](link-infura-secret) which can be used
 on non-public sources (like on a server) to further secure your
 API access and quotas.
 
+_property: InfuraProvider.getWebSocketProvider([ network [ , apiKey ] ]) => [[WebSocketProvider]] @<InfuraProvider-getWebSocketProvider> @SRC<providers>
+Create a new [[WebSocketProvider]] using the INFURA web-socket endpoint
+to connect to //network// with the optional //apiKey//.
+
+The //network// and //apiKey// are specified the same as [the constructor](InfuraProvider).
+
 _note: Note: Default API keys
 If no //apiKey// is provided, a shared API key will be used,
 which may result in reduced performance and throttled requests.
@@ -136,6 +142,14 @@ provider = new InfuraProvider("homestead", {
     projectSecret: projectSecret
 });
 
+// Connect to the INFURA WebSocket endpoints with a WebSocketProvider
+provider = InfuraProvider.getWebSocketProvider()
+// <hide>
+provider._websocket.onopen = function(){
+    provider._websocket.close();
+};
+// </hide>
+
 
 _subsection: AlchemyProvider @<AlchemyProvider> @inherit<[[UrlJsonRpcProvider]]> @src<providers:class.AlchemyProvider>
 

docs.wrm/api/providers/other.wrm

@@ -93,7 +93,7 @@ The URL to use for the JsonRpcProvider instance.
 
 
 
-_subsection: Web3Provider @<Web3Provider> @INHERIT<[[JsonRpcProvider]]>
+_subsection: Web3Provider @<Web3Provider> @INHERIT<[[JsonRpcProvider]]> @SRC<providers:class.Web3Provider>
 
 The Web3Provider is meant to ease moving from a [web3.js based](link-web3)
 application to ethers by wraping an existing Web3-compatible (such as a
@@ -144,3 +144,20 @@ This is identical to ``sendAsync``. Historically, this used a synchronous
 web request, but no current browsers support this, so its use this way
 was deprecated quite a long time ago
 
+
+_subsection: WebSocketProvider @<WebSocketProvider> @INHERIT<[[JsonRpcProvider]]> @SRC<providers:class.WebSocketProvider>
+
+The **WebSocketProvider** connects to a JSON-RPC WebSocket-compatible backend
+which allows for a persistent connection, multiplexing requests and pub-sub
+events for a more immediate event dispatching.
+
+The WebSocket API is newer, and if running your own infrastructure, note that
+WebSockets are much more intensive on your server resourses, as they must manage
+and maintain the state for each client. For this reason, many services may also
+charge additional fees for using their WebSocket endpoints.
+
+_property: new ethers.provider.WebSockerProvider([ url [ , network ] ])
+Returns a new [[WebSocketProvider]] connected to //url// as the //network//.
+
+If //url// is unspecified, the default ``"ws:/\/localhost:8546"`` will be used.
+If //network// is unspecified, it will be queried from the network.

docs.wrm/contributing.wrm

@@ -1,4 +1,4 @@
-_section: Contributing and Hacking
+_section: Contributing and Hacking @<contributing>
 
 The ethers.js library is something that I've written out of necessity,
 and has grown somewhat organically over time.
@@ -25,14 +25,19 @@ have a public discussion and figure out the best way to address to problem/featu
 **:)**
 
 
-_subsection: Building
+_subsection: Building @<contributing--building>
 
-If you wish to modify the source code, there are a few steps involved in setting up
-your environment.
+If you wish to modify the source code, there are a few steps involved in
+setting up your environment.
 
-_code: Preparing the Package @lang<shell>
+Since the library uses a monorepo, you must install an initial required
+set of libraries, which can then be used to install the remaining libraries
+used within each package, as well as link all the packages within the repo
+with each other.
 
-# Clone the REPO
+_code: Preparing for builds @lang<shell>
+
+# Clone the repository
 /home/ricmoo> git clone git@github.com:ethers-io/ethers.js.git
 /home/ricmoo> cd ethers.js
 
@@ -44,6 +49,10 @@ _code: Preparing the Package @lang<shell>
 /home/ricmoo/ethers.js> npm run bootstrap
 
 
+_subsection: Making your changes @<contributing--updating>
+
+TODO: Add more information here.
+
 _code: Watching and Building @lang<shell>
 
 # Begin watching the files and re-building whenever they change
@@ -72,3 +81,65 @@ _code: Preparing the Distribution @lang<shell>
 
 /home/ricmoo/ethers.js> npm run update-version
 
+
+_subsection: Documentation @<contributing--documentation>
+
+The documents are generated using [Flatworm](flatworm) documentation
+generation tool, which was written for the purpose of writing the documentation
+for ethers.
+
+Style Guide (this section will have much more coming):
+
+- Try to keep lines no longer than //around// 80 characters
+- Avoid inline links in the source; use the ``externalLinks`` field in the config.js
+- Prefix external links with ``link-``
+- Changing an anchor name must be well justified, as it will break all existing links
+  to that section; flatworm will support symblinks in the future
+- In general, I aim for xonsistency; look to similar situations throughout the documentation
+
+
+_heading: Building
+
+To build the documentation, you should first follow the
+[above steps](contributing--building) to build the ethers library.
+
+Building the docs will generate several types of output:
+
+- A full set of HTML pages, linking across each other
+- A single one-page HTML page with all pages linking to local anchors
+- A full set of README.md pages organized to be browsable and linkable in GitHub
+- A metadata dump for tool ingestion (still needs more work)
+- (@TODO; only half done) The documentation as a LaTeX and generated PDF
+
+_code: Building the Documentations @lang<shell>
+
+/home/ricmoo/ethers.js> npm run build-docs
+
+
+_heading: Evaluation
+
+When building the documentation, all code samples are run through a JavaScript
+VM to ensure there are no typos in the example code, as well the exact output
+of results are injected into the output, so there is no need to keep the results
+and code in-sync.
+
+However, this can be a bit of a headache when making many small changes, so to
+build the documentation faster, you can skip the evaluation step, which will
+inject the code directly.
+
+_code: Build docs skipping evaluation @lang<shell>
+
+/home/ricmoo/ethers.js> npm run build-docs -- --skip-eval
+
+
+_heading: Previewing Changes
+
+To preview the changes locally, you can use any standard web server and run
+from the ``/docs/`` folder, or use the built-in web server.
+
+The same caveats as normal web development apply, such flushing browser
+caches after changing (and re-building) the docs.
+
+_code: Running a webserver @lang<shell>
+
+/home/ricmoo/ethers.js> npm run serve-docs

docs.wrm/documentation.wrm

@@ -1,4 +1,4 @@
-_section: Flatworm Docs
+_section: Flatworm Docs @<flatworm>
 
 The //Flatworm Docs// rendering engine is designed to be **very**
 simple, but provide enough formatting necessary for documenting
@@ -102,7 +102,7 @@ _definition: **_table:** //FOOTER//
 
 Creates a [Table](flatworm--table) structured according to the body.
 
-Each cell support and variables support markdown.
+Each cell contents supports markdown and variables supports markdown.
 
 **Extensions:** [@style](flatworm--ext-style)
 
@@ -173,7 +173,8 @@ This is placed in an orange box.
 
 
 \_null:
-This breaks out of a directive. For example, to end a
+This breaks out of a directive. For example, to end
+a ``_note:`` or ``_code:``.
 
 
 _subsection: Markdown @<flatworm-markdown>