Skip to content

Commit

Permalink
Updated docs.
Browse files Browse the repository at this point in the history
  • Loading branch information
ricmoo committed Jun 12, 2020
1 parent e1dce87 commit 9e4c7e6
Show file tree
Hide file tree
Showing 78 changed files with 2,124 additions and 1,750 deletions.
91 changes: 42 additions & 49 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,17 +1,35 @@
The Ethers Project
==================

**EXPERIMENTAL**
[![npm (tag)](https://img.shields.io/npm/v/ethers/next)](https://www.npmjs.com/package/ethers/v/next)
[![Node.js CI](https://github.com/ethers-io/ethers.js/workflows/Node.js%20CI/badge.svg?branch=ethers-v5-beta)](https://github.com/ethers-io/ethers.js/actions?query=workflow%3A%22Node.js+CI%22)

This branch is the next release of ethers.js, which should
be promoted to the official release shortly.
A complete Ethereum wallet implementation and utilities in JavaScript (and TypeScript).

I would recommend it for most new projects and personally use
it for my own projects.
**Features:**

The [new documentation](https://docs-beta.ethers.io) is still a
bit sparse, but is coming along as well and will be complete
before the promotion to master.
- Keep your private keys in your client, **safe** and sound
- Import and export **JSON wallets** (Geth, Parity and crowdsale)
- Import and export BIP 39 **mnemonic phrases** (12 word backup phrases) and **HD Wallets** (English as well as Czech, French, Italian, Japanese, Korean, Simplified Chinese, Spanish, Traditional Chinese)
- Meta-classes create JavaScript objects from any contract ABI, including **ABIv2** and **Human-Readable ABI**
- Connect to Ethereum nodes over [JSON-RPC](https://github.com/ethereum/wiki/wiki/JSON-RPC), [INFURA](https://infura.io), [Etherscan](https://etherscan.io), [Alchemy](https://alchemyapi.io) or [MetaMask](https://metamask.io)
- **ENS names** are first-class citizens; they can be used anywhere an Ethereum addresses can be used
- **Tiny** (~104kb compressed; 322kb uncompressed)
- **Modular** packages; include only what you need
- **Complete** functionality for all your Ethereum desires
- Extensive [documentation](https://docs.ethers.io/ethers.js/html/)
- Large collection of **test cases** which are maintained and added to
- Fully **TypeScript** ready, with definition files and full TypeScript source
- **MIT License** (including ALL dependencies); completely open source to do with as you please


Keep Updated
------------

For the latest news and advisories, please follow the [@ethersproject](https://twitter.com/ethersproject)
on Twitter (low-traffic, non-marketting, important information only) as well as watch this GitHub project.

For the latest changes, see the [CHANGELOG](https://github.com/ethers-io/ethers.js/blob/master/CHANGELOG.md).


Installing
Expand Down Expand Up @@ -39,57 +57,32 @@ Installing
```


Documentation
-------------

Browse the documentation online:

- [Getting Started](https://docs.ethers.io/)
- [Full API Documentation](https://docs.ethers.io/)
- [Various Ethereum Articles](https://blog.ricmoo.com/)

Or browser the entire documentations as a [single page](https://docs.ethers.io/single-page/).


Ancillary Packages
------------------

These are a number of packages not included in the umbrella `ethers ` npm package, and
These are a number of packages not included in the umbrella `ethers` npm package, and
additional packages are always being added. Often these packages are for specific
use-cases, so rather than adding them to the umbrella package, they are added as
ancillary packaged, which can be included by those who need them, while not bloating
everyone else with packages they do not need.

We will keep a list of useful pacakges here.

- `@ethersproject/experimental`
- `@ethersproject/cli`
- `@ethersproject/ens`
- `@ethersproject/ledger`
- `@ethersproject/trezor`


Hacking
-------

This project uses a combination of Lerna and the ./admin scripts to manage
itself as a package of packages.

The umbrella package can be found in `packages/ethers`, and all packages in general
can be found in the `packages/` folder.

If you add new dependencies to any package (incuding internal dependencies), you will
need to re-create the internal links and re-build teh dependency graph::

```
/home/ethers> npm run bootstrap
```

To run a continuous build (with incremental TypeScript compilation):

```
/home/ethers> npm run auto-build
```

Finally, once you have made all your changes, you will need to bump the version
of packages that changed their NPM tarballs, as well as update the _version.*
and distribution builds (which is what we host on the CDN for browser-based
apps). To do this, run:


```
/home/ethers> npm run update-versions
```

Which will also list all packages that have changed along with the specifc files.
- `@ethersproject/experimental` ([documentation](https://docs.ethers.io))
- `@ethersproject/cli` ([documentation](https://docs.ethers.io))
- `@ethersproject/hardware-wallets` ([documentation](https://docs.ethers.io))


License
Expand Down
3 changes: 0 additions & 3 deletions docs.wrm/config.js
Original file line number Diff line number Diff line change
Expand Up @@ -263,7 +263,4 @@ module.exports = {
"link-wiki-overflow": { name: "overflow", url: "https:/\/en.wikipedia.org/wiki/Integer_overflow" },
"link-wiki-underflow": { name: "arithmetic underflow", url: "https:/\/en.wikipedia.org/wiki/Arithmetic_underflow" },
},

redirectLinks: JSON.parse(fs.readFileSync(resolve(__dirname, "redirects.json"))),

};
113 changes: 113 additions & 0 deletions docs.wrm/generate-redirects.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,113 @@
const fs = require("fs");
const { resolve } = require("path");

const Content = `
<html>
<head>
<title>ethers.js - Legacy Documentation</title>
<style type="text/css">
html {
font-family: sans-serif;
}
h1 {
opacity: 0.8;
}
.content {
border: 2px solid #000;
border-radius: 7px;
box-shadow: 5px 5px 10px #aaa;
left: 50%;
padding: 20px;
position: absolute;
text-align: center;
transform: translate(-50%, 30px);
width: 700px;
}
.hr {
border-top: 1px solid black;
margin: 4px 10px 40px;
}
span.v5 {
font-size: 24px;
margin-bottom: 40px;
}
span.v4 {
opacity: 0.7;
}
</style>
</head>
<body>
<div class="content">
<h1>This link is out-of-date <i>and</i> has moved.</h1>
<div class="hr"></div>
<span class="v5">Click <a id="link-v5" href="%%DEFAULT%%">here</a> to visit the updated documentation</span>
<br />
<br />
<br />
<span class="v4">or continue to the historic <a id="link-v4" href="%%LEGACY%%">legacy documentation</a>.</span>
</div>
<script type="text/javascript">
var redirects = %%REDIRECTS%%;
var hash = location.hash;
if (hash && hash !== "#") {
hash = hash.substring(1);
var v4 = document.getElementById("link-v4");
v4.setAttribute("href", v4.getAttribute("href").split("#")[0] + "#" + hash);
var target = redirects[hash];
if (target) {
var v5 = document.getElementById("link-v5");
v5.setAttribute("href", target);
}
}
</script>
</body>
</html>`

const redirects = require("./redirects.json");
const links = require("../docs/v5/metadata.json").links;

const result = { };

const prefix = "ethers.js/html/";
Object.keys(redirects).forEach((uri) => {
if (uri.substring(0, prefix.length) !== prefix) { return; }

const comps = uri.substring(prefix.length).split("#");
const filename = comps[0];
const hash = comps[1] || "_";
const tag = redirects[uri];

let path = null;
if (tag.path) {
path = tag.path;
} else if (tag.tag) {
path = links[tag.tag] || null;
} else {
console.log("Missing tag:", uri);
return;
}

if (!path) {
console.log("Missing path:", uri);
return;
}

if (!result[filename]) { result[filename] = {
"_legacy": `/v4/${ filename }`
}; }
result[filename][hash] = path;
});

function generateOutput(filename) {
const page = result[filename];
return Content.replace("%%DEFAULT%%", page._ || "/v5/")
.replace("%%LEGACY%%", page._legacy || "/v4/")
.replace("%%REDIRECTS%%", JSON.stringify(page));
}

Object.keys(result).forEach((filename) => {
const output = generateOutput(filename);
const path = resolve(__dirname, "../docs/ethers.js/html", filename);
fs.writeFileSync(path, output);
});

2 changes: 1 addition & 1 deletion docs.wrm/redirects.json
Original file line number Diff line number Diff line change
Expand Up @@ -414,7 +414,7 @@
"ethers.js/html/migration.html#waiting-for-transactions":
{ "tag": "" },
"ethers.js/html/notes.html":
{ "tag": "/v5/" },
{ "path": "/v5/" },
"ethers.js/html/notes.html#checksum-address":
{ "tag": "address-formats" },
"ethers.js/html/notes.html#contributing":
Expand Down
2 changes: 1 addition & 1 deletion docs/ethers.js/html/notes.html
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,7 @@ <h1>This link is out-of-date <i>and</i> has moved.</h1>
<span class="v4">or continue to the historic <a id="link-v4" href="/v4/notes.html">legacy documentation</a>.</span>
</div>
<script type="text/javascript">
var redirects = {"_legacy":"/v4/notes.html","checksum-address":"/v5/api/utils/address/#address-formats","contributing":"/v5/contributing/","icap-address":"/v5/api/utils/address/#address-formats","ieee754":"/v5/api/utils/bignumber/#BigNumber--notes-safenumbers","memory-hard-brute-force-encrpyting":"/v5/concepts/security/#security--pbkdf","responsible-disclosure":"/v5/contributing/","security":"/v5/concepts/security/","why-can-t-i-just-use-numbers":"/v5/api/utils/bignumber/#BigNumber--notes-safenumbers"};
var redirects = {"_legacy":"/v4/notes.html","_":"/v5/","checksum-address":"/v5/api/utils/address/#address-formats","contributing":"/v5/contributing/","icap-address":"/v5/api/utils/address/#address-formats","ieee754":"/v5/api/utils/bignumber/#BigNumber--notes-safenumbers","memory-hard-brute-force-encrpyting":"/v5/concepts/security/#security--pbkdf","responsible-disclosure":"/v5/contributing/","security":"/v5/concepts/security/","why-can-t-i-just-use-numbers":"/v5/api/utils/bignumber/#BigNumber--notes-safenumbers"};
var hash = location.hash;
if (hash && hash !== "#") {
hash = hash.substring(1);
Expand Down
2 changes: 1 addition & 1 deletion docs/v5/api/contract/contract-factory/index.html
Original file line number Diff line number Diff line change
Expand Up @@ -71,7 +71,7 @@
<div class="nav previous"><a href="/v5/api/contract/contract/"><span class="arrow">&larr;</span>Contract</a></div>
<div class="nav next"><a href="/v5/api/contract/example/">Example: ERC-20 Contract<span class="arrow">&rarr;</span></a></div>
</div>
<div class="copyright">The content of this site is licensed under the <a href="https://choosealicense.com/licenses/cc-by-4.0/">Creative Commons License</a>. Generated on June 12, 2020, 3:31am.</div>
<div class="copyright">The content of this site is licensed under the <a href="https://choosealicense.com/licenses/cc-by-4.0/">Creative Commons License</a>. Last modified on June 12, 2020, 7:17pm.</div>
</div>
<script src="/v5/static/script.js" type="text/javascript"></script>
</body>
Expand Down
2 changes: 1 addition & 1 deletion docs/v5/api/contract/contract/index.html
Original file line number Diff line number Diff line change
Expand Up @@ -109,7 +109,7 @@
<div class="nav previous"><a href="/v5/api/contract/"><span class="arrow">&larr;</span>Contract Interaction</a></div>
<div class="nav next"><a href="/v5/api/contract/contract-factory/">ContractFactory<span class="arrow">&rarr;</span></a></div>
</div>
<div class="copyright">The content of this site is licensed under the <a href="https://choosealicense.com/licenses/cc-by-4.0/">Creative Commons License</a>. Generated on June 12, 2020, 3:31am.</div>
<div class="copyright">The content of this site is licensed under the <a href="https://choosealicense.com/licenses/cc-by-4.0/">Creative Commons License</a>. Last modified on June 12, 2020, 7:17pm.</div>
</div>
<script src="/v5/static/script.js" type="text/javascript"></script>
</body>
Expand Down
53 changes: 27 additions & 26 deletions docs/v5/api/contract/example/index.html
Original file line number Diff line number Diff line change
Expand Up @@ -18,41 +18,42 @@

<a name="example-erc-20-contract"></a><h1 class="show-anchors"><div>Example: ERC-20 Contract<div class="anchors"><a class="self" href="/v5/api/contract/example/#example-erc-20-contract"></a></div></div></h1>
<a name="example-erc-20-contract--connecting-to-a-contract"></a><h2 class="show-anchors"><div>Connecting to a Contract<div class="anchors"><a class="self" href="/v5/api/contract/example/#example-erc-20-contract--connecting-to-a-contract"></a></div></div></h2>
<div class="code-title"><div>A simple ERC-20 contract</div></div><div class="code">// A Human-Readable ABI; any supported ABI format could be used
const abi = [
// Read-Only Functions
"function balanceOf(address owner) view returns (uint256)",
<div class="code-title"><div>A simple ERC-20 contract</div></div><div class="code"><span class="comment">// A Human-Readable ABI; any supported ABI format could be used
</span>const abi = [
<span class="comment"> // Read-Only Functions
</span> "function balanceOf(address owner) view returns (uint256)",
"function decimals() view returns (uint8)",
"function symbol() view returns (string)",

// Authenticated Functions
"function transfer(address to, uint amount) returns (boolean)",
<span class="comment"> // Authenticated Functions
</span> "function transfer(address to, uint amount) returns (boolean)",

// Events
"event Transfer(address indexed from, address indexed to, uint amount)"
<span class="comment"> // Events
</span> "event Transfer(address indexed from, address indexed to, uint amount)"
];

// This can be an address or an ENS name
const address = "dai.tokens.ethers.eth";
<span class="comment">// This can be an address or an ENS name
</span>const address = "dai.tokens.ethers.eth";

// An example Provider
const provider = ethers.getDefaultProvider();
<span class="comment">// An example Provider
</span>const provider = ethers.getDefaultProvider();

// An example Signer
const signer = ethers.Wallet.createRandom().connect(provider);
<span class="comment">// An example Signer
</span>const signer = ethers.Wallet.createRandom().connect(provider);

// Read-Only; By connecting to a Provider, allows:
// - Any constant function
// - Querying Filters
// - Populating Unsigned Transactions for non-constant methods
// - Estimating Gas for non-constant (as an anonymous sender)
// - Static Calling non-constant methods (as anonymous sender)
const erc20 = new ethers.Contract(address, abi, provider);
<span class="comment">// Read-Only; By connecting to a Provider, allows:
</span><span class="comment">// - Any constant function
</span><span class="comment">// - Querying Filters
</span><span class="comment">// - Populating Unsigned Transactions for non-constant methods
</span><span class="comment">// - Estimating Gas for non-constant (as an anonymous sender)
</span><span class="comment">// - Static Calling non-constant methods (as anonymous sender)
</span>const erc20 = new ethers.Contract(address, abi, provider);

// Read-Write; By connecting to a Signer, allows:
// - Everything from Read-Only (except as Signer, not anonymous)
// - Sending transactions for non-constant functions
const erc20_rw = new ethers.Contract(address, abi, signer)</div><a name="example-erc-20-contract--connecting-to-a-contract--erc20contract"></a><h3 class="show-anchors"><div>ERC20Contract<span class="inherits"> inherits <a href="/v5/api/contract/contract/">Contract</a></span><div class="anchors"><a class="self" href="/v5/api/contract/example/#example-erc-20-contract--connecting-to-a-contract--erc20contract"></a></div></div></h3>
<span class="comment">// Read-Write; By connecting to a Signer, allows:
</span><span class="comment">// - Everything from Read-Only (except as Signer, not anonymous)
</span><span class="comment">// - Sending transactions for non-constant functions
</span>const erc20_rw = new ethers.Contract(address, abi, signer)
</div><a name="example-erc-20-contract--connecting-to-a-contract--erc20contract"></a><h3 class="show-anchors"><div>ERC20Contract<span class="inherits"> inherits <a href="/v5/api/contract/contract/">Contract</a></span><div class="anchors"><a class="self" href="/v5/api/contract/example/#example-erc-20-contract--connecting-to-a-contract--erc20contract"></a></div></div></h3>
<div class="property show-anchors"><div class="signature"><span class="modifier">new </span><span class="path">ethers</span><span class="symbol">.</span><span class="method">Contract</span><span class="symbol">(</span> <span class="param">address</span> <span class="symbol">,</span> <span class="param">abi</span> <span class="symbol">,</span> <span class="param">providerOrSigner</span> <span class="symbol">)</span><div class="anchors"></div></div><div class="body"><p>See the above code example for creating an Instance which will (in addition to the Contact methods and properties) automatically add the additional properties defined in <i>abi</i> to a <b>Contract</b> connected to <i>address</i> using the <i>providerOrSigner</i>.</p>

</div></div><a name="example-erc-20-contract--properties"></a><h2 class="show-anchors"><div>Properties<span class="inherits">(inheritted from <a href="/v5/api/contract/contract/">Contract</a>)</span><div class="anchors"><a class="self" href="/v5/api/contract/example/#example-erc-20-contract--properties"></a></div></div></h2>
Expand Down Expand Up @@ -126,7 +127,7 @@
<div class="nav previous"><a href="/v5/api/contract/contract-factory/"><span class="arrow">&larr;</span>ContractFactory</a></div>
<div class="nav next"><a href="/v5/api/signer/">Signers<span class="arrow">&rarr;</span></a></div>
</div>
<div class="copyright">The content of this site is licensed under the <a href="https://choosealicense.com/licenses/cc-by-4.0/">Creative Commons License</a>. Generated on June 12, 2020, 3:31am.</div>
<div class="copyright">The content of this site is licensed under the <a href="https://choosealicense.com/licenses/cc-by-4.0/">Creative Commons License</a>. Last modified on June 12, 2020, 7:17pm.</div>
</div>
<script src="/v5/static/script.js" type="text/javascript"></script>
</body>
Expand Down
2 changes: 1 addition & 1 deletion docs/v5/api/contract/index.html
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@
<div class="nav previous"><a href="/v5/api/"><span class="arrow">&larr;</span>Application Programming Interface</a></div>
<div class="nav next"><a href="/v5/api/contract/contract/">Contract<span class="arrow">&rarr;</span></a></div>
</div>
<div class="copyright">The content of this site is licensed under the <a href="https://choosealicense.com/licenses/cc-by-4.0/">Creative Commons License</a>. Generated on June 12, 2020, 3:31am.</div>
<div class="copyright">The content of this site is licensed under the <a href="https://choosealicense.com/licenses/cc-by-4.0/">Creative Commons License</a>. Last modified on June 12, 2020, 7:17pm.</div>
</div>
<script src="/v5/static/script.js" type="text/javascript"></script>
</body>
Expand Down
2 changes: 1 addition & 1 deletion docs/v5/api/experimental/index.html
Original file line number Diff line number Diff line change
Expand Up @@ -54,7 +54,7 @@
<div class="nav previous"><a href="/v5/api/other/hardware/"><span class="arrow">&larr;</span>Hardware Wallets</a></div>
<div class="nav next"><a href="/v5/cli/">Command Line Interfaces<span class="arrow">&rarr;</span></a></div>
</div>
<div class="copyright">The content of this site is licensed under the <a href="https://choosealicense.com/licenses/cc-by-4.0/">Creative Commons License</a>. Generated on June 12, 2020, 3:31am.</div>
<div class="copyright">The content of this site is licensed under the <a href="https://choosealicense.com/licenses/cc-by-4.0/">Creative Commons License</a>. Last modified on June 12, 2020, 7:17pm.</div>
</div>
<script src="/v5/static/script.js" type="text/javascript"></script>
</body>
Expand Down
2 changes: 1 addition & 1 deletion docs/v5/api/index.html
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@
<div class="nav previous"><a href="/v5/concepts/security/"><span class="arrow">&larr;</span>Security</a></div>
<div class="nav next"><a href="/v5/api/contract/">Contract Interaction<span class="arrow">&rarr;</span></a></div>
</div>
<div class="copyright">The content of this site is licensed under the <a href="https://choosealicense.com/licenses/cc-by-4.0/">Creative Commons License</a>. Generated on June 12, 2020, 3:31am.</div>
<div class="copyright">The content of this site is licensed under the <a href="https://choosealicense.com/licenses/cc-by-4.0/">Creative Commons License</a>. Last modified on June 12, 2020, 7:17pm.</div>
</div>
<script src="/v5/static/script.js" type="text/javascript"></script>
</body>
Expand Down
Loading

0 comments on commit 9e4c7e6

Please sign in to comment.