Compare commits
No commits in common. "main" and "eip-1559" have entirely different histories.
1
.github/FUNDING.yml
vendored
1
.github/FUNDING.yml
vendored
@ -1,2 +1 @@
|
||||
github: ethers-io
|
||||
custom: [ 'https://gitcoin.co/grants/13/ethersjs-complete-simple-and-tiny-2', 'https://www.buymeacoffee.com/ricmoo' ]
|
||||
|
||||
81
.github/ISSUE_TEMPLATE/bug-report-legacy.yml
vendored
81
.github/ISSUE_TEMPLATE/bug-report-legacy.yml
vendored
@ -1,81 +0,0 @@
|
||||
name: "Bug Report v5 (legacy)"
|
||||
description: "Open an issue for a bug in Ethers v5 (legacy)"
|
||||
title: "Add Bug Title Here"
|
||||
labels: [ "investigate", "v5" ]
|
||||
assignees:
|
||||
- ricmoo
|
||||
body:
|
||||
- type: markdown
|
||||
attributes:
|
||||
value: |
|
||||
**READ THIS FIRST** and follow all instructions, please. `:)`
|
||||
|
||||
Thank you for taking the time to report an issue. This form is for reporting **bugs within ethers**, specifically for the legacy v5 branch.
|
||||
|
||||
If you are **new to ethers** or *uncertain* whether this is a bug in ethers, a bug in another framework or a bug in your own code, please [start a discussion](https://github.com/ethers-io/ethers.js/discussions) first.
|
||||
- type: input
|
||||
id: version
|
||||
attributes:
|
||||
label: Ethers Version
|
||||
description: What version of ethers are you using? Before opening an issue, please make sure you are up to date.
|
||||
placeholder: 5.y.z
|
||||
validations:
|
||||
required: true
|
||||
- type: input
|
||||
id: search-terms
|
||||
attributes:
|
||||
label: Search Terms
|
||||
description: Have you searched for answers [in the documentation](https://docs.ethers.org), through [the issues](https://github.com/ethers-io/ethers.js/issues) and [on the discusions](https://github.com/ethers-io/ethers.js/discussions)? Please include the search terms you have tried. This helps us add more keywords where needed.
|
||||
placeholder: e.g. abi, network, utf8
|
||||
- type: textarea
|
||||
id: about-the-bug
|
||||
attributes:
|
||||
label: Describe the Problem
|
||||
description: Please describe what you expected to happen vs what did happen?
|
||||
placeholder: What happened?
|
||||
validations:
|
||||
required: true
|
||||
- type: textarea
|
||||
id: code-snippet
|
||||
attributes:
|
||||
label: Code Snippet
|
||||
description: If possible, please include a **short and concise** code snippets that can reproduce this issue. Ideally code that can be pasted into the [Ethers Playground](https://playground.ethers.org).
|
||||
placeholder: e.g. provider.getBlockNumber()
|
||||
render: shell
|
||||
- type: textarea
|
||||
id: contract-abi
|
||||
attributes:
|
||||
label: Contract ABI
|
||||
description: If this involves a contract, please include any **concise and relevant** ABI fragments.
|
||||
placeholder: e.g. [ 'function balanceOf(address owner) view returns (uint)' ]
|
||||
render: shell
|
||||
- type: textarea
|
||||
id: errors
|
||||
attributes:
|
||||
label: Errors
|
||||
description: If there is an error, please include the **entire error** (redacting any sensitive information).
|
||||
placeholder: "e.g. Error: invalid name (code='INVALID_ARGUMENT, ...)"
|
||||
render: shell
|
||||
- type: dropdown
|
||||
id: environment
|
||||
attributes:
|
||||
label: Environment
|
||||
description: What environment, platforms or frameworks are you using? Select all that apply.
|
||||
multiple: true
|
||||
options:
|
||||
- Ethereum (mainnet/ropsten/rinkeby/goerli)
|
||||
- Altcoin - Please specify (e.g. Polygon)
|
||||
- node.js (v12 or newer)
|
||||
- node.js (older than v12)
|
||||
- Browser (Chrome, Safari, etc)
|
||||
- React Native/Expo/JavaScriptCore
|
||||
- Hardhat
|
||||
- Geth
|
||||
- Parity
|
||||
- Ganache
|
||||
- Other (please specify)
|
||||
- type: input
|
||||
id: other-envrionment
|
||||
attributes:
|
||||
label: Environment (Other)
|
||||
placeholder: anything else?
|
||||
24
.github/ISSUE_TEMPLATE/bug-report.md
vendored
Normal file
24
.github/ISSUE_TEMPLATE/bug-report.md
vendored
Normal file
@ -0,0 +1,24 @@
|
||||
---
|
||||
name: Bug Report
|
||||
about: Create a report to help us improve
|
||||
title: ''
|
||||
labels: investigate
|
||||
assignees: ''
|
||||
|
||||
---
|
||||
|
||||
Note: Not all sections may be relevant, but please be as thorough while remaining concise as possible. Remove this Notice and any sections that don't feel pertinent.
|
||||
|
||||
If you are unsure if something is a bug, start a thread in the *"discussions"* tab above..
|
||||
|
||||
**Describe the bug**
|
||||
A clear and concise description of what the bug is.
|
||||
|
||||
**Reproduction steps**
|
||||
Please include code snippets, with console.log output, any contract ABI, contract address, network and the full error.
|
||||
|
||||
**Environment:**
|
||||
Please include anything that may be useful in diagnosing the issue. Node vs Browser? Geth vs Parity vs Ganache? Third Party tools, like Hardhat? Mobile vs. Desktop?
|
||||
|
||||
**Search Terms**
|
||||
Often similar issues have come up before. Include any search terms you have tried in this repository's Issues (including closed issues) and *"Discussions"*, so if there are matching issues, we can be sure to add those keywords and link this issue to it, making it easier for people to find in the future.
|
||||
81
.github/ISSUE_TEMPLATE/bug-report.yml
vendored
81
.github/ISSUE_TEMPLATE/bug-report.yml
vendored
@ -1,81 +0,0 @@
|
||||
name: "Bug Report v6 (latest)"
|
||||
description: "Open an issue for a bug in Ethers v6 (latest)"
|
||||
title: "Add Bug Title Here"
|
||||
labels: [ "investigate", "v6" ]
|
||||
assignees:
|
||||
- ricmoo
|
||||
body:
|
||||
- type: markdown
|
||||
attributes:
|
||||
value: |
|
||||
**READ THIS FIRST** and follow all instructions, please. `:)`
|
||||
|
||||
Thank you for taking the time to report an issue. This form is for reporting **bugs within ethers**.
|
||||
|
||||
If you are **new to ethers** or *uncertain* whether this is a bug in ethers, a bug in another framework or a bug in your own code, please [start a discussion](https://github.com/ethers-io/ethers.js/discussions) first.
|
||||
- type: input
|
||||
id: version
|
||||
attributes:
|
||||
label: Ethers Version
|
||||
description: What version of ethers are you using? Before opening an issue, please make sure you are up to date.
|
||||
placeholder: 6.y.z
|
||||
validations:
|
||||
required: true
|
||||
- type: input
|
||||
id: search-terms
|
||||
attributes:
|
||||
label: Search Terms
|
||||
description: Have you searched for answers [in the documentation](https://docs.ethers.org), through [the issues](https://github.com/ethers-io/ethers.js/issues) and [on the discusions](https://github.com/ethers-io/ethers.js/discussions)? Please include the search terms you have tried. This helps us add more keywords where needed.
|
||||
placeholder: e.g. abi, network, utf8
|
||||
- type: textarea
|
||||
id: about-the-bug
|
||||
attributes:
|
||||
label: Describe the Problem
|
||||
description: Please describe what you expected to happen vs what did happen?
|
||||
placeholder: What happened?
|
||||
validations:
|
||||
required: true
|
||||
- type: textarea
|
||||
id: code-snippet
|
||||
attributes:
|
||||
label: Code Snippet
|
||||
description: If possible, please include a **short and concise** code snippets that can reproduce this issue. Ideally code that can be pasted into the [Ethers Playground](https://playground.ethers.org).
|
||||
placeholder: e.g. provider.getBlockNumber()
|
||||
render: shell
|
||||
- type: textarea
|
||||
id: contract-abi
|
||||
attributes:
|
||||
label: Contract ABI
|
||||
description: If this involves a contract, please include any **concise and relevant** ABI fragments.
|
||||
placeholder: e.g. [ 'function balanceOf(address owner) view returns (uint)' ]
|
||||
render: shell
|
||||
- type: textarea
|
||||
id: errors
|
||||
attributes:
|
||||
label: Errors
|
||||
description: If there is an error, please include the **entire error** (redacting any sensitive information).
|
||||
placeholder: "e.g. Error: invalid name (code='INVALID_ARGUMENT, ...)"
|
||||
render: shell
|
||||
- type: dropdown
|
||||
id: environment
|
||||
attributes:
|
||||
label: Environment
|
||||
description: What environment, platforms or frameworks are you using? Select all that apply.
|
||||
multiple: true
|
||||
options:
|
||||
- Ethereum (mainnet/ropsten/rinkeby/goerli)
|
||||
- Altcoin - Please specify (e.g. Polygon)
|
||||
- node.js (v12 or newer)
|
||||
- node.js (older than v12)
|
||||
- Browser (Chrome, Safari, etc)
|
||||
- React Native/Expo/JavaScriptCore
|
||||
- Hardhat
|
||||
- Geth
|
||||
- Parity
|
||||
- Ganache
|
||||
- Other (please specify)
|
||||
- type: input
|
||||
id: other-envrionment
|
||||
attributes:
|
||||
label: Environment (Other)
|
||||
placeholder: anything else?
|
||||
16
.github/ISSUE_TEMPLATE/documentation.md
vendored
Normal file
16
.github/ISSUE_TEMPLATE/documentation.md
vendored
Normal file
@ -0,0 +1,16 @@
|
||||
---
|
||||
name: Documentation
|
||||
about: Documentation request or suggestion
|
||||
title: ''
|
||||
labels: documentation
|
||||
assignees: ''
|
||||
|
||||
---
|
||||
|
||||
Please include anything about the [documentation](https://docs.ethers.io) you would like to see improved.
|
||||
|
||||
- Missing information or details?
|
||||
- Wrong Information?
|
||||
- Dead or wrong links?
|
||||
- Something needs code examples?
|
||||
- General feedback or anything else?
|
||||
23
.github/ISSUE_TEMPLATE/documentation.yml
vendored
23
.github/ISSUE_TEMPLATE/documentation.yml
vendored
@ -1,23 +0,0 @@
|
||||
name: Documentation
|
||||
description: Documentation update, change or suggestion
|
||||
title: "Documentation Title"
|
||||
labels: ["documentation"]
|
||||
body:
|
||||
- type: markdown
|
||||
attributes:
|
||||
value: |
|
||||
Please include anything about the [documentation](https://docs.ethers.org) you would like to see improved.
|
||||
|
||||
- Missing information or details?
|
||||
- Spelling or Grammar mistakes?
|
||||
- Wrong Information?
|
||||
- Dead or wrong links?
|
||||
- Something needs code examples?
|
||||
- General feedback or anything else?
|
||||
- type: textarea
|
||||
id: suggestion
|
||||
attributes:
|
||||
label: Suggestion
|
||||
placeholder: e.g. please add an example for ropsten
|
||||
validations:
|
||||
required: true
|
||||
22
.github/ISSUE_TEMPLATE/feature-request.md
vendored
Normal file
22
.github/ISSUE_TEMPLATE/feature-request.md
vendored
Normal file
@ -0,0 +1,22 @@
|
||||
---
|
||||
name: Feature Request
|
||||
about: Suggest a new feature for ethers
|
||||
title: ''
|
||||
labels: ''
|
||||
assignees: ''
|
||||
|
||||
---
|
||||
|
||||
Note: The best place to start a Feature Request is usually in the Discussions, to mull through the desired feature, current options and think through the impact on the library overall.
|
||||
|
||||
**Is your feature request related to a problem? Please describe.**
|
||||
A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
|
||||
|
||||
**Describe the solution you'd like**
|
||||
A clear and concise description of what you want to happen.
|
||||
|
||||
**Describe alternatives you've considered**
|
||||
A clear and concise description of any alternative solutions or features you've considered.
|
||||
|
||||
**Additional context**
|
||||
Add any other context or screenshots about the feature request here.
|
||||
26
.github/ISSUE_TEMPLATE/feature-request.yml
vendored
26
.github/ISSUE_TEMPLATE/feature-request.yml
vendored
@ -1,26 +0,0 @@
|
||||
name: Feature Request
|
||||
description: Suggest a new feature or addition to Ethers
|
||||
title: "Feature Request Title"
|
||||
labels: [ "enhancement" ]
|
||||
body:
|
||||
- type: markdown
|
||||
attributes:
|
||||
value: |
|
||||
The best place to start a new feature request is by starting an [Idea discussion](https://github.com/ethers-io/ethers.js/discussions), to mull over the feature, discuss current options and think through the impact on the overall library.
|
||||
|
||||
Keep in mind that features increase the library size, and may require additional dependencies. Ethers strives to remain lean and the number of dependencies low, so many features may make more sense as ancillary packages.
|
||||
- type: textarea
|
||||
id: about-the-feature
|
||||
attributes:
|
||||
label: Describe the Feature
|
||||
description: Please describe the feature, the problem it is solving, your solution and alternatives you've considered.
|
||||
placeholder: e.g. I want Ethers to be more/less magical.
|
||||
validations:
|
||||
required: true
|
||||
- type: textarea
|
||||
id: code-example
|
||||
attributes:
|
||||
label: Code Example
|
||||
description: Optionally, provide an example of how the feature would be used in code.
|
||||
placeholder: e.g. provider.doMagic()
|
||||
render: shell
|
||||
16
.github/ISSUE_TEMPLATE/other.md
vendored
Normal file
16
.github/ISSUE_TEMPLATE/other.md
vendored
Normal file
@ -0,0 +1,16 @@
|
||||
---
|
||||
name: Other
|
||||
about: Something else
|
||||
title: ''
|
||||
labels: ''
|
||||
assignees: ''
|
||||
|
||||
---
|
||||
|
||||
Generally this issue template should be used.
|
||||
|
||||
If your issue is **not** a **Feature Request**, a **Bug Report** or problem with the **Documentation** you should probably be using the *"Discussion"* tab at the top.
|
||||
|
||||
But for truly exceptional issues, please include the details here.
|
||||
|
||||
Please also include any search terms you used when searching issues and discussions, so we can better tag those in the future.
|
||||
48
.github/workflows/generate-docs.yml
vendored
48
.github/workflows/generate-docs.yml
vendored
@ -1,48 +0,0 @@
|
||||
name: Generate Documentation
|
||||
|
||||
on:
|
||||
push:
|
||||
branches:
|
||||
- main
|
||||
paths:
|
||||
- "src.ts/**"
|
||||
- "docs.wrm/**"
|
||||
|
||||
jobs:
|
||||
docs:
|
||||
name: Generate Documentation
|
||||
|
||||
runs-on: ubuntu-latest
|
||||
|
||||
environment: ethers-tests
|
||||
env:
|
||||
FAUCET_PRIVATEKEY: ${{ secrets.FAUCET_PRIVATEKEY }}
|
||||
|
||||
steps:
|
||||
- uses: actions/setup-node@v1
|
||||
with:
|
||||
node-version: 20.x
|
||||
|
||||
- name: Checkout repository
|
||||
uses: actions/checkout@v3
|
||||
with:
|
||||
fetch-depth: "0"
|
||||
|
||||
- name: Install dependencies
|
||||
run: npm ci
|
||||
|
||||
- name: Install Flatworm
|
||||
run: npm install --no-save 'https://github.com/ricmoo/flatworm.git#tsdocs'
|
||||
|
||||
- name: Build Documentation
|
||||
run: node node_modules/flatworm/lib/cli-test ./docs.wrm/config.mjs
|
||||
|
||||
- name: Upload documentation to to docs.ethers.org
|
||||
uses: ethers-io/sync-s3-action@main
|
||||
with:
|
||||
aws_access_key_id: ${{ secrets.DOCS_AWS_ACCESS_KEY_ID }}
|
||||
aws_secret_access_key: ${{ secrets.DOCS_AWS_SECRET_ACCESS_KEY}}
|
||||
aws_s3_bucket: ethers.org
|
||||
source_folder: 'output/docs/'
|
||||
destination_prefix: 'docs/'
|
||||
aws_cloudfront_id: ${{ secrets.DOCS_AWS_CLOUDFRONT_ID }}
|
||||
143
.github/workflows/nodejs.yml
vendored
Normal file
143
.github/workflows/nodejs.yml
vendored
Normal file
@ -0,0 +1,143 @@
|
||||
name: Node.js CI
|
||||
|
||||
on:
|
||||
push:
|
||||
branches:
|
||||
- master
|
||||
|
||||
jobs:
|
||||
|
||||
test-node:
|
||||
|
||||
# runs-on: ubuntu-latest
|
||||
runs-on: macos-latest
|
||||
|
||||
strategy:
|
||||
fail-fast: false
|
||||
matrix:
|
||||
node-version: [ 8.x, 10.x, 12.x, 13.x ]
|
||||
|
||||
steps:
|
||||
- name: Use Node.js ${{ matrix.node-version }}
|
||||
uses: actions/setup-node@v1
|
||||
with:
|
||||
node-version: ${{ matrix.node-version }}
|
||||
|
||||
- name: Checkout repository
|
||||
uses: actions/checkout@v2
|
||||
|
||||
# - name: Install node-hid requirements
|
||||
# run: sudo apt-get install libusb-1.0-0 libusb-1.0-0-dev libudev-dev
|
||||
|
||||
- name: Install dependencies (and link per package)
|
||||
run: npm ci
|
||||
|
||||
- name: Build CommonJS and ESM (from TypeScript)
|
||||
run: npm run build-all
|
||||
|
||||
- name: Run tests
|
||||
run: npm run test-node
|
||||
|
||||
|
||||
test-browser:
|
||||
|
||||
# runs-on: ubuntu-latest
|
||||
runs-on: macos-latest
|
||||
|
||||
strategy:
|
||||
fail-fast: false
|
||||
matrix:
|
||||
module: [ 'esm', 'umd' ]
|
||||
|
||||
steps:
|
||||
- uses: actions/setup-node@v1
|
||||
with:
|
||||
node-version: 12.x
|
||||
|
||||
- name: Checkout repository
|
||||
uses: actions/checkout@v2
|
||||
|
||||
# - name: Install node-hid requirements
|
||||
# run: sudo apt-get install libusb-1.0-0 libusb-1.0-0-dev libudev-dev
|
||||
|
||||
- name: Install dependencies (and link per package)
|
||||
run: npm ci
|
||||
|
||||
- name: Build CommonJS and ESM (from TypeScript)
|
||||
run: npm run build-all
|
||||
|
||||
- name: Run tests
|
||||
run: npm run test-browser-${{ matrix.module }}
|
||||
|
||||
test-react-native:
|
||||
|
||||
runs-on: macos-latest
|
||||
|
||||
# Temporary for testing CI
|
||||
continue-on-error: true
|
||||
|
||||
strategy:
|
||||
fail-fast: false
|
||||
|
||||
steps:
|
||||
- name: Use Node.js 12.x
|
||||
uses: actions/setup-node@v1
|
||||
with:
|
||||
node-version: 12.x
|
||||
|
||||
- name: Checkout repository
|
||||
uses: actions/checkout@v2
|
||||
|
||||
- name: Install dependencies (and link per package)
|
||||
run: npm ci
|
||||
|
||||
- name: Build CommonJS and ESM (from TypeScript)
|
||||
run: npm run build-all
|
||||
|
||||
- name: Run tests
|
||||
run: npm run test-react
|
||||
|
||||
|
||||
coverage:
|
||||
|
||||
name: Coverage
|
||||
|
||||
# runs-on: ubuntu-latest
|
||||
runs-on: macos-latest
|
||||
|
||||
continue-on-error: true
|
||||
|
||||
steps:
|
||||
- uses: actions/setup-node@v1
|
||||
with:
|
||||
node-version: 12.x
|
||||
|
||||
- name: Checkout repository
|
||||
uses: actions/checkout@v2
|
||||
|
||||
# - name: Install node-hid requirements
|
||||
# run: sudo apt-get install libusb-1.0-0 libusb-1.0-0-dev libudev-dev
|
||||
|
||||
- name: Install dependencies (and link per package)
|
||||
run: npm ci
|
||||
|
||||
- name: Build CommonJS and ESM (from TypeScript)
|
||||
run: npm run build-all
|
||||
|
||||
- name: Run tests
|
||||
run: npm run test-coverage
|
||||
|
||||
- name: Upload coverage summary
|
||||
uses: actions/upload-artifact@v2
|
||||
with:
|
||||
name: coverage-summary
|
||||
path: ./output/summary.txt
|
||||
|
||||
- name: Tar files
|
||||
run: tar -cvf ./output/coverage.tar ./output/lcov-report/
|
||||
|
||||
- name: Upload coverage
|
||||
uses: actions/upload-artifact@v2
|
||||
with:
|
||||
name: coverage-complete
|
||||
path: ./output/coverage.tar
|
||||
46
.github/workflows/test-browser.yml
vendored
46
.github/workflows/test-browser.yml
vendored
@ -1,46 +0,0 @@
|
||||
name: Browser Tests
|
||||
|
||||
on:
|
||||
push:
|
||||
branches:
|
||||
- main
|
||||
paths:
|
||||
- "src.ts/**"
|
||||
- "lib.esm/**"
|
||||
- "lib.commonjs/**"
|
||||
- "misc/test-browser/**"
|
||||
|
||||
jobs:
|
||||
test-browser:
|
||||
name: Run Browser Tests
|
||||
|
||||
runs-on: ubuntu-latest
|
||||
|
||||
environment: ethers-tests
|
||||
|
||||
strategy:
|
||||
fail-fast: false
|
||||
|
||||
steps:
|
||||
- name: Install Node.js
|
||||
uses: actions/setup-node@v1
|
||||
with:
|
||||
node-version: 20.x
|
||||
|
||||
- name: Install and run Geth
|
||||
uses: ethers-io/run-geth-action@main
|
||||
|
||||
- name: Insall Chrome
|
||||
run: wget -q 'https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb' && sudo dpkg --install google-chrome-stable_current_amd64.deb
|
||||
|
||||
- name: Checkout repository
|
||||
uses: actions/checkout@v2
|
||||
|
||||
- name: Install dependencies
|
||||
run: npm ci
|
||||
|
||||
- name: Build browser bundles (from TypeScript)
|
||||
run: npm run build-dist
|
||||
|
||||
- name: Run tests
|
||||
run: npm run test-browser
|
||||
109
.github/workflows/test-ci.yml
vendored
109
.github/workflows/test-ci.yml
vendored
@ -1,109 +0,0 @@
|
||||
name: CI Tests
|
||||
|
||||
on:
|
||||
push:
|
||||
branches:
|
||||
- main
|
||||
paths:
|
||||
- "src.ts/**"
|
||||
- "lib.esm/**"
|
||||
- "lib.commonjs/**"
|
||||
|
||||
jobs:
|
||||
|
||||
test-node:
|
||||
#if: ${{ false }} # disable for now
|
||||
|
||||
name: Run Node.js Tests
|
||||
|
||||
runs-on: ubuntu-latest
|
||||
|
||||
environment: ethers-tests
|
||||
env:
|
||||
FAUCET_PRIVATEKEY: ${{ secrets.FAUCET_PRIVATEKEY }}
|
||||
|
||||
strategy:
|
||||
fail-fast: false
|
||||
matrix:
|
||||
node-version: [ 18.x, 20.x ]
|
||||
test-type: [ esm, commonjs ]
|
||||
|
||||
steps:
|
||||
- name: Use Node.js ${{ matrix.node-version }}
|
||||
uses: actions/setup-node@v1
|
||||
with:
|
||||
node-version: ${{ matrix.node-version }}
|
||||
|
||||
- name: Install and run Geth
|
||||
uses: ethers-io/run-geth-action@main
|
||||
|
||||
- name: Checkout repository
|
||||
uses: actions/checkout@v2
|
||||
|
||||
- name: Install dependencies
|
||||
run: npm ci
|
||||
|
||||
- name: Build ESM and CommonJS (from TypeScript)
|
||||
run: npm run build-all
|
||||
|
||||
- name: Run tests (${{ matrix.test-type }})
|
||||
run: npm run test-${{ matrix.test-type }}
|
||||
|
||||
|
||||
coverage:
|
||||
#if: ${{ false }} # disable for now
|
||||
|
||||
name: Generate Coverage Report
|
||||
|
||||
runs-on: ubuntu-latest
|
||||
|
||||
environment: ethers-tests
|
||||
env:
|
||||
FAUCET_PRIVATEKEY: ${{ secrets.FAUCET_PRIVATEKEY }}
|
||||
|
||||
continue-on-error: true
|
||||
|
||||
steps:
|
||||
- uses: actions/setup-node@v1
|
||||
with:
|
||||
node-version: 20.x
|
||||
|
||||
- name: Install and run Geth
|
||||
uses: ethers-io/run-geth-action@main
|
||||
|
||||
- name: Checkout repository
|
||||
uses: actions/checkout@v2
|
||||
|
||||
- name: Install dependencies
|
||||
run: npm ci
|
||||
|
||||
- name: Build ESM (from TypeScript)
|
||||
run: npm run build
|
||||
|
||||
- name: Run coverage tests
|
||||
run: npm run test-coverage
|
||||
|
||||
- name: Store coverage summary artifact
|
||||
uses: actions/upload-artifact@v2
|
||||
with:
|
||||
name: coverage-summary
|
||||
path: ./output/summary.txt
|
||||
|
||||
- name: Tar coverage files
|
||||
run: tar -cvf ./output/coverage.tar ./output/lcov-report/
|
||||
|
||||
- name: Store full coverage artifact
|
||||
uses: actions/upload-artifact@v2
|
||||
with:
|
||||
name: coverage-complete
|
||||
path: ./output/coverage.tar
|
||||
|
||||
- name: Upload coverage to build.ethers.org
|
||||
uses: ethers-io/sync-s3-action@main
|
||||
with:
|
||||
aws_access_key_id: ${{ secrets.BUILD_AWS_ACCESS_KEY_ID }}
|
||||
aws_secret_access_key: ${{ secrets.BUILD_AWS_SECRET_ACCESS_KEY}}
|
||||
aws_s3_bucket: ethers.org
|
||||
source_folder: 'output/'
|
||||
destination_prefix: 'build/output/'
|
||||
aws_cloudfront_id: ${{ secrets.BUILD_AWS_CLOUDFRONT_ID }}
|
||||
86
.github/workflows/test-env.yml
vendored
86
.github/workflows/test-env.yml
vendored
@ -1,86 +0,0 @@
|
||||
name: Environment Tests
|
||||
|
||||
on:
|
||||
push:
|
||||
branches:
|
||||
- main
|
||||
|
||||
jobs:
|
||||
|
||||
test-tsc-env:
|
||||
name: Test TypeScript Environments
|
||||
|
||||
runs-on: ubuntu-latest
|
||||
|
||||
env:
|
||||
npm_config_registry: http://localhost:8043
|
||||
|
||||
strategy:
|
||||
fail-fast: false
|
||||
matrix:
|
||||
tsModuleResolution: [ "node", "node16", "nodenext" ]
|
||||
tsModule: [ "commonjs", "es2020" ]
|
||||
|
||||
steps:
|
||||
- name: Use Node.js
|
||||
uses: actions/setup-node@v1
|
||||
with:
|
||||
node-version: 20.x
|
||||
|
||||
- name: Checkout repository
|
||||
uses: actions/checkout@v3
|
||||
with:
|
||||
path: "faux_modules/ethers"
|
||||
|
||||
- name: Copy tests to working directory
|
||||
run: cp -r faux_modules/ethers/testcases/test-env/test-tsc/* .
|
||||
|
||||
- name: Prepare setup moduleResolution=${{ matrix.tsModuleResolution }} module=${{ matrix.tsModule }}
|
||||
run: node prepare.cjs ${{ matrix.tsModuleResolution }} ${{ matrix.tsModule }}
|
||||
|
||||
- name: Dump Config
|
||||
run: cat package.json tsconfig.json
|
||||
|
||||
- name: Install and run Faux Registry
|
||||
uses: ethers-io/hijack-npm-action@main
|
||||
|
||||
- name: Install packages
|
||||
run: npm install
|
||||
|
||||
- name: Dump Faux Logs
|
||||
run: cat .fauxNpm.log
|
||||
|
||||
- name: Run tests
|
||||
run: npm test
|
||||
|
||||
test-angular:
|
||||
name: Test Angular Environment
|
||||
|
||||
runs-on: ubuntu-latest
|
||||
|
||||
env:
|
||||
npm_config_registry: http://localhost:8043
|
||||
|
||||
steps:
|
||||
- name: Use Node.js
|
||||
uses: actions/setup-node@v1
|
||||
with:
|
||||
node-version: 20.x
|
||||
|
||||
- name: Checkout repository
|
||||
uses: actions/checkout@v3
|
||||
with:
|
||||
path: "faux_modules/ethers"
|
||||
|
||||
- name: Copy tests to working directory
|
||||
run: cp -r faux_modules/ethers/testcases/test-env/angular/* .
|
||||
|
||||
- name: Install and run Faux Registry
|
||||
uses: ethers-io/hijack-npm-action@main
|
||||
|
||||
- name: Install packages
|
||||
run: npm install
|
||||
|
||||
- name: Build project
|
||||
run: npm run build
|
||||
|
||||
32
.gitignore
vendored
32
.gitignore
vendored
@ -1,7 +1,29 @@
|
||||
node_modules/**
|
||||
node_modules/
|
||||
packages/*/node_modules
|
||||
packages/*/lib._esm
|
||||
.package_node_modules/
|
||||
obsolete/
|
||||
.DS_Store
|
||||
.tmp/
|
||||
dist/types/shims/
|
||||
shims/*.d.ts
|
||||
**/*.swp
|
||||
*~
|
||||
|
||||
# Weird intermediate files tsc generates for references
|
||||
**/src.ts/*.js
|
||||
|
||||
# Weird file Browserify sometimes leaves lying around.
|
||||
**/*.tmp-browserify-*
|
||||
|
||||
lerna-debug.log
|
||||
|
||||
packages/*/tsconfig.tsbuildinfo
|
||||
|
||||
packages/testcases/input/nameprep/**
|
||||
|
||||
.nyc_output/**
|
||||
|
||||
output/**
|
||||
|
||||
**/*.save
|
||||
**/*.swp
|
||||
**/*.tgz
|
||||
dist/*.gz
|
||||
misc/testing/**
|
||||
|
||||
31
.npmignore
31
.npmignore
@ -1,31 +0,0 @@
|
||||
|
||||
# Ignore TypeScript config and caches
|
||||
tsconfig.*.json
|
||||
tsconfig.tsbuildinfo
|
||||
rollup.config.js
|
||||
output/**
|
||||
docs.wrm/**
|
||||
.github/**
|
||||
|
||||
# Ignore admin scripts and files
|
||||
src.ts/_admin/**
|
||||
lib.commonjs/_admin/**
|
||||
lib.esm/_admin/**
|
||||
types/_admin/**
|
||||
reporter.cjs
|
||||
package-commonjs.json
|
||||
.github/workflows/test-ci.yml
|
||||
|
||||
# Ignore test cases
|
||||
src.ts/_tests/**
|
||||
lib.commonjs/_tests/**
|
||||
lib.esm/_tests/**
|
||||
types/_tests/**
|
||||
testcases/**
|
||||
|
||||
# Ignore random junk
|
||||
.DS_Store
|
||||
node_modules/**
|
||||
misc/**
|
||||
**/*.tgz
|
||||
dist/*.gz
|
||||
1
.npmrc
1
.npmrc
@ -1 +0,0 @@
|
||||
@tornado:registry=https://git.tornado.ws/api/packages/tornado-packages/npm/
|
||||
583
CHANGELOG.md
583
CHANGELOG.md
@ -1,339 +1,330 @@
|
||||
Change Log
|
||||
==========
|
||||
Changelog
|
||||
=========
|
||||
|
||||
This change log is maintained by `src.ts/_admin/update-changelog.ts` but may also be manually updated.
|
||||
This change log is managed by `admin/cmds/update-versions` but may be manually updated.
|
||||
|
||||
ethers/v6.12.0 (2024-04-17 01:09)
|
||||
ethers/v5.3.1 (2021-06-10 18:28)
|
||||
--------------------------------
|
||||
|
||||
- Fixed replacement transaction detection for JsonRpcSigner. ([#1658](https://github.com/ethers-io/ethers.js/issues/1658); [ee82e86](https://github.com/ethers-io/ethers.js/commit/ee82e86ccc439825259d20825a00050217890ad3))
|
||||
- Added Matic testnet info to networks. ([#1546](https://github.com/ethers-io/ethers.js/issues/1546); [376cf3c](https://github.com/ethers-io/ethers.js/commit/376cf3cdbf6d2281331d36c5742414a425927318))
|
||||
- Match Solidity identifier regex. ([#1657](https://github.com/ethers-io/ethers.js/issues/1657); [a6e128f](https://github.com/ethers-io/ethers.js/commit/a6e128f5cc566d291b722cca1734ba41aae6c548))
|
||||
|
||||
ethers/v5.3.0 (2021-05-31 18:41)
|
||||
--------------------------------
|
||||
|
||||
- Added MinInt256 and MaxInt256 constants. ([#1576](https://github.com/ethers-io/ethers.js/issues/1576); [bfcd05f](https://github.com/ethers-io/ethers.js/commit/bfcd05fcbb132d456d6f22f70c8ac9cf5b1826f7))
|
||||
- Version bumps for bn.js and hash.js to match elliptic and fix some build tools. ([#1478](https://github.com/ethers-io/ethers.js/issues/1478); [819b1ac](https://github.com/ethers-io/ethers.js/commit/819b1ace5c9b16e29dc354ad80e0e5b71ac63c52))
|
||||
- Removed Hangul checks in shims which crashes Android. ([#1519](https://github.com/ethers-io/ethers.js/issues/1519); [4b33114](https://github.com/ethers-io/ethers.js/commit/4b331148d980e3056ceaabdcd6e50a2aa1beb40d))
|
||||
- Fixed ENS namehash with leading and trailing dots. ([#1605](https://github.com/ethers-io/ethers.js/issues/1605); [7adcf3b](https://github.com/ethers-io/ethers.js/commit/7adcf3b154669d9d1a0a66d5e15dabfbf6618180))
|
||||
- Fixed broken variable in template string. ([#1624](https://github.com/ethers-io/ethers.js/issues/1624), [#1626](https://github.com/ethers-io/ethers.js/issues/1626); [630656e](https://github.com/ethers-io/ethers.js/commit/630656e949a8ffd940e4b66ec93ec07cd6ec2634))
|
||||
- Fixed FixedNumber rounding for non-default formats. ([#1629](https://github.com/ethers-io/ethers.js/issues/1629); [8681cd5](https://github.com/ethers-io/ethers.js/commit/8681cd59698d02d040871aa889fc6ccc8550df98))
|
||||
- Update ws dependency version to fix security. ([#1633](https://github.com/ethers-io/ethers.js/issues/1633), [#1634](https://github.com/ethers-io/ethers.js/issues/1634); [470551e](https://github.com/ethers-io/ethers.js/commit/470551e4ee3f1e343a26fc0775f9d9f7489129f8))
|
||||
|
||||
ethers/v5.2.0 (2021-05-17 16:18)
|
||||
--------------------------------
|
||||
|
||||
- More aggresively check for mempool transactions sent from JsonRpcSigner. ([3316468](https://github.com/ethers-io/ethers.js/commit/3316468e3e0a5925cbecad85d894cc7d622394e7))
|
||||
- Added initial support for detecting replacement transactions. ([#1477](https://github.com/ethers-io/ethers.js/issues/1477); [987bec8](https://github.com/ethers-io/ethers.js/commit/987bec87afaa365f291290a0136cedbc2b1992f2), [5144acf](https://github.com/ethers-io/ethers.js/commit/5144acf456b51c95bbe3950bd37609abecc7ebc7))
|
||||
- Added convenience method for HD path derivation. ([aadc5cd](https://github.com/ethers-io/ethers.js/commit/aadc5cd3d65421e13ebd4e4d7c293ac3ece5e178))
|
||||
- Added mnemonicPath option to cli. ([6e08809](https://github.com/ethers-io/ethers.js/commit/6e088099adabd7c5d2e6710062ebc62b316ba0f1))
|
||||
- Added some popular Ethereum-compatible chains to networks. ([b6370f1](https://github.com/ethers-io/ethers.js/commit/b6370f13600a0c444342cbf16a83f010a929976b))
|
||||
- Added debug event to Web3Provider. ([26464c5](https://github.com/ethers-io/ethers.js/commit/26464c54258f98c321638475d6cf11595186e76d))
|
||||
- Abstracted EtherscanProivder to more easily fascilitate other Etherscan-supported chains. ([#1204](https://github.com/ethers-io/ethers.js/issues/1204), [#1473](https://github.com/ethers-io/ethers.js/issues/1473); [37a9c77](https://github.com/ethers-io/ethers.js/commit/37a9c77ab2acb7f75e1fc4cc918810d2fe59dd76))
|
||||
- Added Custom Contract Errors. ([#1498](https://github.com/ethers-io/ethers.js/issues/1498); [6519609](https://github.com/ethers-io/ethers.js/commit/65196097f6626401638d85cf19e3d628a6223d5d), [483d67f](https://github.com/ethers-io/ethers.js/commit/483d67f55c15a76bcd853e889a0e35815d9850f7))
|
||||
- More flexible FixedNumber input and output for strings with no decimals. ([#1019](https://github.com/ethers-io/ethers.js/issues/1019), [#1291](https://github.com/ethers-io/ethers.js/issues/1291), [#1463](https://github.com/ethers-io/ethers.js/issues/1463); [a9cdbe1](https://github.com/ethers-io/ethers.js/commit/a9cdbe1238c149a7167c6bb1a78f314805b52755))
|
||||
- Added hex support for bigint. ([#1472](https://github.com/ethers-io/ethers.js/issues/1472); [4e9abfd](https://github.com/ethers-io/ethers.js/commit/4e9abfdee478a8423da4d55feea8c1aae78a8eb4))
|
||||
- Added support for null entries in EventFilter. ([#1499](https://github.com/ethers-io/ethers.js/issues/1499); [3bb5fbf](https://github.com/ethers-io/ethers.js/commit/3bb5fbf533107e880377ecc14f30f314a5028e56))
|
||||
- Add bigint to allowed BigNumberish types. ([#1472](https://github.com/ethers-io/ethers.js/issues/1472); [cadccc3](https://github.com/ethers-io/ethers.js/commit/cadccc3060b88ab2ca64aeb302717d2d1c95a897))
|
||||
- Minor version bump. ([8e22e02](https://github.com/ethers-io/ethers.js/commit/8e22e0260eb70713c943c9e99ee8d66d71ebe56d))
|
||||
|
||||
ethers/v5.1.4 (2021-04-22 06:33)
|
||||
--------------------------------
|
||||
|
||||
- Do not throw on ABI "error" type. ([#1493](https://github.com/ethers-io/ethers.js/issues/1493), [#1497](https://github.com/ethers-io/ethers.js/issues/1497); [bd05aed](https://github.com/ethers-io/ethers.js/commit/bd05aed070ac9e1421a3e2bff2ceea150bedf9b7))
|
||||
|
||||
ethers/v5.1.3 (2021-04-19 21:01)
|
||||
--------------------------------
|
||||
|
||||
- Fixed JsonRpcProvider event-loop caching when using any network. ([#1484](https://github.com/ethers-io/ethers.js/issues/1484); [58488e7](https://github.com/ethers-io/ethers.js/commit/58488e78f9ef79715693e19b42663335aad88c03))
|
||||
- Updated experimental Eip1193Bridge to support final EIP-1193 API. ([2911659](https://github.com/ethers-io/ethers.js/commit/29116593ba6c9c0fa491b13787cca8b233d4218c))
|
||||
- Fail early for ABI decoding that will obviously run out of data. ([#1486](https://github.com/ethers-io/ethers.js/issues/1486); [51f0e1a](https://github.com/ethers-io/ethers.js/commit/51f0e1a52fb885e6f146f7b3b70ed487fd1c8f5a))
|
||||
- Fixed BigNumber toBigInt return type. ([#1485](https://github.com/ethers-io/ethers.js/issues/1485); [c086962](https://github.com/ethers-io/ethers.js/commit/c0869623024bbf3671938dad03b131ff2ac54345))
|
||||
|
||||
ethers/v5.1.2 (2021-04-18 19:31)
|
||||
--------------------------------
|
||||
|
||||
- Increase provider tests gas price for sending a transaction. ([8eaeba3](https://github.com/ethers-io/ethers.js/commit/8eaeba35f550c3d9aa1ae62eb8d8e0c912818f7f))
|
||||
- Fixed run-checking non-filter Contract events. ([#1458](https://github.com/ethers-io/ethers.js/issues/1458); [4a44865](https://github.com/ethers-io/ethers.js/commit/4a44865a8c22adb9c55d5c37a81ee46ebc68228c))
|
||||
|
||||
ethers/v5.1.1 (2021-04-18 02:47)
|
||||
--------------------------------
|
||||
|
||||
- Increased sendTransaction timeout to 15 minutes and pull Pocket from tx tests. ([08adc18](https://github.com/ethers-io/ethers.js/commit/08adc18a68bdc730633bdaaf2329014a84c12b2b))
|
||||
- Export Eip1193Bridge in experimental package. ([1fcf4b6](https://github.com/ethers-io/ethers.js/commit/1fcf4b6ce6922d2bcb245375c967da3072f113ed))
|
||||
- Prevent non-typed transactions from unsafely ignoring specified access lists. ([#1364](https://github.com/ethers-io/ethers.js/issues/1364); [4577444](https://github.com/ethers-io/ethers.js/commit/4577444c448f41114263077c5b54fbe6af749fd4))
|
||||
- Update tests for current EIP-2930 support across backends. ([#1364](https://github.com/ethers-io/ethers.js/issues/1364); [1cb3199](https://github.com/ethers-io/ethers.js/commit/1cb3199e5cb01f5a55eb00ab6c7904606d7ea1dd))
|
||||
- Removed underscore from the JsonRpcBatchProvider name. ([#62](https://github.com/ethers-io/ethers.js/issues/62), [#656](https://github.com/ethers-io/ethers.js/issues/656), [#892](https://github.com/ethers-io/ethers.js/issues/892); [ae0d5eb](https://github.com/ethers-io/ethers.js/commit/ae0d5eb7c2e37a003d893671db59c2d5719aea0f))
|
||||
- Added better error detection when pre-EIP-155 transactions are disabled. ([b8df000](https://github.com/ethers-io/ethers.js/commit/b8df000c8f0ccd252b6049ac5a32a986d5a8e08d))
|
||||
- Fix Android React Native environment shims which crash on normalizing Korean test. ([#1298](https://github.com/ethers-io/ethers.js/issues/1298); [eb1ec2f](https://github.com/ethers-io/ethers.js/commit/eb1ec2f2318e2851073ea1634e5003cdb53f1c1b))
|
||||
- Fixed EIP-2930 transactions for EtherscanProvider. ([#1364](https://github.com/ethers-io/ethers.js/issues/1364); [b655089](https://github.com/ethers-io/ethers.js/commit/b65508995ce7d02f109a970ebeb625819beb915a))
|
||||
- Re-enable AlchemyProvider Berlin tests. ([bec066b](https://github.com/ethers-io/ethers.js/commit/bec066bcb5ab8b95a7e7ce4848d7b76d7f248ccc))
|
||||
- Added experimental _JsonRpcBatchProvider. ([#62](https://github.com/ethers-io/ethers.js/issues/62), [#656](https://github.com/ethers-io/ethers.js/issues/656), [#892](https://github.com/ethers-io/ethers.js/issues/892); [d55ab6d](https://github.com/ethers-io/ethers.js/commit/d55ab6d4e6025c484cc7e64486d927bd54a0772b))
|
||||
- Cache JsonRpcProvider requests for certain methods per event loop. ([#1371](https://github.com/ethers-io/ethers.js/issues/1371); [1a7c4e8](https://github.com/ethers-io/ethers.js/commit/1a7c4e89efecc2b8afc8bea4c1f8f75fdaac08c5))
|
||||
|
||||
ethers/v5.1.0 (2021-03-30 14:44)
|
||||
--------------------------------
|
||||
|
||||
- Added BigNumber.toBigInt method. ([#1415](https://github.com/ethers-io/ethers.js/issues/1415); [81fd628](https://github.com/ethers-io/ethers.js/commit/81fd628292b7dde90fe5115074fa68476a872dbf))
|
||||
- Abstracted Contract with BaseContract without meta-class properties for easier extensions. ([#1384](https://github.com/ethers-io/ethers.js/issues/1384); [87ceaed](https://github.com/ethers-io/ethers.js/commit/87ceaed4be21283619da74678cf371c228c918b7))
|
||||
- Fixed Contract properties that collide with null member properties. ([#1393](https://github.com/ethers-io/ethers.js/issues/1393); [0e1721b](https://github.com/ethers-io/ethers.js/commit/0e1721b13084dacf63089e47116f7d5331be4f36))
|
||||
- Added EIP-2930 support. ([#1364](https://github.com/ethers-io/ethers.js/issues/1364); [c47d2eb](https://github.com/ethers-io/ethers.js/commit/c47d2eba4dc741eb5cb754c3ef5064b8ea7ac7cc))
|
||||
- Added abstraction for EIP-2718 support. ([1db4ce1](https://github.com/ethers-io/ethers.js/commit/1db4ce12d49e235a7155de24ee153f409e7e7370))
|
||||
|
||||
ethers/v5.0.32 (2021-03-07 18:17)
|
||||
---------------------------------
|
||||
|
||||
- Added Linea Sepolia network and Infura endpoint ([#4655](https://github.com/ethers-io/ethers.js/issues/4655); [b4aaab8](https://github.com/ethers-io/ethers.js/commit/b4aaab8d39fe47f8a1a296fa442f0856f84faf03)).
|
||||
- Do not send unsubscribe messages to destroyed Providers ([#4678](https://github.com/ethers-io/ethers.js/issues/4678); [c45935e](https://github.com/ethers-io/ethers.js/commit/c45935e29ca0dd1ecdf1277fa1107246041be580)).
|
||||
- Get definitive network from InfuraProvider when using InfuraWebSocketProvider ([38e32d8](https://github.com/ethers-io/ethers.js/commit/38e32d82145eb289e5179f9b6b11f4a9225a7022)).
|
||||
- Better error messages for transaction field mismatch ([#4659](https://github.com/ethers-io/ethers.js/issues/4659); [9230aa0](https://github.com/ethers-io/ethers.js/commit/9230aa0b9a88b5241915a8d6afa8a522d35abd5d)).
|
||||
- Added prevRandao to block ([#3372](https://github.com/ethers-io/ethers.js/issues/3372); [ec6a754](https://github.com/ethers-io/ethers.js/commit/ec6a754f0c8647dae59c73b2589225cb200d83dd)).
|
||||
- Added Polygon Amoy testnet ([#4645](https://github.com/ethers-io/ethers.js/issues/4645); [1717abb](https://github.com/ethers-io/ethers.js/commit/1717abbf29a14a6f6b106e479fe9a5b1f8768dc4)).
|
||||
- Added Chainstack provider ([#2741](https://github.com/ethers-io/ethers.js/issues/2741); [014004d](https://github.com/ethers-io/ethers.js/commit/014004d9402d7fd8c15553792cfb7a8a84ed327a)).
|
||||
- Added deep convertion to Result for toObject and toArray ([#4681](https://github.com/ethers-io/ethers.js/issues/4681); [03bfe2a](https://github.com/ethers-io/ethers.js/commit/03bfe2a4f7b29b15cd90127974b7fc1d8b03edf9)).
|
||||
- Added EIP-4844 broadcast support ([92bad88](https://github.com/ethers-io/ethers.js/commit/92bad88261a5d8a538535a7d5528162fe5010527)).
|
||||
- Fix ignored throttle parameters ([#4663](https://github.com/ethers-io/ethers.js/issues/4663); [12772e9](https://github.com/ethers-io/ethers.js/commit/12772e9498b70f8538838f30e16f3792ea90e173)).
|
||||
- Bumped TypeScript to 4.2.2. ([#1288](https://github.com/ethers-io/ethers.js/issues/1288); [b2ecffb](https://github.com/ethers-io/ethers.js/commit/b2ecffb0c8d44c8ee65199e7866dc744abae4e6e))
|
||||
- Fixed shims from not displaying debug information. ([a953f71](https://github.com/ethers-io/ethers.js/commit/a953f717523a844a3a45810a5acc6630383884d3))
|
||||
- Force TypedData numbers to be in decimal. ([#1193](https://github.com/ethers-io/ethers.js/issues/1193); [c5a53d6](https://github.com/ethers-io/ethers.js/commit/c5a53d6911d7c41dd03a290b550e80f2919e9379))
|
||||
|
||||
ethers/v6.11.1 (2024-02-14 13:13)
|
||||
ethers/v5.0.31 (2021-02-12 19:04)
|
||||
---------------------------------
|
||||
|
||||
- Throw an error when attempting to derive from a master path from a non-master node ([#4551](https://github.com/ethers-io/ethers.js/issues/4551); [556fdd9](https://github.com/ethers-io/ethers.js/commit/556fdd91d9b6bf7db4041bb099e66b2080e1a985)).
|
||||
- Allow ENS wildcards with labels up to 255 bytes wide; discussed with ENS and deemed safe ([#4543](https://github.com/ethers-io/ethers.js/issues/4543); [7f14bde](https://github.com/ethers-io/ethers.js/commit/7f14bdebf1aef6760462a1c2437c31f002b984fe)).
|
||||
- Enforce string is passed to toUtf8Bytes ([#4583](https://github.com/ethers-io/ethers.js/issues/4583); [f45bb87](https://github.com/ethers-io/ethers.js/commit/f45bb87aefaf2c6c3a4991f6e30a81c227ae83c0)).
|
||||
- Fix transaction.index not being populated on some backends ([#4591](https://github.com/ethers-io/ethers.js/issues/4591); [7f0e140](https://github.com/ethers-io/ethers.js/commit/7f0e140d5e3925a42e8bb2ac9eb1ba3fbd939864)).
|
||||
- Prevent unhandled rejections when passing nullish into Contract constructor. ([#1234](https://github.com/ethers-io/ethers.js/issues/1234); [d937668](https://github.com/ethers-io/ethers.js/commit/d937668dc1d39cc293f64bbd30b99b29614d1607))
|
||||
- Better error messaging when provider backends give bogus responses. ([#1243](https://github.com/ethers-io/ethers.js/issues/1243); [8279120](https://github.com/ethers-io/ethers.js/commit/8279120e0ad1cbb7aeabd32c08e168a4228abbec))
|
||||
- Prevent unconfigured ENS names from making an init tx. ([#1290](https://github.com/ethers-io/ethers.js/issues/1290); [243beff](https://github.com/ethers-io/ethers.js/commit/243beffa4f83c910f5f1c5e0554531e5dcf3ab93))
|
||||
|
||||
ethers/v6.11.0 (2024-02-08 20:26)
|
||||
ethers/v5.0.30 (2021-02-08 15:22)
|
||||
---------------------------------
|
||||
|
||||
- Allow transaction encoding for inferred type transactions ([f02211d](https://github.com/ethers-io/ethers.js/commit/f02211d055567b51373b5faa2c3dc6efe0523618)).
|
||||
- Added EIP-4788, receipts root and state root fields to Block ([#4570](https://github.com/ethers-io/ethers.js/issues/4570); [c5f126f](https://github.com/ethers-io/ethers.js/commit/c5f126faf7d826b6a99df0ee578ff3d0ef409381)).
|
||||
- Added EIP-4844 fields to Provider classes and formatter ([#4570](https://github.com/ethers-io/ethers.js/issues/4570); [7b4f2c1](https://github.com/ethers-io/ethers.js/commit/7b4f2c1a74db411829b5e8ef758bfa2ee21e5890)).
|
||||
- Assert BrowserProvider receives an EIP-1193 provider to fail early when passing undefined ethereum object ([b69f43b](https://github.com/ethers-io/ethers.js/commit/b69f43bc6f35da881ca7a0c8ccc5fda92edd076d)).
|
||||
- Add timeout to ContractTransactionResponse wait ([#4497](https://github.com/ethers-io/ethers.js/issues/4497); [095de51](https://github.com/ethers-io/ethers.js/commit/095de51e605a9b88576e5e34fd55a6e32befa4eb)).
|
||||
- Allow override keyword in human-readable ABI and improve error messages ([#4514](https://github.com/ethers-io/ethers.js/issues/4514), [#4548](https://github.com/ethers-io/ethers.js/issues/4548); [be5ec2d](https://github.com/ethers-io/ethers.js/commit/be5ec2d327a503b2e5fc0f37c47eee9e828f8e23)).
|
||||
- Expand Contract sub-class to accept BaseContract super-class constructor arguments ([#4538](https://github.com/ethers-io/ethers.js/issues/4538); [98496bc](https://github.com/ethers-io/ethers.js/commit/98496bc48ec23ce0d9c21d3c6c87e5b1b796a610)).
|
||||
- Allow network for default provider to be null to select mainnet ([#4501](https://github.com/ethers-io/ethers.js/issues/4501); [b6bf7ab](https://github.com/ethers-io/ethers.js/commit/b6bf7aba62fb38839cd01858432b801cc5c28a11)).
|
||||
- Allow long dnsEncode names with optional length parameter ([#4543](https://github.com/ethers-io/ethers.js/issues/4543); [a136348](https://github.com/ethers-io/ethers.js/commit/a1363483a56b0dee342595c8f44ed8fcce7ecca9)).
|
||||
- Fix parseLog signature when receiving read-only array for topics ([#4029](https://github.com/ethers-io/ethers.js/issues/4029), [#4459](https://github.com/ethers-io/ethers.js/issues/4459); [20cd8a2](https://github.com/ethers-io/ethers.js/commit/20cd8a23eaf8e8a14e2b51f7f64da4cb3e32fccb)).
|
||||
- Use Secure endpoints for BNB on Etherscan ([#4525](https://github.com/ethers-io/ethers.js/issues/4525); [1f6e188](https://github.com/ethers-io/ethers.js/commit/1f6e1882515195bd67f0bce9fe347ec05107324b)).
|
||||
- Added holesky network and related end-points for supporting providers ([c6e6c43](https://github.com/ethers-io/ethers.js/commit/c6e6c432574a0b7e55c300ab3e470aafdace28b3)).
|
||||
- Added EIP-4844 BLOb transactions ([#4554](https://github.com/ethers-io/ethers.js/issues/4554); [9c1e82e](https://github.com/ethers-io/ethers.js/commit/9c1e82e1230526ebcd62902890c4f24b1f7f7d79)).
|
||||
- Normalize EIP-712 types before computing the payload ([#4541](https://github.com/ethers-io/ethers.js/issues/4541); [56c1361](https://github.com/ethers-io/ethers.js/commit/56c1361ee83db8b68859caf0850c95ff70e7e306)).
|
||||
- Updated thrid-part provider URLs for QuickNode ([2b4891d](https://github.com/ethers-io/ethers.js/commit/2b4891d86e72e849079cb1dc98b18e158b0c0620)).
|
||||
- Fixed normalization and abstracted EIP-712 Array parsing ([#4541](https://github.com/ethers-io/ethers.js/issues/4541); [8f99601](https://github.com/ethers-io/ethers.js/commit/8f99601df1f26a8ba4d6d9dea5e033e7f688107e)).
|
||||
- Updated third-party provider network URLs ([#4542](https://github.com/ethers-io/ethers.js/issues/4542); [84ca14f](https://github.com/ethers-io/ethers.js/commit/84ca14f1ffc5afbdd7f4c26a9b734ec5951eee3c)).
|
||||
- Added additional sepolia testnets ([4efef76](https://github.com/ethers-io/ethers.js/commit/4efef76e8cab0acaf1b2ba231a0148f9381bb1ee)).
|
||||
- Fix EIP-712 type aliases for uint and int ([#4541](https://github.com/ethers-io/ethers.js/issues/4541); [43fb9c2](https://github.com/ethers-io/ethers.js/commit/43fb9c233696aeaa80b1c2b0e5fafce90e0ad508)).
|
||||
- Fixed typo in Error string ([#4539](https://github.com/ethers-io/ethers.js/issues/4539); [7882905](https://github.com/ethers-io/ethers.js/commit/78829050853093bc5291ae78fc5a904044759aa0)).
|
||||
- Better debugging output on fetch errors ([bee07a0](https://github.com/ethers-io/ethers.js/commit/bee07a0750b448a9d13c2d57014bcf27f43e2ed7)).
|
||||
- When in Status trigger personal_sign instead of eth_sign. ([#1285](https://github.com/ethers-io/ethers.js/issues/1285); [73e9434](https://github.com/ethers-io/ethers.js/commit/73e94349de94d2969ccb21c834119525ddfcb961))
|
||||
- Bump elliptic version for CVE-2020-28498. ([#1284](https://github.com/ethers-io/ethers.js/issues/1284); [796954f](https://github.com/ethers-io/ethers.js/commit/796954f8807b0c464c7baa8f7ff299e22685e192))
|
||||
|
||||
ethers/v6.10.0 (2024-01-12 19:46)
|
||||
ethers/v5.0.29 (2021-02-03 14:36)
|
||||
---------------------------------
|
||||
|
||||
- Limit decoded result imflation ratio from ABI-encoded data ([#4537](https://github.com/ethers-io/ethers.js/issues/4537); [1b4debd](https://github.com/ethers-io/ethers.js/commit/1b4debd4a9e61d171bfc60590116facb8bdbd2da)).
|
||||
- Fixed typos in JSON ABI formatting. ([#1275](https://github.com/ethers-io/ethers.js/issues/1275); [73b31b3](https://github.com/ethers-io/ethers.js/commit/73b31b371fa47bacc4f5f6bed01d0d1e5d66fa2c))
|
||||
|
||||
ethers/v6.9.2 (2024-01-02 19:12)
|
||||
ethers/v5.0.28 (2021-02-02 17:12)
|
||||
---------------------------------
|
||||
|
||||
- Added load balancer support to PocketProvider. ([#1052](https://github.com/ethers-io/ethers.js/issues/1052); [27a981c](https://github.com/ethers-io/ethers.js/commit/27a981c84b578feb762fdb37dd5325d9c335bd59))
|
||||
|
||||
ethers/v5.0.27 (2021-02-01 15:55)
|
||||
---------------------------------
|
||||
|
||||
- Added support for networks with slightly incorrect EIP-658 implementations. ([#952](https://github.com/ethers-io/ethers.js/issues/952), [#1251](https://github.com/ethers-io/ethers.js/issues/1251); [e727efc](https://github.com/ethers-io/ethers.js/commit/e727efc33eaa31c3af6adbb64a893caf354d0ba7))
|
||||
- Added Pocket network to the default provider. ([#1030](https://github.com/ethers-io/ethers.js/issues/1030), [#1052](https://github.com/ethers-io/ethers.js/issues/1052); [4af2c19](https://github.com/ethers-io/ethers.js/commit/4af2c19f455bb43406d3cc5421c3b3fdda75f78f))
|
||||
- Added TypeScript declaration maps. ([#401](https://github.com/ethers-io/ethers.js/issues/401); [3396846](https://github.com/ethers-io/ethers.js/commit/3396846a30a4be0ed58fe449589e7e4e54f3d32e))
|
||||
|
||||
ethers/v5.0.26 (2021-01-13 14:47)
|
||||
---------------------------------
|
||||
|
||||
- Fixed abundant UnhandledRejectErrors in provider polling. ([#1084](https://github.com/ethers-io/ethers.js/issues/1084), [#1208](https://github.com/ethers-io/ethers.js/issues/1208), [#1221](https://github.com/ethers-io/ethers.js/issues/1221), [#1235](https://github.com/ethers-io/ethers.js/issues/1235); [74470de](https://github.com/ethers-io/ethers.js/commit/74470defda5170338735bbbe676c207cdd5cc1cf), [20f6e16](https://github.com/ethers-io/ethers.js/commit/20f6e16394909a43498c1ac6c73152957bd121bd))
|
||||
- Fixed non-checksum address comparisons in abstract Signer. ([#1236](https://github.com/ethers-io/ethers.js/issues/1236); [8175c83](https://github.com/ethers-io/ethers.js/commit/8175c83026436b6335800780ca12b7257e1b490f))
|
||||
|
||||
ethers/v5.0.25 (2021-01-08 03:31)
|
||||
---------------------------------
|
||||
|
||||
- Safety check on digest length for signing. ([20335e9](https://github.com/ethers-io/ethers.js/commit/20335e96c2429e851081b72031ea3fd4cd677904))
|
||||
- Fixed listenerCount for contract when requesting for all events. ([#1205](https://github.com/ethers-io/ethers.js/issues/1205); [a56a0a3](https://github.com/ethers-io/ethers.js/commit/a56a0a33366ea9276fba5bc45f1e4678dd723fa6))
|
||||
- Lock package versions for the ESM builds. ([#1009](https://github.com/ethers-io/ethers.js/issues/1009); [0e6cc9a](https://github.com/ethers-io/ethers.js/commit/0e6cc9a9a8ebceae4529ccbb7c107618eb54490a))
|
||||
|
||||
ethers/v5.0.24 (2020-12-08 01:43)
|
||||
---------------------------------
|
||||
|
||||
- Fixed EIP-712 getPayload dropping EIP712Domain from types for JSON-RPC calls. ([#687](https://github.com/ethers-io/ethers.js/issues/687); [d3b1ac0](https://github.com/ethers-io/ethers.js/commit/d3b1ac046aaf2a46f6c3efbd93c55adb0cb8f16d))
|
||||
- Remvoed dead files. ([70c2b1b](https://github.com/ethers-io/ethers.js/commit/70c2b1b3002f44c39f4fd87fc2cfc3f5dc6555ed))
|
||||
|
||||
ethers/v5.0.23 (2020-11-25 15:25)
|
||||
---------------------------------
|
||||
|
||||
- Fix BigNumber when passed something with a length property. ([#1172](https://github.com/ethers-io/ethers.js/issues/1172); [45a2902](https://github.com/ethers-io/ethers.js/commit/45a2902874e828a16396a253548bcb00bceccf95))
|
||||
|
||||
ethers/v5.0.22 (2020-11-23 19:16)
|
||||
---------------------------------
|
||||
|
||||
- Added directory to repo field for each package. ([799896a](https://github.com/ethers-io/ethers.js/commit/799896ac13cce857ce0124d2fb480f5d1eed114c))
|
||||
- Add ABI coder function to compute default values. ([#1101](https://github.com/ethers-io/ethers.js/issues/1101); [a8e3380](https://github.com/ethers-io/ethers.js/commit/a8e3380ed547b6368be5fe40b48be6e31b5cdd93))
|
||||
- Fix for new versions of Geth which return formatted data on revert rather than standard data. ([#949](https://github.com/ethers-io/ethers.js/issues/949); [4a8d579](https://github.com/ethers-io/ethers.js/commit/4a8d579dcaf026d0c232e20176605d34cba4767d))
|
||||
- Addd missing sideEffects flag to some packages. ([20defec](https://github.com/ethers-io/ethers.js/commit/20defec9f1683487b6ea9c8730d2ab7b3745bfa5))
|
||||
- Allow base-10 to be passed into BigNumbner.toString and improve errors for other radices. ([#1164](https://github.com/ethers-io/ethers.js/issues/1164); [c8bb77d](https://github.com/ethers-io/ethers.js/commit/c8bb77d8af85d2f9f9df82f1afbe7516ab296e98), [fbbe4ad](https://github.com/ethers-io/ethers.js/commit/fbbe4ad638e06089cdd976a7f4ffd51b85a31558))
|
||||
- Allow private keys to Wallet to omit the 0x prefix. ([#1166](https://github.com/ethers-io/ethers.js/issues/1166); [29f6c34](https://github.com/ethers-io/ethers.js/commit/29f6c34343d75fa42023bdcd07632f49a450570c))
|
||||
|
||||
ethers/v5.0.21 (2020-11-19 18:52)
|
||||
---------------------------------
|
||||
|
||||
- Force address to use bignumber package with base36 private functions. ([#1163](https://github.com/ethers-io/ethers.js/issues/1163); [c9e5480](https://github.com/ethers-io/ethers.js/commit/c9e548071e9ed03e3b12f40f0be779c16422a73f))
|
||||
- Remove stray console.log in hardware wallets. ([#1136](https://github.com/ethers-io/ethers.js/issues/1136); [cc63e61](https://github.com/ethers-io/ethers.js/commit/cc63e61f73d530c28655f9421506a25fc0a49df0))
|
||||
- Added some funding links for the sponsor button. ([2816850](https://github.com/ethers-io/ethers.js/commit/2816850716d4bf2b458f1db4e0c7a5dc09fb14f7))
|
||||
- Remove invalid pkg.module reference. ([#1133](https://github.com/ethers-io/ethers.js/issues/1133); [cddc258](https://github.com/ethers-io/ethers.js/commit/cddc258c963ab63de426b89ef190b83aefe6f6cd))
|
||||
|
||||
ethers/v5.0.20 (2020-11-17 20:32)
|
||||
---------------------------------
|
||||
|
||||
- Fix browser ws alias for WebSockets. ([02546b9](https://github.com/ethers-io/ethers.js/commit/02546b9401d8066135b4453da917f7ef49c95ad8))
|
||||
- Fixing React Native tests. ([f10977a](https://github.com/ethers-io/ethers.js/commit/f10977ab35f953c3148d99b61799788f47d2a5a2), [fff72ef](https://github.com/ethers-io/ethers.js/commit/fff72ef369f5420bf8283b0808e8fec71f26dd2b))
|
||||
- Refactoring dist build process. ([4809325](https://github.com/ethers-io/ethers.js/commit/4809325bee9cbdd269b099d7b12b218f441ac840), [22bd0c7](https://github.com/ethers-io/ethers.js/commit/22bd0c76dddef7134618ec70ac1b084a054e616e), [8933467](https://github.com/ethers-io/ethers.js/commit/8933467c01b64ead547d7c136f22f3c05c85ca1f))
|
||||
|
||||
ethers/v5.0.19 (2020-10-22 21:55)
|
||||
---------------------------------
|
||||
|
||||
- Allow 0x as a numeric value for 0 in Provider formatter. ([#1104](https://github.com/ethers-io/ethers.js/issues/1104); [fe17a29](https://github.com/ethers-io/ethers.js/commit/fe17a295816214d063f3d6bd4f3273e0ce0c3eac))
|
||||
- Use POST for long requests in EtherscanProvider. ([#1093](https://github.com/ethers-io/ethers.js/issues/1093); [28f60d5](https://github.com/ethers-io/ethers.js/commit/28f60d5ef83665541c8c1b432f8e173d73cb8227))
|
||||
- Added verifyTypedData for EIP-712 typed data. ([#687](https://github.com/ethers-io/ethers.js/issues/687); [550ecf2](https://github.com/ethers-io/ethers.js/commit/550ecf2f25b90f6d8996583489a218dbf2306ebc), [a21202c](https://github.com/ethers-io/ethers.js/commit/a21202c66b392ec6f91296d66551dffca742cf0a))
|
||||
|
||||
ethers/v5.0.18 (2020-10-19 01:26)
|
||||
---------------------------------
|
||||
|
||||
- Fix signTypedData call for JsonRpcSigner. ([#687](https://github.com/ethers-io/ethers.js/issues/687); [15a90af](https://github.com/ethers-io/ethers.js/commit/15a90af5be75806e26f589f0a3f3687c0fb1c672))
|
||||
- Added EIP-712 test cases. ([#687](https://github.com/ethers-io/ethers.js/issues/687); [1589353](https://github.com/ethers-io/ethers.js/commit/15893537c3d9c92fe8748a3e9617d133d1d5d6a7))
|
||||
- Initial Signer support for EIP-712 signed typed data. ([#687](https://github.com/ethers-io/ethers.js/issues/687); [be4e216](https://github.com/ethers-io/ethers.js/commit/be4e2164e64dfa0697561763e8079120a485a566))
|
||||
- Split hash library files up. ([3e676f2](https://github.com/ethers-io/ethers.js/commit/3e676f21b00931ed966f4561e4f28792a1f8f154))
|
||||
- Added EIP-712 multi-dimensional array support. ([#687](https://github.com/ethers-io/ethers.js/issues/687); [5a4dd5a](https://github.com/ethers-io/ethers.js/commit/5a4dd5a70377d3e86823d279d6ff466d03767644))
|
||||
- Consolidated TypedDataEncoder methods. ([#687](https://github.com/ethers-io/ethers.js/issues/687); [345a830](https://github.com/ethers-io/ethers.js/commit/345a830dc4bc869d5f3edfdc27465797e7663055))
|
||||
- Initial EIP-712 utilities. ([#687](https://github.com/ethers-io/ethers.js/issues/687); [cfa6dec](https://github.com/ethers-io/ethers.js/commit/cfa6dec29314fe485df283974612d40550bc4179))
|
||||
- Added initial PocketProvider. ([#1052](https://github.com/ethers-io/ethers.js/issues/1052); [a62d20d](https://github.com/ethers-io/ethers.js/commit/a62d20d86f2d545b9a7bcda5418993790b7db91c))
|
||||
|
||||
ethers/v5.0.17 (2020-10-07 20:08)
|
||||
---------------------------------
|
||||
|
||||
- Better error message for parseUnits of non-strings. ([#981](https://github.com/ethers-io/ethers.js/issues/981); [5abc2f3](https://github.com/ethers-io/ethers.js/commit/5abc2f36e20eef79a935961f3dd8133b5528d9e5))
|
||||
- Add gzip support to AlchemyProivder and InfuraProvider fetching. ([#1085](https://github.com/ethers-io/ethers.js/issues/1085); [38a068b](https://github.com/ethers-io/ethers.js/commit/38a068bcea3f251c8f3a349a90fcb077a39d23ad))
|
||||
- Add gzip support to getUrl in node. ([#1085](https://github.com/ethers-io/ethers.js/issues/1085); [65772a8](https://github.com/ethers-io/ethers.js/commit/65772a8e1a55d663bdb67e3a2b160fecc9f986ef))
|
||||
- Added CommunityResourcable to mark Providers as highly throttled. ([a022093](https://github.com/ethers-io/ethers.js/commit/a022093ce03f55db7ba2cac36e365d1af39ac45b))
|
||||
- Added debug event info to WebSocketProvider. ([#1018](https://github.com/ethers-io/ethers.js/issues/1018); [8e682cc](https://github.com/ethers-io/ethers.js/commit/8e682cc8481c6051a6f8115b29d78f4996120ccd))
|
||||
|
||||
ethers/v5.0.16 (2020-10-05 15:44)
|
||||
---------------------------------
|
||||
|
||||
- ABI encoding performance additions. ([#1012](https://github.com/ethers-io/ethers.js/issues/1012); [f3e5b0d](https://github.com/ethers-io/ethers.js/commit/f3e5b0ded1b227a377fd4799507653c95c76e353))
|
||||
- Export hexConcat in utils. ([#1079](https://github.com/ethers-io/ethers.js/issues/1079); [3d051e4](https://github.com/ethers-io/ethers.js/commit/3d051e454db978f58c7b38ff4484096c3eb85b94))
|
||||
- Cache chain ID for WebSocketProvider. ([#1054](https://github.com/ethers-io/ethers.js/issues/1054); [40264ff](https://github.com/ethers-io/ethers.js/commit/40264ff9006156ba8441e6101e5a7149a5cf03f6))
|
||||
|
||||
ethers/v5.0.15 (2020-09-26 03:22)
|
||||
---------------------------------
|
||||
|
||||
- Add more accurate intrinsic gas cost to ABI calls with specified gas property. ([#1058](https://github.com/ethers-io/ethers.js/issues/1058); [f0a5869](https://github.com/ethers-io/ethers.js/commit/f0a5869c53475e55a5f47d8651f609fff45dc9a7))
|
||||
- Better errors for unconfigured ENS names. ([#1066](https://github.com/ethers-io/ethers.js/issues/1066); [5cd1668](https://github.com/ethers-io/ethers.js/commit/5cd1668e0d29099c5b7ce1fdc1d0e8a41af1a249))
|
||||
- Updated CLI solc to versin 0.7.1. ([4306b35](https://github.com/ethers-io/ethers.js/commit/4306b3563a171baa9d7bf4872475a13c3434f834))
|
||||
|
||||
ethers/v5.0.14 (2020-09-16 02:39)
|
||||
---------------------------------
|
||||
|
||||
- More robust blockchain error detection ([#1047](https://github.com/ethers-io/ethers.js/issues/1047); [49f7157](https://github.com/ethers-io/ethers.js/commit/49f71574f4799d685a5ae8fd24fe1134f752d70a))
|
||||
- Forward blockchain errors from Signer during gas estimation. ([#1047](https://github.com/ethers-io/ethers.js/issues/1047); [9ee685d](https://github.com/ethers-io/ethers.js/commit/9ee685df46753c46cbbde12d05d6ea04f2b5ea3f))
|
||||
- Improve fetch errors with looser mime-type detection. ([#1047](https://github.com/ethers-io/ethers.js/issues/1047); [263bfe5](https://github.com/ethers-io/ethers.js/commit/263bfe5ce632790e0399d06a0ab660a501997998))
|
||||
|
||||
ethers/v5.0.13 (2020-09-11 02:10)
|
||||
---------------------------------
|
||||
|
||||
- Force content-length in web fetching. ([be92339](https://github.com/ethers-io/ethers.js/commit/be923396962ea76bf0fb566dcf8801e58ccf0e7e))
|
||||
- Better error forwarding from FallbackProvider. ([#1021](https://github.com/ethers-io/ethers.js/issues/1021); [bc3eeec](https://github.com/ethers-io/ethers.js/commit/bc3eeeca39adb734f24019d0e942eff2eac6ad4d))
|
||||
- Add clamping functions to FixedNumber. ([#1037](https://github.com/ethers-io/ethers.js/issues/1037); [042b74e](https://github.com/ethers-io/ethers.js/commit/042b74e6ee648d4fa37bf674194273d8f4483bfb))
|
||||
|
||||
ethers/v5.0.12 (2020-09-07 19:54)
|
||||
---------------------------------
|
||||
|
||||
- Allow events to use compact bytes ABI coded data for Solidity 0.4 external events. ([#891](https://github.com/ethers-io/ethers.js/issues/891), [#992](https://github.com/ethers-io/ethers.js/issues/992); [4e394fc](https://github.com/ethers-io/ethers.js/commit/4e394fc68019445ae4b4e201e41f95d6793dbe92))
|
||||
|
||||
ethers/v5.0.11 (2020-09-05 23:51)
|
||||
---------------------------------
|
||||
|
||||
- Synced unorm in shims to most recent version. ([bdccf7b](https://github.com/ethers-io/ethers.js/commit/bdccf7b8d352ba400317266a0a37e6e290633e3c))
|
||||
- Fixed LedgerSigner sendTransaction. ([#936](https://github.com/ethers-io/ethers.js/issues/936); [cadb28d](https://github.com/ethers-io/ethers.js/commit/cadb28d6b364e68e43a06f7a9b8a31797afbd920))
|
||||
- Added BrainWallet to experimental exports. ([72385c2](https://github.com/ethers-io/ethers.js/commit/72385c228783a3158511b3cddc5cb4f9ce1dddae))
|
||||
- More readable server errors. ([201e5ce](https://github.com/ethers-io/ethers.js/commit/201e5ced9c38da2de1dd7518ffbf24284d477e80))
|
||||
|
||||
ethers/v5.0.10 (2020-09-05 01:21)
|
||||
---------------------------------
|
||||
|
||||
- Added retry logic to provider tests. ([0558bba](https://github.com/ethers-io/ethers.js/commit/0558bba8eb1b783ef50bb37bcf4c9bae1f86f1e1), [35b64b9](https://github.com/ethers-io/ethers.js/commit/35b64b9a65e2c09ecb63b0eca712b45a3092c204), [681f2a5](https://github.com/ethers-io/ethers.js/commit/681f2a50b26d7954795dba5aec55bede4740e494))
|
||||
- Fixed link in docs. ([#1028](https://github.com/ethers-io/ethers.js/issues/1028); [2359a98](https://github.com/ethers-io/ethers.js/commit/2359a98641d99b26cf88ec892e3601a8a2c81c9c))
|
||||
- Added memory-like support and new opcodes to asm. ([6fd3bb6](https://github.com/ethers-io/ethers.js/commit/6fd3bb62d10eab1563dc4ddbd88732b4f484ec7a))
|
||||
- Added basic ENS resolver functions for contenthash, text and multi-coin addresses. ([#1003](https://github.com/ethers-io/ethers.js/issues/1003); [83db8a6](https://github.com/ethers-io/ethers.js/commit/83db8a6bd1364458dcfeea544de707df41890b4e))
|
||||
- Added support for changing Reporter logging function. ([d01d0c8](https://github.com/ethers-io/ethers.js/commit/d01d0c8448df40de52253f9e92889ab7e75c6a97))
|
||||
- Initial React Native test harness. ([#993](https://github.com/ethers-io/ethers.js/issues/993); [57eb5b7](https://github.com/ethers-io/ethers.js/commit/57eb5b777e2c67f1f8d74e41d3413e9f0564528d), [d3b473e](https://github.com/ethers-io/ethers.js/commit/d3b473e7c738fdfc65b6f1c8f80bcdacf9827d8a))
|
||||
- Updating shims for constrained environments. ([#944](https://github.com/ethers-io/ethers.js/issues/944), [#993](https://github.com/ethers-io/ethers.js/issues/993); [8abdbbb](https://github.com/ethers-io/ethers.js/commit/8abdbbbf633f96fde2346c4ae70e538895fd7829), [240aac5](https://github.com/ethers-io/ethers.js/commit/240aac568303deff14cbb2366b94c8c89cacefc1))
|
||||
|
||||
ethers/v5.0.9 (2020-08-25 01:45)
|
||||
--------------------------------
|
||||
|
||||
- Fix Base58 padding for string representation of binary data ([#4527](https://github.com/ethers-io/ethers.js/issues/4527); [ccac24a](https://github.com/ethers-io/ethers.js/commit/ccac24a5b0a4d07a4b639c1c4d0a44703e32d418)).
|
||||
- Updated docs for all packages on npm pages. ([#1013](https://github.com/ethers-io/ethers.js/issues/1013); [cb8f4a3](https://github.com/ethers-io/ethers.js/commit/cb8f4a3a4e378a749c6bbbddf46d8d79d35722cc))
|
||||
- Added JSON support to BigNumber. ([#1010](https://github.com/ethers-io/ethers.js/issues/1010); [8facc1a](https://github.com/ethers-io/ethers.js/commit/8facc1a5305b1f699aa3afc5a0a692abe7927652))
|
||||
- Updated packages for security audit. ([5b5904e](https://github.com/ethers-io/ethers.js/commit/5b5904ea9977ecf8c079a57593b627553f0126a0))
|
||||
- Fix emitted error for ABI code array count mismatch. ([#1004](https://github.com/ethers-io/ethers.js/issues/1004); [b0c082d](https://github.com/ethers-io/ethers.js/commit/b0c082d728dc66b0f2a5ec315da44d6295716284))
|
||||
|
||||
ethers/v6.9.1 (2023-12-19 04:53)
|
||||
ethers/v5.0.8 (2020-08-04 20:55)
|
||||
--------------------------------
|
||||
|
||||
- Fix uncatchable issue when sending transactions over JSON-RPC and provide some retry-recovery for missing v ([#4513](https://github.com/ethers-io/ethers.js/issues/4513); [1802215](https://github.com/ethers-io/ethers.js/commit/180221574c5d2af9ad85404af4fab8752d3d5029)).
|
||||
- Abstract fetchJson for data. ([e2d6f28](https://github.com/ethers-io/ethers.js/commit/e2d6f281d5a2bd749bc72549a4e55f2c752a7bd8), [2c49a52](https://github.com/ethers-io/ethers.js/commit/2c49a52a41a30ae844376561de95f0c851d19f73), [e1bbb06](https://github.com/ethers-io/ethers.js/commit/e1bbb064a10d0b4bf5563e0a79396665d83935a1))
|
||||
|
||||
ethers/v6.9.0 (2023-11-27 06:15)
|
||||
ethers/v5.0.7 (2020-07-20 02:22)
|
||||
--------------------------------
|
||||
|
||||
- Use provider-specified suggested priority fee when available, otherwise fallback onto existing logic of 1 gwei ([#4463](https://github.com/ethers-io/ethers.js/issues/4463); [f8f11c7](https://github.com/ethers-io/ethers.js/commit/f8f11c754aa2c9b541db73d3bde66a8ffa5146f0)).
|
||||
- Add auto-detected static network support to providers and allow customizing socket provider options ([#4199](https://github.com/ethers-io/ethers.js/issues/4199), [#4418](https://github.com/ethers-io/ethers.js/issues/4418), [#4441](https://github.com/ethers-io/ethers.js/issues/4441); [4681b83](https://github.com/ethers-io/ethers.js/commit/4681b83d516ab2eb41ddb68b5021c97e14c6f2cf)).
|
||||
- Added Base network to AlchemyProvider ([#4384](https://github.com/ethers-io/ethers.js/issues/4384); [9e74d14](https://github.com/ethers-io/ethers.js/commit/9e74d14432e6efebdff21b9a7d2e6143af55e143)).
|
||||
- Fixed ParamType formatting causing bad tuple full and minimal ABI output ([#4329](https://github.com/ethers-io/ethers.js/issues/4329), [#4479](https://github.com/ethers-io/ethers.js/issues/4479); [2b67488](https://github.com/ethers-io/ethers.js/commit/2b6748815169abf2c99a647131875c13b8b6a787)).
|
||||
- Adjust for provider config weight when kicking off a request in FallbackProvider ([#4298](https://github.com/ethers-io/ethers.js/issues/4298); [da34e35](https://github.com/ethers-io/ethers.js/commit/da34e3569e95357d9469209d926cb645f0750bfa)).
|
||||
- More robust FallbackProvider broadcast ([#4186](https://github.com/ethers-io/ethers.js/issues/4186), [#4297](https://github.com/ethers-io/ethers.js/issues/4297), [#4442](https://github.com/ethers-io/ethers.js/issues/4442); [e2485b8](https://github.com/ethers-io/ethers.js/commit/e2485b8ef927d18c7a15d2d29b3b0feffec9991a)).
|
||||
- Added safe and finalized provider events ([#3921](https://github.com/ethers-io/ethers.js/issues/3921); [a92766e](https://github.com/ethers-io/ethers.js/commit/a92766e56ad04185625037d84fc28adaac7fae8c)).
|
||||
- Fix Logger setLogLevel with enum case mismatch. ([#947](https://github.com/ethers-io/ethers.js/issues/947); [5443363](https://github.com/ethers-io/ethers.js/commit/5443363de43e92de712e72d55165c3f4d7f652e9), [af10705](https://github.com/ethers-io/ethers.js/commit/af10705632bc1f8203ea50ea7ed3120b01c67122))
|
||||
- Removed UUID dependency from json-wallets. ([#966](https://github.com/ethers-io/ethers.js/issues/966); [e3f7426](https://github.com/ethers-io/ethers.js/commit/e3f7426af4d6d7e43db322700d768216b06433e0))
|
||||
- Removed unnecessary dependency from BigNumber. ([#951](https://github.com/ethers-io/ethers.js/issues/951); [78b350b](https://github.com/ethers-io/ethers.js/commit/78b350bbc5ea73561bf47038743b9e51049496f7))
|
||||
|
||||
ethers/v6.8.1 (2023-11-01 16:08)
|
||||
ethers/v5.0.6 (2020-07-16 05:54)
|
||||
--------------------------------
|
||||
|
||||
- Fixed typo in error description when converting values to arrays ([#4427](https://github.com/ethers-io/ethers.js/issues/4427), [#4446](https://github.com/ethers-io/ethers.js/issues/4446); [8fed2f8](https://github.com/ethers-io/ethers.js/commit/8fed2f84768ace4bf3e5742c931a74841da7c637)).
|
||||
- Fix invalid token nonpayable being included in formatted constructor ([#4412](https://github.com/ethers-io/ethers.js/issues/4412); [2e0bd90](https://github.com/ethers-io/ethers.js/commit/2e0bd90744b8e76fcf03f75a66cb0061d50f7bd9)).
|
||||
- Add ENS support for Sepolia ([#4422](https://github.com/ethers-io/ethers.js/issues/4422); [1da50ae](https://github.com/ethers-io/ethers.js/commit/1da50ae286da01e58a70bb8df8aa5cc5d260e33e)).
|
||||
- Removed unnecessary dependency from BigNumber. ([#951](https://github.com/ethers-io/ethers.js/issues/951); [78b350b](https://github.com/ethers-io/ethers.js/commit/78b350bbc5ea73561bf47038743b9e51049496f7))
|
||||
- Longer Etherscan throttle slot interval. ([9f20258](https://github.com/ethers-io/ethers.js/commit/9f20258d5d39cd901d2078275323071eb0f3505b))
|
||||
- Fixed ENS overrides for the default provider. ([#959](https://github.com/ethers-io/ethers.js/issues/959); [63dd3d4](https://github.com/ethers-io/ethers.js/commit/63dd3d4682b564445948988243fa9139c598587b))
|
||||
- Added Retry-After support and adjustable slot interval to fetchJson. ([7d43545](https://github.com/ethers-io/ethers.js/commit/7d435453039f009b339d835ddee47e35a843711b))
|
||||
- Added initial throttling support. ([#139](https://github.com/ethers-io/ethers.js/issues/139), [#904](https://github.com/ethers-io/ethers.js/issues/904), [#926](https://github.com/ethers-io/ethers.js/issues/926); [88c7eae](https://github.com/ethers-io/ethers.js/commit/88c7eaed061ae9a6798733a97e4e87011d36b8e7))
|
||||
- Use status code 1000 on WebSocket hangup for compatibility. ([588f64c](https://github.com/ethers-io/ethers.js/commit/588f64c760ee49bfb5109bfbaafb4beafe41c52a))
|
||||
- Updated WebSocketProvider to use web-style event listener API. ([57fd6f0](https://github.com/ethers-io/ethers.js/commit/57fd6f06047a1a2a3a46fe8b23ff585293a40062))
|
||||
- Normalize formatUnits to simplified decimals. ([79b1da1](https://github.com/ethers-io/ethers.js/commit/79b1da130be50df80c7e5aeb221edc5669fc211e))
|
||||
- Prevent zero-padding on Solidity type lengths. ([e128bfc](https://github.com/ethers-io/ethers.js/commit/e128bfcd10e006c920532151598700ca33a2127e))
|
||||
- Set sensible defaults for INFURA and AlchemyAPI getWebSocketProvider methods. ([e3d3e60](https://github.com/ethers-io/ethers.js/commit/e3d3e604f299edbafe7d0721c0a3eff5f67c83f4))
|
||||
- Added logger assert methods. ([619a888](https://github.com/ethers-io/ethers.js/commit/619a8888ebe08de9956f60c16703fb3543aeacc4))
|
||||
- Added initial code coverage testing. ([0c1d55b](https://github.com/ethers-io/ethers.js/commit/0c1d55b6dc9c725c86e849d13b911c8bace9821d))
|
||||
- Added destroy to WebSocketProvider. ([d0a79c6](https://github.com/ethers-io/ethers.js/commit/d0a79c6a1362e12f6f102e4af99adfef930092db))
|
||||
- Updated packages (security updates). ([c660176](https://github.com/ethers-io/ethers.js/commit/c6601769ada64832b1ce392680a30cb145c3cab9))
|
||||
|
||||
ethers/v6.8.0 (2023-10-10 22:42)
|
||||
ethers/v5.0.5 (2020-07-07 23:18)
|
||||
--------------------------------
|
||||
|
||||
- Replicated former ENS normalize behaviour for empty strings and update namehash testcases ([125ff11](https://github.com/ethers-io/ethers.js/commit/125ff1189b9cefb8abfd7da9c104c75e382a50cc)).
|
||||
- Initial shortMessage support for errors ([#4241](https://github.com/ethers-io/ethers.js/issues/4241); [d6a8c14](https://github.com/ethers-io/ethers.js/commit/d6a8c14d907cf8b90347444c0186b83a5db2e293)).
|
||||
- Fixed resolving ENS addresses used as from parameters ([#3961](https://github.com/ethers-io/ethers.js/issues/3961); [2616f4c](https://github.com/ethers-io/ethers.js/commit/2616f4c30c82bd45449b73fa37ef269d60a07d80)).
|
||||
- Merge: 9a4b7534 0c9c23b0 Merge branch 'v5.8-progress' ([cd5f0fe](https://github.com/ethers-io/ethers.js/commit/cd5f0fe03f2137fbc47e295f8db38a5151111e72)).
|
||||
- Allow more loose input format for RLP encoder ([#4402](https://github.com/ethers-io/ethers.js/issues/4402); [9a4b753](https://github.com/ethers-io/ethers.js/commit/9a4b7534458fc79a0654b0eb57fc956bffa02a2f)).
|
||||
- Update to latest noble crypto libraries ([#3975](https://github.com/ethers-io/ethers.js/issues/3975); [b27faa0](https://github.com/ethers-io/ethers.js/commit/b27faa02ac8f90e2e54b188e8139c59d98c469e3)).
|
||||
- More robust configuration options for FetchRequest getUrl functions ([#4353](https://github.com/ethers-io/ethers.js/issues/4353); [9541f2f](https://github.com/ethers-io/ethers.js/commit/9541f2f70cd7f5c6f3caf93f5a3d5e34eae5281a)).
|
||||
- Ignore blockTag when calling Etherscan if it is the default block tag ([dcea9b3](https://github.com/ethers-io/ethers.js/commit/dcea9b353619d85878ad2ba340ae17e5c285d558)).
|
||||
- Fixed splitSignature when recoveryParam is encoded directly. ([#893](https://github.com/ethers-io/ethers.js/issues/893), [#933](https://github.com/ethers-io/ethers.js/issues/933); [bf65ddb](https://github.com/ethers-io/ethers.js/commit/bf65ddbff0036f6eb8e99c145f30edff157687f5))
|
||||
- Fixed BigNumber string validation. ([#935](https://github.com/ethers-io/ethers.js/issues/935); [7e56f3d](https://github.com/ethers-io/ethers.js/commit/7e56f3d392e52815c5c859772b99660e0fc38ef5))
|
||||
|
||||
ethers/v6.7.1 (2023-08-15 03:08)
|
||||
ethers/v5.0.4 (2020-07-04 23:46)
|
||||
--------------------------------
|
||||
|
||||
- Prevent destroyed providers from emitting network detection errors ([7d41730](https://github.com/ethers-io/ethers.js/commit/7d4173049edc3b4ff2de1971c3ecca3b08588651)).
|
||||
- Fix VSCode reported lint issues ([#4153](https://github.com/ethers-io/ethers.js/issues/4153), [#4156](https://github.com/ethers-io/ethers.js/issues/4156), [#4158](https://github.com/ethers-io/ethers.js/issues/4158), [#4159](https://github.com/ethers-io/ethers.js/issues/4159); [4eb84da](https://github.com/ethers-io/ethers.js/commit/4eb84da865a82a27c5113c38102b6b710096958e), [203dfc3](https://github.com/ethers-io/ethers.js/commit/203dfc33b9c8e72c9cdfe0a349ac763ef17a4484)).
|
||||
- Add gasPrice to Polygon feeData for type 0 and type 1 legacy transactions ([#4315](https://github.com/ethers-io/ethers.js/issues/4315); [0df3ab9](https://github.com/ethers-io/ethers.js/commit/0df3ab93137039de1e1986bbfe9a5b32ceffa8a4)).
|
||||
- Prevent negative exponents in BigNumber. ([#925](https://github.com/ethers-io/ethers.js/issues/925); [84e253f](https://github.com/ethers-io/ethers.js/commit/84e253f3f9674b52fa2a17b097644e91e6474021))
|
||||
- Fixed StaticJsonRpcProvider when auto-detecting network. ([#901](https://github.com/ethers-io/ethers.js/issues/901); [0fd9aa5](https://github.com/ethers-io/ethers.js/commit/0fd9aa5cb6f4a3f9c1bea9b4eeee389700db01fa))
|
||||
- Added WebSocket static method to Alchemy provider and updated Alchemy URLs. ([4838874](https://github.com/ethers-io/ethers.js/commit/48388741272df8569315637f21df7c6519f79e2e))
|
||||
|
||||
ethers/v6.7.0 (2023-08-02 23:52)
|
||||
ethers/v5.0.3 (2020-06-29 00:50)
|
||||
--------------------------------
|
||||
|
||||
- Fixed receipt wait not throwing on reverted transactions ([25fef4f](https://github.com/ethers-io/ethers.js/commit/25fef4f8d756f5bbf5a2a05e38233248a8eb43ac)).
|
||||
- Added custom priority fee to Optimism chain (via telegram) ([ff80b04](https://github.com/ethers-io/ethers.js/commit/ff80b04f31da21496e72d3687cecd1c01efaecc5)).
|
||||
- Add context to Logs that fail decoding due to ABI issues to help debugging ([f3c46f2](https://github.com/ethers-io/ethers.js/commit/f3c46f22994d194ff78b3b176407b2ecb7af1c77)).
|
||||
- Added new exports for FallbackProviderOptions and FetchUrlFeeDataNetworkPlugin ([#2828](https://github.com/ethers-io/ethers.js/issues/2828), [#4160](https://github.com/ethers-io/ethers.js/issues/4160); [b1dbbb0](https://github.com/ethers-io/ethers.js/commit/b1dbbb0de3f10a3d9e12d6a84ad5c52bea25c7f6)).
|
||||
- Allow overriding pollingInterval in JsonRpcProvider constructor (via discord) ([f42f258](https://github.com/ethers-io/ethers.js/commit/f42f258beb305a06e563ad16522f095a72da32eb)).
|
||||
- Fixed FallbackProvider priority sorting ([#4150](https://github.com/ethers-io/ethers.js/issues/4150); [78538eb](https://github.com/ethers-io/ethers.js/commit/78538eb100addd135d29e60c9fa4fed3946278fa)).
|
||||
- Added linea network to InfuraProvider and Network ([#4184](https://github.com/ethers-io/ethers.js/issues/4184), [#4190](https://github.com/ethers-io/ethers.js/issues/4190); [d3e5e2c](https://github.com/ethers-io/ethers.js/commit/d3e5e2c45b28c377f306091acfc024e30c49ef20)).
|
||||
- Added whitelist support to getDefaultProvider ([82bb936](https://github.com/ethers-io/ethers.js/commit/82bb936542e29c6441ac8dc2d3ebbdd4edb708ee)).
|
||||
- Add Polygon RPC endpoints to the default provider ([#3689](https://github.com/ethers-io/ethers.js/issues/3689); [23704a9](https://github.com/ethers-io/ethers.js/commit/23704a9c44d5857817e138fb19d44ce2103ca005)).
|
||||
- Added customizable quorum to FallbackProvider ([#4160](https://github.com/ethers-io/ethers.js/issues/4160); [8f0a509](https://github.com/ethers-io/ethers.js/commit/8f0a50921a12a866addcf5b0fabc576bfc287689)).
|
||||
- Added basic Gas Station support via a NetworkPlugin ([#2828](https://github.com/ethers-io/ethers.js/issues/2828); [229145d](https://github.com/ethers-io/ethers.js/commit/229145ddf566a962517588eaeed155734c7d4598)).
|
||||
- Add BNB URLs to EtherscanProvider networks ([ec39abe](https://github.com/ethers-io/ethers.js/commit/ec39abe067259fad4ea8607a6c5aece61890eb41)).
|
||||
- Added tests for JSON format ([#4248](https://github.com/ethers-io/ethers.js/issues/4248); [ba36079](https://github.com/ethers-io/ethers.js/commit/ba36079a285706694532ce726568c4c447acad47)).
|
||||
- Use empty string for unnamed parameters in JSON output instead of undefined ([#4248](https://github.com/ethers-io/ethers.js/issues/4248); [8c2652c](https://github.com/ethers-io/ethers.js/commit/8c2652c8cb4d054207d89688d30930869d9d3f8b)).
|
||||
- Return undefined for Contract properties that do not exist instead of throwing an error ([#4266](https://github.com/ethers-io/ethers.js/issues/4266); [5bf7b34](https://github.com/ethers-io/ethers.js/commit/5bf7b3494ed62952fc387b4368a0bdc86dfe163e)).
|
||||
- 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/v6.6.7 (2023-07-28 14:50)
|
||||
ethers/v5.0.2 (2020-06-13 21:36)
|
||||
--------------------------------
|
||||
|
||||
- Prevent malformed logs from preventing other logs being decoded ([#4275](https://github.com/ethers-io/ethers.js/issues/4275); [0dca645](https://github.com/ethers-io/ethers.js/commit/0dca645632d73488bf6ad460e0d779361a537bbe)).
|
||||
- Allow visibility on human-readable constructors ([#4278](https://github.com/ethers-io/ethers.js/issues/4278); [3a52201](https://github.com/ethers-io/ethers.js/commit/3a52201fe2ba68a00105cca2c0901da5ffa18d6b)).
|
||||
- Allow provider.ready to stall until the network is available. ([#882](https://github.com/ethers-io/ethers.js/issues/882); [bbb4f40](https://github.com/ethers-io/ethers.js/commit/bbb4f407b34782c36ff93fa528e3b9f793987d4a))
|
||||
- Reduce dependencies to squash security issues. ([738d349](https://github.com/ethers-io/ethers.js/commit/738d34969d7c2184242b92f78228ba6a8aed1f3a))
|
||||
- Updated admin scripts for publishing prod releases. ([e0e0dbe](https://github.com/ethers-io/ethers.js/commit/e0e0dbef1830572c465670b826a7aa2b403ad2e8))
|
||||
|
||||
ethers/v6.6.6 (2023-07-28 01:14)
|
||||
ethers/v5.0.1 (2020-06-12 23:09)
|
||||
--------------------------------
|
||||
|
||||
- Better error message when passing invalid overrides object into a contract deployment ([#4182](https://github.com/ethers-io/ethers.js/issues/4182); [aa2ea3d](https://github.com/ethers-io/ethers.js/commit/aa2ea3d5296956fd0d40b83888e1ca053bb250ee)).
|
||||
- Fixed embedded package version strings. ([5a69e9c](https://github.com/ethers-io/ethers.js/commit/5a69e9caa882aa5f1b44c4453d67cde43254eafe))
|
||||
|
||||
ethers/v6.6.5 (2023-07-24 00:04)
|
||||
ethers/v5.0.0 (2020-06-12 19:58)
|
||||
--------------------------------
|
||||
|
||||
- Reflect symbols in the Contract Proxy to target ([#4084](https://github.com/ethers-io/ethers.js/issues/4048); [ac2f5e5](https://github.com/ethers-io/ethers.js/commit/ac2f5e563b8ec0e91a931470eb6ea58b0c01fb3d)).
|
||||
- Allow arrays of address for indexed filter topics ([#4259](https://github.com/ethers-io/ethers.js/issues/4259); [93af87c](https://github.com/ethers-io/ethers.js/commit/93af87c447eeb77090e29bd940612603b3f74026)).
|
||||
- Fixed filter encoding for bytesX ([#4244](https://github.com/ethers-io/ethers.js/issues/4244); [fa3a883](https://github.com/ethers-io/ethers.js/commit/fa3a883ff7c88611ce766f58bdd4b8ac90814470)).
|
||||
- Fix JSON formatting for tuple arrays ([#4237](https://github.com/ethers-io/ethers.js/issues/4237); [a8bc49b](https://github.com/ethers-io/ethers.js/commit/a8bc49bdcf07a51b35f38cf209db27e116cc1a59)).
|
||||
- Better error messages when parsing fragment strings ([#4246](https://github.com/ethers-io/ethers.js/issues/4246); [e36b6c3](https://github.com/ethers-io/ethers.js/commit/e36b6c35b7bc777c9adbe0055b32b31a13185240)).
|
||||
- Include the missing fragment key and args when no matching Contract method or event is present ([#3809](https://github.com/ethers-io/ethers.js/issues/3809); [450a176](https://github.com/ethers-io/ethers.js/commit/450a176ee25f88a2ddb9ff23b153ef70bf1dc546)).
|
||||
- Prevent a single malformed event from preventing other Contract logs; reported on Discord ([b1375f4](https://github.com/ethers-io/ethers.js/commit/b1375f4e4463b856855ebc684b45945455ac082e)).
|
||||
|
||||
ethers/v6.6.4 (2023-07-16 00:35)
|
||||
--------------------------------
|
||||
|
||||
- More robust support for Signatures with less standard parameter values ([#3835](https://github.com/ethers-io/ethers.js/issues/3835), [#4228](https://github.com/ethers-io/ethers.js/issues/4228); [a7e4048](https://github.com/ethers-io/ethers.js/commit/a7e4048fe3b75a743cec8c8ef2a5fad4bdc8b14c)).
|
||||
- Fixed CCIP-read in the EnsResolver ([#4221](https://github.com/ethers-io/ethers.js/issues/4221); [57f1e1c](https://github.com/ethers-io/ethers.js/commit/57f1e1c47148921148e35c10c83539531942923e)).
|
||||
- Skip checking confirmation count if confirms is 0 ([#4229](https://github.com/ethers-io/ethers.js/issues/4229), [#4242](https://github.com/ethers-io/ethers.js/issues/4242); [492919d](https://github.com/ethers-io/ethers.js/commit/492919d14f646c630f29e1596e5564df1e51f309)).
|
||||
- Fixed waiting for confirmations in deployment transactions ([#4212](https://github.com/ethers-io/ethers.js/issues/4212), [#4230](https://github.com/ethers-io/ethers.js/issues/4230); [43c253a](https://github.com/ethers-io/ethers.js/commit/43c253a402f52a08353c424f6c4e236836cfaf36)).
|
||||
|
||||
ethers/v6.6.3 (2023-07-11 20:55)
|
||||
--------------------------------
|
||||
|
||||
- Throw more desscriptive error for unconfigured ENS name contract targets ([#4213](https://github.com/ethers-io/ethers.js/issues/4213); [80f62ef](https://github.com/ethers-io/ethers.js/commit/80f62efc41c3a29e690af40a1976928b7f886a0e)).
|
||||
- Fixed contract once not running stop callback ([7d061b7](https://github.com/ethers-io/ethers.js/commit/7d061b786f72cbfc461bf80d139d10aeff533a6e)).
|
||||
|
||||
ethers/v6.6.2 (2023-06-27 23:30)
|
||||
--------------------------------
|
||||
|
||||
- Wider error detection for call exceptions on certain backends ([#4154](https://github.com/ethers-io/ethers.js/issues/4154), [#4155](https://github.com/ethers-io/ethers.js/issues/4155); [9197f9f](https://github.com/ethers-io/ethers.js/commit/9197f9f938b5f3b5f97c043f2dab06854656c932)).
|
||||
- Added wider error deetection for JSON-RPC unsupported operation ([#4162](https://github.com/ethers-io/ethers.js/issues/4162); [1dc8986](https://github.com/ethers-io/ethers.js/commit/1dc8986a33be9dce536b24189326cbfaabf1342e)).
|
||||
- Fixed formatUnits and parseUnits for values over 128 bits ([#4037](https://github.com/ethers-io/ethers.js/issues/4037), [#4133](https://github.com/ethers-io/ethers.js/issues/4133); [3d141b4](https://github.com/ethers-io/ethers.js/commit/3d141b44b528f52b3c9205125b64ce342f91643c)).
|
||||
|
||||
ethers/v6.6.1 (2023-06-23 00:35)
|
||||
--------------------------------
|
||||
|
||||
- Fixed CCIP read in contract calls ([#4043](https://github.com/ethers-io/ethers.js/issues/4043); [d51e3fb](https://github.com/ethers-io/ethers.js/commit/d51e3fbff43c31d88353ac71151626312d22c0b9), [857aa8c](https://github.com/ethers-io/ethers.js/commit/857aa8ccc30f25eda8e83dcac3e0ad2c1a5ce2b3)).
|
||||
|
||||
ethers/v6.6.0 (2023-06-13 21:42)
|
||||
--------------------------------
|
||||
|
||||
- Add exports for AbstractProviderOptions and for MulticoinProviderPlugin ([203a759](https://github.com/ethers-io/ethers.js/commit/203a759efc65bf6901d3e574a601525ea3936238)).
|
||||
- Add option to adjust perform cache timeout in AbstractProvider ([de0f518](https://github.com/ethers-io/ethers.js/commit/de0f5189f695c181a5fa09100af96a691a338e2b)).
|
||||
- Add full support for MultiCoin plugins and automatic detection for EVM-compatible coin types ([#3888](https://github.com/ethers-io/ethers.js/issues/3888), [#4081](https://github.com/ethers-io/ethers.js/issues/4081); [84375be](https://github.com/ethers-io/ethers.js/commit/84375be92d32a2939cf4a2f713e4c554b5b54a32)).
|
||||
- Allow Interface instances where InterfaceAbi are allowed ([#4142](https://github.com/ethers-io/ethers.js/issues/4142); [2318005](https://github.com/ethers-io/ethers.js/commit/2318005dfd996c8a7c51603d0264ceabe9bb6141)).
|
||||
- Allow Numeric type for decimals in FixedNumber ([#4141](https://github.com/ethers-io/ethers.js/issues/4141); [9055ef6](https://github.com/ethers-io/ethers.js/commit/9055ef6c69291f1a44ea23a2e7b5aaf3140a5577)).
|
||||
|
||||
ethers/v6.5.1 (2023-06-07 20:19)
|
||||
--------------------------------
|
||||
|
||||
- Fix lost promise fulfillment when a batch has an error response ([#4126](https://github.com/ethers-io/ethers.js/issues/4126); [8dd21f0](https://github.com/ethers-io/ethers.js/commit/8dd21f03334ffd3cdb7ac532376d51fd4130c7ab)).
|
||||
|
||||
ethers/v6.5.0 (2023-06-06 22:41)
|
||||
--------------------------------
|
||||
|
||||
- Fix CJS browser bundling ([#4033](https://github.com/ethers-io/ethers.js/issues/4033); [38ee319](https://github.com/ethers-io/ethers.js/commit/38ee3195b0192d8180899fd61308e03fa3a0eb32)).
|
||||
- Fixed type guard for non-Typed instances ([#4087](https://github.com/ethers-io/ethers.js/issues/4087); [20c3d1b](https://github.com/ethers-io/ethers.js/commit/20c3d1b109743e33ab60a75d69bf7ede73b15ce2)).
|
||||
- Add confirmations to TransactionResponse ([#4094](https://github.com/ethers-io/ethers.js/issues/4094); [bb8685b](https://github.com/ethers-io/ethers.js/commit/bb8685b112ce1c689c740d4dbcb358c16fb9b22d)).
|
||||
- Fix stray promises when a node returns invalid results ([#4118](https://github.com/ethers-io/ethers.js/issues/4118); [3c1bad2](https://github.com/ethers-io/ethers.js/commit/3c1bad2fb7ad4a6ff90ff11f3e382fd18e41c800)).
|
||||
- Added support to detect and stop providers spinning on intitial network detection ([#4015](https://github.com/ethers-io/ethers.js/issues/4015); [f37a52d](https://github.com/ethers-io/ethers.js/commit/f37a52da28ac130b7f4de52901618320994ea87a)).
|
||||
|
||||
ethers/v6.4.2 (2023-06-05 22:41)
|
||||
--------------------------------
|
||||
|
||||
- Bump ens-normalize version ([#4071](https://github.com/ethers-io/ethers.js/issues/4071), [#4077](https://github.com/ethers-io/ethers.js/issues/4077), [#4080](https://github.com/ethers-io/ethers.js/issues/4080), [#4102](https://github.com/ethers-io/ethers.js/issues/4102); [c135784](https://github.com/ethers-io/ethers.js/commit/c1357847dcdec93d72f28d890f9271d0289ccefd)).
|
||||
- Fix for networks with polling with non-consistent block and filter events ([#4119](https://github.com/ethers-io/ethers.js/issues/4119); [9b0e992](https://github.com/ethers-io/ethers.js/commit/9b0e9920c09577296ec0e2abb3acc3f3299d96c7)).
|
||||
|
||||
ethers/v6.4.1 (2023-06-01 17:52)
|
||||
--------------------------------
|
||||
|
||||
- Fixed AbstractProvider lookupAddress bug ([#4086](https://github.com/ethers-io/ethers.js/issues/4086); [15ed2f5](https://github.com/ethers-io/ethers.js/commit/15ed2f5b32084527961332481c9442a313036a01)).
|
||||
- Fix FixedNumber comparison bug ([#4112](https://github.com/ethers-io/ethers.js/issues/4112); [d8e9586](https://github.com/ethers-io/ethers.js/commit/d8e9586044e888e424b5ead0f6e01f88140dba8a)).
|
||||
|
||||
ethers/v6.4.0 (2023-05-18 17:28)
|
||||
--------------------------------
|
||||
|
||||
- Coerce value into BigInt when checking for value ([83d7f43](https://github.com/ethers-io/ethers.js/commit/83d7f43b9ca4b9868a3952510e56b41ea8610baa)).
|
||||
- Better errors when junk passed as Contract target ([#3947](https://github.com/ethers-io/ethers.js/issues/3947), [#4053](https://github.com/ethers-io/ethers.js/issues/4053); [219b16d](https://github.com/ethers-io/ethers.js/commit/219b16dc284b0c6a532c8c49e824d8234f94222b)).
|
||||
- More robust message checking in socket providers ([#4051](https://github.com/ethers-io/ethers.js/issues/4051); [f58990b](https://github.com/ethers-io/ethers.js/commit/f58990b80cfd83579014339315e58663c0aa6ae3)).
|
||||
- More robust defaultProvider start-up when a backend fails on bootstrap ([#3979](https://github.com/ethers-io/ethers.js/issues/3979); [984f6fa](https://github.com/ethers-io/ethers.js/commit/984f6fa155fca08ebec2353c75ee0a0b974e8568)).
|
||||
- Fix Result.map when Array contains zero elements ([#4036](https://github.com/ethers-io/ethers.js/issues/4036), [#4048](https://github.com/ethers-io/ethers.js/issues/4048); [2e5935b](https://github.com/ethers-io/ethers.js/commit/2e5935b91cff462165a054b33c8b8413f51e3f39)).
|
||||
- Fixed error handling for contracts with receive and non-payable fallback ([6db7458](https://github.com/ethers-io/ethers.js/commit/6db7458cf0a09e8e8a2abb712239972ab81dc9df)).
|
||||
- Remove superfluous logging in defaultProvider ([f87f6ef](https://github.com/ethers-io/ethers.js/commit/f87f6ef9a01ca399664f9fe106b0a677dba0c8e8)).
|
||||
- Removed superfluous logging ([1bc8b55](https://github.com/ethers-io/ethers.js/commit/1bc8b55d502a95c4ae58352bdcfce9e5f9ea72d3)).
|
||||
- Fix receipt gas price when effectiveGasPrice is 0 on testnets ([#4014](https://github.com/ethers-io/ethers.js/issues/4014); [2b0fe61](https://github.com/ethers-io/ethers.js/commit/2b0fe611335432aee334d777a64d8c7827881618)).
|
||||
- Added error event to provider ([#3970](https://github.com/ethers-io/ethers.js/issues/3970), [#3982](https://github.com/ethers-io/ethers.js/issues/3982); [af0291c](https://github.com/ethers-io/ethers.js/commit/af0291c01639674658f5049343da88a84da763a1)).
|
||||
- Removed superfluous parameters for internal transaction functions ([e848978](https://github.com/ethers-io/ethers.js/commit/e8489787585c2e69a23f6cdec6901f22b096aebe)).
|
||||
- More aggresive tree-shaking ([076edad](https://github.com/ethers-io/ethers.js/commit/076edad81ef62474f48f2b4c8af0edc6e4fd64f2)).
|
||||
- More flexible static network checking ([#3834](https://github.com/ethers-io/ethers.js/issues/3834); [7c0465c](https://github.com/ethers-io/ethers.js/commit/7c0465c5fb834eba18d4e5535072685bdc1029f0)).
|
||||
- Support transitive dependants that use non-node16 moduleResolution ([#3920](https://github.com/ethers-io/ethers.js/issues/3920); [df685b1](https://github.com/ethers-io/ethers.js/commit/df685b1bd9ad346ee7863beb6c3ca3f4e94932a2)).
|
||||
- Populate any missing log.removed with false ([#3959](https://github.com/ethers-io/ethers.js/issues/3959); [4e478e6](https://github.com/ethers-io/ethers.js/commit/4e478e625d5648f2172631eef5fda5776ee776b0)).
|
||||
|
||||
ethers/v6.3.0 (2023-04-06 04:35)
|
||||
--------------------------------
|
||||
|
||||
- Added support for legacy ABI JSON fragments ([#3932](https://github.com/ethers-io/ethers.js/issues/3932); [8c5973e](https://github.com/ethers-io/ethers.js/commit/8c5973e3a9b8d4d4ed80bdf209d8a0b6cc6b8d6d)).
|
||||
- Add _in_ operator support for contract and contract.filters ([#3901](https://github.com/ethers-io/ethers.js/issues/3901); [c58ab3a](https://github.com/ethers-io/ethers.js/commit/c58ab3a97687e15a3ffe30b038089c5f4b570bb9)).
|
||||
- Fixed TypedData unsigned value range ([#3873](https://github.com/ethers-io/ethers.js/issues/3873); [a851b24](https://github.com/ethers-io/ethers.js/commit/a851b24d0af009ecf277766d2a5f81f9b3e7f9f8)).
|
||||
- Added missing export for getIndexedAccountPath ([#3875](https://github.com/ethers-io/ethers.js/issues/3875); [356ff2b](https://github.com/ethers-io/ethers.js/commit/356ff2becb4f4d3622b281d3825770af5caf71ca)).
|
||||
- Fixed TypedData payloads for JSON-restricted chainId field ([#3836](https://github.com/ethers-io/ethers.js/issues/3836); [50b74b8](https://github.com/ethers-io/ethers.js/commit/50b74b8806ef2064f2764b09f89c7ac75fda3a3c)).
|
||||
|
||||
ethers/v6.2.3 (2023-03-27 21:22)
|
||||
--------------------------------
|
||||
|
||||
- Fixed events when emitted in WebSocketProvider ([#3767](https://github.com/ethers-io/ethers.js/issues/3767), [#3922](https://github.com/ethers-io/ethers.js/issues/3922); [ffaafc0](https://github.com/ethers-io/ethers.js/commit/ffaafc0ce1cf40d1d76d8d814c9c445057bf6989)).
|
||||
|
||||
ethers/v6.2.2 (2023-03-24 00:49)
|
||||
--------------------------------
|
||||
|
||||
- Fixed FetchRequest when using credentials ([#3897](https://github.com/ethers-io/ethers.js/issues/3897); [88e8124](https://github.com/ethers-io/ethers.js/commit/88e8124c37d377628f9b8abdf140fc07ad06259f)).
|
||||
|
||||
ethers/v6.2.1 (2023-03-23 17:33)
|
||||
--------------------------------
|
||||
|
||||
- Stall block polling bootstrap when the network is down ([#3924](https://github.com/ethers-io/ethers.js/issues/3924); [603d474](https://github.com/ethers-io/ethers.js/commit/603d47496e2b667c15b72f315261d6e299381848)).
|
||||
|
||||
ethers/v6.2.0 (2023-03-20 15:53)
|
||||
--------------------------------
|
||||
|
||||
- Added extra details in the error info field for RPC errors ([30ffa78](https://github.com/ethers-io/ethers.js/commit/30ffa78d1441fa033677fa09237fc135a314f373)).
|
||||
- Remove Ankr as a deafult for now as the provided API key is failing ([6e01e54](https://github.com/ethers-io/ethers.js/commit/6e01e5448f4a3e2d30288d4c8447db295c3a2e7a)).
|
||||
- Fixed deferred filters after unsafe-eval changes ([#3749](https://github.com/ethers-io/ethers.js/issues/3749), [#3763](https://github.com/ethers-io/ethers.js/issues/3763); [2e3802a](https://github.com/ethers-io/ethers.js/commit/2e3802a83b8ad2f5a6269d79fbd1c83c9f2d1047)).
|
||||
- Remove use of Function sub-class to address unsafe-eval issues ([#3749](https://github.com/ethers-io/ethers.js/issues/3749), [#3763](https://github.com/ethers-io/ethers.js/issues/3763); [7d3af51](https://github.com/ethers-io/ethers.js/commit/7d3af512c75b4c24027ec2daef1e9f4c1064194a)).
|
||||
- Added verifyTypedData utility (reported on Farcaster) ([f06a445](https://github.com/ethers-io/ethers.js/commit/f06a445247f3b294f9fc805cc8fe0752accb8edc)).
|
||||
- Removed stray logging in IpcProvider ([#3908](https://github.com/ethers-io/ethers.js/issues/3908), [#3909](https://github.com/ethers-io/ethers.js/issues/3909); [e11d4c1](https://github.com/ethers-io/ethers.js/commit/e11d4c1c20cc5b6fd5803cf9636c4f5bc082dab7)).
|
||||
- Fixed legacy serialization for implicit chainId transactions ([#3898](https://github.com/ethers-io/ethers.js/issues/3898), [#3899](https://github.com/ethers-io/ethers.js/issues/3899); [fcf6c8f](https://github.com/ethers-io/ethers.js/commit/fcf6c8fcee95ec412aaafba8ec84d5049b077a4e)).
|
||||
- Fix Webpack issue (reported on discord) ([3ad4273](https://github.com/ethers-io/ethers.js/commit/3ad4273b8b714bff344ccbfb1eb71ed8a8b7cfa4)).
|
||||
- Fix some bundlers which cannot handle recursive pkg.exports ([#3848](https://github.com/ethers-io/ethers.js/issues/3848); [6315e78](https://github.com/ethers-io/ethers.js/commit/6315e78ea32147653b72ca06f6800f3e2df6ffbf)).
|
||||
- Fixed typo in signature.s error ([#3891](https://github.com/ethers-io/ethers.js/issues/3891); [47ef3eb](https://github.com/ethers-io/ethers.js/commit/47ef3ebde37bfa0c015c258c3d8a6800d751e147)).
|
||||
- Fixed stray unreachable code ([#3890](https://github.com/ethers-io/ethers.js/issues/3890); [c220fe2](https://github.com/ethers-io/ethers.js/commit/c220fe2ea747ccc80cd3c4020e0278e3daf3c4fc)).
|
||||
- Move all wrapping to proper _wrap functions ([#3818](https://github.com/ethers-io/ethers.js/issues/3818); [02a0aad](https://github.com/ethers-io/ethers.js/commit/02a0aad61212c35e8d2723a8ae589989b97dae3e)).
|
||||
|
||||
ethers/v6.1.0 (2023-03-07 02:10)
|
||||
--------------------------------
|
||||
|
||||
- Fixed ethers imported in web workers ([#3856](https://github.com/ethers-io/ethers.js/issues/3856); [5f2678f](https://github.com/ethers-io/ethers.js/commit/5f2678fb059d643638b9cc1dc59cbfc61ce7a7b8)).
|
||||
- Added Sepolia support ([#3863](https://github.com/ethers-io/ethers.js/issues/3863); [abeaa74](https://github.com/ethers-io/ethers.js/commit/abeaa74da04fbe25e837a2ffa7d1e9c1257a5da5)).
|
||||
- Added missing exports ([#3734](https://github.com/ethers-io/ethers.js/issues/3734); [06aa303](https://github.com/ethers-io/ethers.js/commit/06aa30363f88144db672376d39012d7fe3f86c33)).
|
||||
- Allow null values for TypedData domain ([#3623](https://github.com/ethers-io/ethers.js/issues/3623); [a32af3a](https://github.com/ethers-io/ethers.js/commit/a32af3adc104c4b07a45097a4a3725a4ce9e0be6)).
|
||||
- Added listAccounts to JsonRpcProvider ([#3778](https://github.com/ethers-io/ethers.js/issues/3778); [287d94f](https://github.com/ethers-io/ethers.js/commit/287d94fc454d03f1b3086ea98745131cdf40129a)).
|
||||
- Allow BigInt for blockTag ([#3780](https://github.com/ethers-io/ethers.js/issues/3780); [fe1f04c](https://github.com/ethers-io/ethers.js/commit/fe1f04c6e5fb4254a100f492d7dcbdc3cf19a446)).
|
||||
- Fixed typo in error messages ([#3822](https://github.com/ethers-io/ethers.js/issues/3822), [#3824](https://github.com/ethers-io/ethers.js/issues/3824); [f1a810d](https://github.com/ethers-io/ethers.js/commit/f1a810dcb56df54b1e1567f2a59c73500619472f)).
|
||||
- Re-adding definition files to require exports ([#3703](https://github.com/ethers-io/ethers.js/issues/3703); [76fab92](https://github.com/ethers-io/ethers.js/commit/76fab923da33e71e6bb751bb0b5e3ba3faa27ab2)).
|
||||
|
||||
ethers/v6.0.8 (2023-02-23 06:30)
|
||||
--------------------------------
|
||||
|
||||
- Fix matic-mumbai network and include aliases to legacy names ([#3811](https://github.com/ethers-io/ethers.js/issues/3811); [20bbd12](https://github.com/ethers-io/ethers.js/commit/20bbd1281911d31b360f6f5032251c9257943541)).
|
||||
- Fixed getSigner bug ([#3821](https://github.com/ethers-io/ethers.js/issues/3821); [388edf6](https://github.com/ethers-io/ethers.js/commit/388edf6abc168f89f1ca609e9e5b025dc9205add)).
|
||||
|
||||
ethers/v6.0.7 (2023-02-23 01:41)
|
||||
--------------------------------
|
||||
|
||||
- Fixed getContentHash ([#3819](https://github.com/ethers-io/ethers.js/issues/3819); [b993f7c](https://github.com/ethers-io/ethers.js/commit/b993f7c3b6c0e135c460c8b8dc5943215628231a)).
|
||||
|
||||
ethers/v6.0.6 (2023-02-22 21:53)
|
||||
--------------------------------
|
||||
|
||||
- Added chain parameters for Arbitrum and Optimism ([#3811](https://github.com/ethers-io/ethers.js/issues/3811); [77a7323](https://github.com/ethers-io/ethers.js/commit/77a7323119923e596f4def4f1bc90beae5447320)).
|
||||
- Fix NonceManager race condition ([#3812](https://github.com/ethers-io/ethers.js/issues/3812), [#3813](https://github.com/ethers-io/ethers.js/issues/3813); [5a3c10a](https://github.com/ethers-io/ethers.js/commit/5a3c10a29c047609a50828adb620d88aa8cf0014)).
|
||||
- Add UMD output to dist builds ([#3814](https://github.com/ethers-io/ethers.js/issues/3814); [f9eed4c](https://github.com/ethers-io/ethers.js/commit/f9eed4cdb190b06dd4ddaa2382c1de42e8e98de6)).
|
||||
|
||||
ethers/v6.0.5 (2023-02-18 22:36)
|
||||
--------------------------------
|
||||
|
||||
- Fixed Result to behave correctly like an array using slice and toArray ([#3787](https://github.com/ethers-io/ethers.js/issues/3787); [399356b](https://github.com/ethers-io/ethers.js/commit/399356b91227db04e496628af60c4b8e38207760)).
|
||||
- Replaced substring from 0 index with startsWith ([#3691](https://github.com/ethers-io/ethers.js/issues/3691); [4512e97](https://github.com/ethers-io/ethers.js/commit/4512e97f9b55607ce388aa6eb63a37fc196a5d9d)).
|
||||
- Fixed inverted assert in duplicate name detection for ABI encoding ([#3792](https://github.com/ethers-io/ethers.js/issues/3792); [762c2f3](https://github.com/ethers-io/ethers.js/commit/762c2f34eac848c5464389f11d1697dcd8ebcbb5)).
|
||||
- Fixed missing property during transaction copy ([#3793](https://github.com/ethers-io/ethers.js/issues/3793); [48bbef7](https://github.com/ethers-io/ethers.js/commit/48bbef7ade69bcfe86542f752f15049cc62f4141)).
|
||||
- Add support for Wallet private keys without 0x prefix ([#3768](https://github.com/ethers-io/ethers.js/issues/3768); [4665fb4](https://github.com/ethers-io/ethers.js/commit/4665fb4c6886c8b344dee316ba9f4fde57ce7557)).
|
||||
- Fixed quicknode property for defaultProvider ([#3741](https://github.com/ethers-io/ethers.js/issues/3741); [a8afb72](https://github.com/ethers-io/ethers.js/commit/a8afb72fbbceb6a5024c1edb85badb72099787ea)).
|
||||
- Fixed exports field order ([#3703](https://github.com/ethers-io/ethers.js/issues/3703), [#3755](https://github.com/ethers-io/ethers.js/issues/3755); [085a905](https://github.com/ethers-io/ethers.js/commit/085a9054f349afb816ca1a123737293ec9bd2532)).
|
||||
|
||||
ethers/v6.0.4 (2023-02-16 08:55)
|
||||
--------------------------------
|
||||
|
||||
- Fixed custom error decoding ([#3785](https://github.com/ethers-io/ethers.js/issues/3785); [4d9b29d](https://github.com/ethers-io/ethers.js/commit/4d9b29de751e2387c143e474bb96d271da892ea6)).
|
||||
- Removed stray debug logging ([e1e0929](https://github.com/ethers-io/ethers.js/commit/e1e09293483a9d07fd8e8f96552aa958b5ec45ed)).
|
||||
- Fixed lookupAddress when bad resolver is present ([#3782](https://github.com/ethers-io/ethers.js/issues/3782); [92def9c](https://github.com/ethers-io/ethers.js/commit/92def9c1489bb35ad13fe58a1cd107ee3a05a112)).
|
||||
- Fixed FallbackProvider median calculation ([#3746](https://github.com/ethers-io/ethers.js/issues/3746); [83957dc](https://github.com/ethers-io/ethers.js/commit/83957dc283043b9af8f6e89920faac3e09ca69fc)).
|
||||
- Move the xnf normalize variant to pkg.browser instead of import ([#3724](https://github.com/ethers-io/ethers.js/issues/3724); [179e6ca](https://github.com/ethers-io/ethers.js/commit/179e6ca520392177c7dea5e477b29930952ed637)).
|
||||
|
||||
ethers/v6.0.3 (2023-02-12 22:45)
|
||||
--------------------------------
|
||||
|
||||
- Allow null type in transaction receipt for legacy type 0 networks ([#3459](https://github.com/ethers-io/ethers.js/issues/3459); [6372a46](https://github.com/ethers-io/ethers.js/commit/6372a46b1b273db3e4c1189daebb4b888bd588bc)).
|
||||
- Fixed events when slicing immutable Result ([#3765](https://github.com/ethers-io/ethers.js/issues/3765); [2ba4a17](https://github.com/ethers-io/ethers.js/commit/2ba4a172555b7e17ac01fedfc944549defab61bc)).
|
||||
- More robust support on networks which throw when filters are not supported ([#3767](https://github.com/ethers-io/ethers.js/issues/3767); [37bf4fb](https://github.com/ethers-io/ethers.js/commit/37bf4fb55563d7ff66edee15c7515c8a0d6a2266)).
|
||||
- Fixed ignored polling override for JsonRpcApiProvider ([400d576](https://github.com/ethers-io/ethers.js/commit/400d57621b3e9a33679a528b5072449699f0a068)).
|
||||
|
||||
ethers/v6.0.2 (2023-02-04 08:50)
|
||||
--------------------------------
|
||||
|
||||
- Fixed crossed assert in Fetch ([#3733](https://github.com/ethers-io/ethers.js/issues/3733); [6c338c1](https://github.com/ethers-io/ethers.js/commit/6c338c1c5b4013db9754c9d1a33dcbf54330e5c7)).
|
||||
|
||||
ethers/v6.0.1 (2023-02-04 04:06)
|
||||
--------------------------------
|
||||
|
||||
- Fix Subscriber model when removed within emit callback ([d0ed918](https://github.com/ethers-io/ethers.js/commit/d0ed91840c9f51c7ce9061ebb1d36727dbdd51a4)).
|
||||
- Fixed human-readable parser when identifier begins with valid type prefix ([#3728](https://github.com/ethers-io/ethers.js/issues/3728); [522fd16](https://github.com/ethers-io/ethers.js/commit/522fd16f68aabc53e4dc8745d4128e0d61260ed5)).
|
||||
- Update to latest secp256k1 library ([#3719](https://github.com/ethers-io/ethers.js/issues/3719); [803e8f9](https://github.com/ethers-io/ethers.js/commit/803e8f9821950b83efa876d64b1cfb35f6bccc38)).
|
||||
|
||||
ethers/v6.0.0 (2023-02-02 22:48)
|
||||
--------------------------------
|
||||
|
||||
- Initial release ([90afd9b](https://github.com/ethers-io/ethers.js/commit/90afd9bd81ed1408421a0247fa0845a74c9eb319)).
|
||||
- Preserve config canary string. ([7157816](https://github.com/ethers-io/ethers.js/commit/7157816fa53f660d750811b293e3b1d5a2f70bd4))
|
||||
- Updated docs. ([9e4c7e6](https://github.com/ethers-io/ethers.js/commit/9e4c7e609d9eeb5f2a11d6a90bfa9d32ee696431))
|
||||
|
||||
523
CHANGELOG.v5-beta.md
Normal file
523
CHANGELOG.v5-beta.md
Normal file
@ -0,0 +1,523 @@
|
||||
Changelog
|
||||
=========
|
||||
|
||||
This change log is managed by `scripts/cmds/update-versions` but may be manually updated.
|
||||
|
||||
ethers/v5.0.0-beta.192 (2020-06-12 04:51)
|
||||
-----------------------------------------
|
||||
|
||||
- Support nonpayable Solidity modifier in ABI. ([adc8d3d](https://github.com/ethers-io/ethers.js/commit/adc8d3d9aec2f5ee8e207f8bc77d99052e473d16))
|
||||
- More debug information in timeout and fetch errors. ([#678](https://github.com/ethers-io/ethers.js/issues/678); [693094e](https://github.com/ethers-io/ethers.js/commit/693094e97ce4f0dc0cd49b9cf6b1557bd7dc517d))
|
||||
- Use URL parse instead of constructor for react compatibility. ([#874](https://github.com/ethers-io/ethers.js/issues/874); [5e7d28b](https://github.com/ethers-io/ethers.js/commit/5e7d28b19b18aa1bbb4b851f74f6d7865725be02))
|
||||
|
||||
ethers/v5.0.0-beta.191 (2020-06-03 03:41)
|
||||
-----------------------------------------
|
||||
|
||||
- Allow undefined properties in transaction object and fix stray this. ([#860](https://github.com/ethers-io/ethers.js/issues/860); [98bb589](https://github.com/ethers-io/ethers.js/commit/98bb58964bec7dff0ccf481d474354ec1ca6f376), [d2406c4](https://github.com/ethers-io/ethers.js/commit/d2406c42a18c123205918eb46bf24de0ff97ee23))
|
||||
- Allow JsonRpcSigner to override from if it matches Signer. ([#862](https://github.com/ethers-io/ethers.js/issues/862); [1a89c59](https://github.com/ethers-io/ethers.js/commit/1a89c591c26a7fcc2031d0df90137d8a096c5c01))
|
||||
- Added initial support for spontaneous network changes. ([#495](https://github.com/ethers-io/ethers.js/issues/495), [#861](https://github.com/ethers-io/ethers.js/issues/861); [2bc7bb6](https://github.com/ethers-io/ethers.js/commit/2bc7bb6e61219a40cfe2acd95c115c2195c21223), [d2ca4fb](https://github.com/ethers-io/ethers.js/commit/d2ca4fb443b2653063ca5aa349b52ecd0ff79e2f))
|
||||
|
||||
ethers/v5.0.0-beta.190 (2020-06-01 05:02)
|
||||
-----------------------------------------
|
||||
|
||||
- Re-enable tests removed to fix slow CI. ([cd7a0b3](https://github.com/ethers-io/ethers.js/commit/cd7a0b36cd77df5d5951a97cdb6b6be1c9387f51))
|
||||
- Major Contract refactor for overrides. ([#819](https://github.com/ethers-io/ethers.js/issues/819), [#845](https://github.com/ethers-io/ethers.js/issues/845), [#847](https://github.com/ethers-io/ethers.js/issues/847), [#860](https://github.com/ethers-io/ethers.js/issues/860); [42dee67](https://github.com/ethers-io/ethers.js/commit/42dee67187adb04d0b88f420b24cb3e73301d609))
|
||||
- Remove legacy Circle CI tasks. ([c445232](https://github.com/ethers-io/ethers.js/commit/c445232980007d3474bc036ff59fb37638f93820))
|
||||
- Fixing GitHub actions. ([#853](https://github.com/ethers-io/ethers.js/issues/853); [6b8f0f3](https://github.com/ethers-io/ethers.js/commit/6b8f0f3cb38295cd5d693f9b71f629b591206f1e))
|
||||
|
||||
ethers/v5.0.0-beta.189 (2020-05-29 21:25)
|
||||
-----------------------------------------
|
||||
|
||||
- Simplify typing for properties module. ([41e66ab](https://github.com/ethers-io/ethers.js/commit/41e66ab834e9835807481658a7956207edfef3d7))
|
||||
- Refactor Contract away from monolithic runMethod. ([e5a1b4d](https://github.com/ethers-io/ethers.js/commit/e5a1b4d5cbbaa0a8ce64c72e13d0d12fa2b856e3))
|
||||
- Correctly set last emitted block for WebSocketProvider. ([#856](https://github.com/ethers-io/ethers.js/issues/856); [1b0ad5a](https://github.com/ethers-io/ethers.js/commit/1b0ad5aa69327f80c7814069142965914673dc06))
|
||||
- Fixed delayed network detection attempting to overwrite read-only value. ([#854](https://github.com/ethers-io/ethers.js/issues/854); [8efd8d2](https://github.com/ethers-io/ethers.js/commit/8efd8d203158ebdef040ec759c3b423312a86e7c))
|
||||
- Better WebSocket compatibilities with Parity. ([#849](https://github.com/ethers-io/ethers.js/issues/849); [180a1af](https://github.com/ethers-io/ethers.js/commit/180a1aff3adc5b4af3a1349b52666ca5942c92a2))
|
||||
|
||||
ethers/v5.0.0-beta.188 (2020-05-21 00:02)
|
||||
-----------------------------------------
|
||||
|
||||
- Make filter blockHash property name match EIP-234. ([b03c4ed](https://github.com/ethers-io/ethers.js/commit/b03c4edd31a1929b411d0559d17eee7e3d6b11c8), [ed29fac](https://github.com/ethers-io/ethers.js/commit/ed29fac376c1a0aa210bf75979bb2ab62d0cf46b))
|
||||
- Fixed FallbackProvider sync-stalling for backends. ([#841](https://github.com/ethers-io/ethers.js/issues/841); [f963589](https://github.com/ethers-io/ethers.js/commit/f96358940043123aa7a8fe97a1af7af293ce9740))
|
||||
- Add correct tag to release on publish. ([#828](https://github.com/ethers-io/ethers.js/issues/828); [8516076](https://github.com/ethers-io/ethers.js/commit/85160766cdcd031f226382901ebadee9d7f40200))
|
||||
|
||||
ethers/v5.0.0-beta.187 (2020-05-12 23:29)
|
||||
-----------------------------------------
|
||||
|
||||
- Add sub-error to gas estimate error for Ganache users. ([#829](https://github.com/ethers-io/ethers.js/issues/829); [647fbd8](https://github.com/ethers-io/ethers.js/commit/647fbd8cbfa0f94f72db6faadd528e61c49b1dd6))
|
||||
- Moved ABI check for unique names to coding time and only if ambiguous. ([#816](https://github.com/ethers-io/ethers.js/issues/816); [fa87417](https://github.com/ethers-io/ethers.js/commit/fa87417e9416d99a37d9a2668a1e54feb7e342fc))
|
||||
- Added missing Interface exports to umbrella utils. ([82a9326](https://github.com/ethers-io/ethers.js/commit/82a93263fae330ae39a7212e74d973fa9f820f64))
|
||||
- Fixed FallbackProvider ESM super-this out-of-order issue. ([#822](https://github.com/ethers-io/ethers.js/issues/822); [fde102b](https://github.com/ethers-io/ethers.js/commit/fde102b7eda304403dcc677cd6d3b48339cd3a81))
|
||||
- Fixed node hanging on unnecessary timeout when fetchJson fails. ([fdf2253](https://github.com/ethers-io/ethers.js/commit/fdf2253218cf379043acc32dea8c95c284a82cec))
|
||||
|
||||
ethers/v5.0.0-beta.186 (2020-05-08 15:27)
|
||||
-----------------------------------------
|
||||
|
||||
- Fix JsonRpcProvider out-of-order super call. ([#822](https://github.com/ethers-io/ethers.js/issues/822); [963197d](https://github.com/ethers-io/ethers.js/commit/963197d70c96e5970b431173c2cc782cb496674c))
|
||||
|
||||
ethers/v5.0.0-beta.185 (2020-05-04 22:54)
|
||||
-----------------------------------------
|
||||
|
||||
- More robust FallbackProvider on clean exits. ([8eeda23](https://github.com/ethers-io/ethers.js/commit/8eeda23e989fcb0126bd20b17c67f62466d19259))
|
||||
- Safer test suite reporter timer. ([657a039](https://github.com/ethers-io/ethers.js/commit/657a0394f56b51a13c691477c2b0dcf74678fd7c))
|
||||
- Added goerli to AlchemyProvider tests. ([ab7c781](https://github.com/ethers-io/ethers.js/commit/ab7c78118ab80990a3e3368749599a1cf6e9d4ae))
|
||||
- Added more robust poll event to Provider. ([dc48bfb](https://github.com/ethers-io/ethers.js/commit/dc48bfb7adb9334848c93173ba2c634f22a9a72f))
|
||||
- Added goerli to AlchemyProvider. ([86670eb](https://github.com/ethers-io/ethers.js/commit/86670eb80e96fc4ba4e3664c9389f8130bbfea73))
|
||||
- Removed Cloudflare from test suite; it is down again. ([17dc022](https://github.com/ethers-io/ethers.js/commit/17dc022603afdfe4147638ab4b2704bcef09533f))
|
||||
- Prevent forceOutput in test reporter from crashing. ([cafd344](https://github.com/ethers-io/ethers.js/commit/cafd34460b194d78092021f1d7e0307130340b68))
|
||||
- Stall FallbackProvider backends from requests if not in-sync. ([fa6904f](https://github.com/ethers-io/ethers.js/commit/fa6904fef35e7ab888221f3a0613bfe7e6df3594))
|
||||
- Allow providers to detect their network after instantiation. ([#814](https://github.com/ethers-io/ethers.js/issues/814); [99ae946](https://github.com/ethers-io/ethers.js/commit/99ae946476a317a9d89e5d8f57cf37f8680bfa2b))
|
||||
- Better messaging on low-level network errors. ([#814](https://github.com/ethers-io/ethers.js/issues/814); [0e3a66c](https://github.com/ethers-io/ethers.js/commit/0e3a66c82959a08f3f4e4ffbca3ae3792ff2548f))
|
||||
- Manage FallbackProvider stalling without unref. ([#815](https://github.com/ethers-io/ethers.js/issues/815); [7b1a7c7](https://github.com/ethers-io/ethers.js/commit/7b1a7c7f31a3631e12c2a341b562983360e670e9))
|
||||
- Only error on duplicate signatures in Contract ABI. ([#499](https://github.com/ethers-io/ethers.js/issues/499); [098d7ef](https://github.com/ethers-io/ethers.js/commit/098d7efb21bd648c2660342297d2419904a10925))
|
||||
- Added getWebSocketProvider static method to InfuraProvider. ([a6c1174](https://github.com/ethers-io/ethers.js/commit/a6c1174dffe6dca1a3a64d1d472cec6e12372117))
|
||||
- Fix WebSocketProvider responses when message result is null. ([#813](https://github.com/ethers-io/ethers.js/issues/813); [472e5b0](https://github.com/ethers-io/ethers.js/commit/472e5b07eab180baa12185c8f00e5079ce4c671f))
|
||||
- Allow modifiers on Human-Readable ABI for tuples and arrays. ([83fba3d](https://github.com/ethers-io/ethers.js/commit/83fba3de25b524cc48975b1952f4319d63874205))
|
||||
- Added initial renew support to ENS CLI. ([54dfb75](https://github.com/ethers-io/ethers.js/commit/54dfb757c4c88e4bcada1890c4016fadfb25581a))
|
||||
- Allow contract filters to include OR-ed values. ([#437](https://github.com/ethers-io/ethers.js/issues/437); [28800d7](https://github.com/ethers-io/ethers.js/commit/28800d7681f3bab08f6d30a22f0813e04feee18a))
|
||||
|
||||
ethers/v5.0.0-beta.184 (2020-04-28 04:58)
|
||||
-----------------------------------------
|
||||
|
||||
- Removed old EIP-1193 experimental provider; it can now be supported by Web3Provider as EIP-1193 is now backwards compatible. ([84c68ac](https://github.com/ethers-io/ethers.js/commit/84c68ac5c17b10897ade966d6c8fac1f1f66a4af))
|
||||
- Fixed getLogs filter deserialization. ([#805](https://github.com/ethers-io/ethers.js/issues/805); [393c0c7](https://github.com/ethers-io/ethers.js/commit/393c0c74a91175adca2e25026dcdb9e6445afd8f))
|
||||
- Added EIP-1193 support to Web3Provider. ([56af441](https://github.com/ethers-io/ethers.js/commit/56af4413b1dd1787db68985e0b612b63d86fdf7c))
|
||||
- Minor typing-detected fixes. ([d1f3a42](https://github.com/ethers-io/ethers.js/commit/d1f3a42c119d5588eab667ec7bb6e71042cfb656))
|
||||
- Added initial support for recoverable coding erros. ([#800](https://github.com/ethers-io/ethers.js/issues/800); [bda6623](https://github.com/ethers-io/ethers.js/commit/bda66230916e58e25a522e8430ce4de25091eb6b))
|
||||
- More draconian Typing. ([14e6811](https://github.com/ethers-io/ethers.js/commit/14e6811bf7d7c38a3b5714dededcc883c185d814))
|
||||
- Omit HID libraries for hardware-wallets package on unsupported environments. ([#798](https://github.com/ethers-io/ethers.js/issues/798); [2e24920](https://github.com/ethers-io/ethers.js/commit/2e24920d028d42908d0764ad4ca0b56b55f852d1), [5aefb43](https://github.com/ethers-io/ethers.js/commit/5aefb4303d2fdda62e7e5ddb644919f613d6016a))
|
||||
- Make default constructor non-payable. ([#684](https://github.com/ethers-io/ethers.js/issues/684); [017ea0d](https://github.com/ethers-io/ethers.js/commit/017ea0d6bd22833e9d399ae6b818443786f17884))
|
||||
|
||||
ethers/v5.0.0-beta.183 (2020-04-23 23:28)
|
||||
-----------------------------------------
|
||||
|
||||
- Fixed inconsistent log format in WebSocketProvider. ([#795](https://github.com/ethers-io/ethers.js/issues/795); [8e7751f](https://github.com/ethers-io/ethers.js/commit/8e7751f7dfb41e58f81c7918cf36c152c3209ae2))
|
||||
- Added WebSocketProvider support for ENS names in filters. ([6707754](https://github.com/ethers-io/ethers.js/commit/6707754580490c5a801d6205af0841794d20b3c9))
|
||||
- Fixed provider filtering by ENS name. ([aeeb75f](https://github.com/ethers-io/ethers.js/commit/aeeb75f74c3be11b9b3b2925fd73349070542e54))
|
||||
- Fixed ContractFactory.deploy ignoring overrides. ([#796](https://github.com/ethers-io/ethers.js/issues/796); [8bb2a0f](https://github.com/ethers-io/ethers.js/commit/8bb2a0fd08f6f128a80444e3fd90c29e4cd7edfb))
|
||||
- Fix median calculation for large block number deltas across FallbackProvider backends. ([fca5ccb](https://github.com/ethers-io/ethers.js/commit/fca5ccbc2052569e700a96dbb1de1c9cef7c966f))
|
||||
- Work-around for Cloudflare not offering eth_blockNumber. ([8cf4b3c](https://github.com/ethers-io/ethers.js/commit/8cf4b3cf4598f4f3643d5ebe9c366466d398cb83))
|
||||
- Added string spell-checking to library and fixed discovered typos. ([71d03c6](https://github.com/ethers-io/ethers.js/commit/71d03c6e3cab1aacb3e4e74d3966fbaa7db2ee06))
|
||||
- Fixed getUrl for node 8. ([560adea](https://github.com/ethers-io/ethers.js/commit/560adeabb06a2ab483bcad162f02ccef41ebc245))
|
||||
- Dependency security updates. ([da3b0bf](https://github.com/ethers-io/ethers.js/commit/da3b0bf0786fe8a95c68485d130ca59c597ffe4d))
|
||||
- Fixes for dist builds without injected XMLHttpRequest. ([#789](https://github.com/ethers-io/ethers.js/issues/789), [#506](https://github.com/ethers-io/ethers.js/issues/506); [9ae6b70](https://github.com/ethers-io/ethers.js/commit/9ae6b70efb9f3d3251820403597085cfa30ace05))
|
||||
|
||||
ethers/v5.0.0-beta.182 (2020-04-16 21:53)
|
||||
-----------------------------------------
|
||||
|
||||
- Added support for Contract event parsing error recovery. ([cc72f76](https://github.com/ethers-io/ethers.js/commit/cc72f76695572d235d7f5a5ad4dc1838a5fe884a))
|
||||
- Fix provider log filters with zero topics. ([#785](https://github.com/ethers-io/ethers.js/issues/785); [4ef0e4f](https://github.com/ethers-io/ethers.js/commit/4ef0e4f7653226bf8cca86e065ad614e7288af96))
|
||||
|
||||
ethers/v5.0.0-beta.181 (2020-04-15 18:23)
|
||||
-----------------------------------------
|
||||
|
||||
- Temporarily remove CloudflareProvider tests; it is down and breaking the tests. ([797abb7](https://github.com/ethers-io/ethers.js/commit/797abb726711499d96bf1c12c61e3bb1a7b4925d))
|
||||
- Better error reporting for Fragments. ([7dcefcb](https://github.com/ethers-io/ethers.js/commit/7dcefcbf71ef337103639bbe3f4ad2625565651a))
|
||||
- Fixed Contract filter unsubscribing. ([2eb3823](https://github.com/ethers-io/ethers.js/commit/2eb3823de4ba111cc0c746a0715fe6dd3d1b16da), [39c78f3](https://github.com/ethers-io/ethers.js/commit/39c78f37ceff9b8ec08329903dcba7bd53bd8661))
|
||||
- Fixed WebSocketProvider filter events. ([#784](https://github.com/ethers-io/ethers.js/issues/784); [69f7077](https://github.com/ethers-io/ethers.js/commit/69f707762ed5939c5f52bf6dce5c5513aaf6fa1d))
|
||||
- Added bitwise operations to BigNumber. ([#781](https://github.com/ethers-io/ethers.js/issues/781); [7498c18](https://github.com/ethers-io/ethers.js/commit/7498c18235c7566b2f652cddba991f55e0943da8), [284771e](https://github.com/ethers-io/ethers.js/commit/284771ea39b6f4ee9cdf75ce5feea9e6aa9a65c5))
|
||||
|
||||
ethers/v5.0.0-beta.180 (2020-04-03 22:10)
|
||||
-----------------------------------------
|
||||
|
||||
- Correctly return the Provider in NonceManager. ([6caf7c2](https://github.com/ethers-io/ethers.js/commit/6caf7c292cd5f03741cd6b30053c3325c4f30a81))
|
||||
- Fail earlier when resolving an ENS name that is not a string. ([2882546](https://github.com/ethers-io/ethers.js/commit/28825463517f8821392464ec2283ee59c431d928))
|
||||
- Fixed mutabilityState calculation for function fragments. ([#762](https://github.com/ethers-io/ethers.js/issues/762); [6526de0](https://github.com/ethers-io/ethers.js/commit/6526de016fda5403474dad61ee59acc62ee25ebc), [d7c8b35](https://github.com/ethers-io/ethers.js/commit/d7c8b355a049b36068b0525a357c6278639a8d58))
|
||||
- Force Log properties to be non-optional. ([#415](https://github.com/ethers-io/ethers.js/issues/415); [da412f6](https://github.com/ethers-io/ethers.js/commit/da412f660723d1c411484e74970ce4eb166374c2), [8ad26f0](https://github.com/ethers-io/ethers.js/commit/8ad26f0ff42614a6c40e735cb6fffd36874da1a0))
|
||||
- Fixed Signer call not forwarding blockTag. ([#768](https://github.com/ethers-io/ethers.js/issues/768); [053a2d7](https://github.com/ethers-io/ethers.js/commit/053a2d7fcdb4ca4c9bfd0bee0f42e0187d3db477))
|
||||
|
||||
ethers/v5.0.0-beta.179 (2020-03-31 23:40)
|
||||
-----------------------------------------
|
||||
|
||||
- Fixed ENS CLI lookup for Website. ([0f144c6](https://github.com/ethers-io/ethers.js/commit/0f144c6cc03082026080782356b940af3389b34e))
|
||||
- Fixed getEtherPrice for EtherscanProvider. ([#776](https://github.com/ethers-io/ethers.js/issues/776); [6c71b51](https://github.com/ethers-io/ethers.js/commit/6c71b515126d8ef3cea5a1aec814c4cab56cc1a5))
|
||||
- Fixed ENS CLI tool set-websites and added set-name. ([70cffb6](https://github.com/ethers-io/ethers.js/commit/70cffb6a5166a79a54e02b03b6a7ec0085407e07))
|
||||
|
||||
ethers/v5.0.0-beta.178 (2020-03-30 22:14)
|
||||
-----------------------------------------
|
||||
|
||||
- Fixed Event args keyword access. ([2692e78](https://github.com/ethers-io/ethers.js/commit/2692e783b40ce16207fa1a8e8513ebb5455fd2d0), [092ce9b](https://github.com/ethers-io/ethers.js/commit/092ce9bcc2abf92c40550c4a990a8e2c889cc250))
|
||||
- Updating TypeScript library and fixing some audit issues. ([bd32ee0](https://github.com/ethers-io/ethers.js/commit/bd32ee0af5b25a435e5896773d8bfd482d3adcaf))
|
||||
|
||||
ethers/v5.0.0-beta.177 (2020-03-21 12:46)
|
||||
-----------------------------------------
|
||||
|
||||
- Abstracted JSON-RPC parameter generation for others to use. ([030f65e](https://github.com/ethers-io/ethers.js/commit/030f65e66ce059d69d8d77973d5c3190745eaac2))
|
||||
- Updated RLP package to use Logger instead of bare errors. ([390497f](https://github.com/ethers-io/ethers.js/commit/390497f38964a052837f6c0e7c96efe74c668517))
|
||||
- Fixed log level filtering for Logger. ([#379](https://github.com/ethers-io/ethers.js/issues/379); [72c8992](https://github.com/ethers-io/ethers.js/commit/72c89922a4e1b77295414c8e0717a7373f2397b8))
|
||||
- Throw errors when trying to RLP encode integers. ([9ea16e5](https://github.com/ethers-io/ethers.js/commit/9ea16e5172928962792ba4c0273e23db373409e0))
|
||||
- Added delays to provider tests to prevent throttling causing failed tests. ([3e44aac](https://github.com/ethers-io/ethers.js/commit/3e44aac8f199ec09babb20c4af2ee668e0ab05a1))
|
||||
|
||||
ethers/v5.0.0-beta.176 (2020-03-12 19:10)
|
||||
-----------------------------------------
|
||||
|
||||
- Checking in initial Eip1193Bridge (experimental). ([2c78f0b](https://github.com/ethers-io/ethers.js/commit/2c78f0bf265a0f7c9f4cfc1bc79ecd4629b59c49))
|
||||
- Added initial WebSocketProvider. ([#141](https://github.com/ethers-io/ethers.js/issues/141); [117a5dd](https://github.com/ethers-io/ethers.js/commit/117a5dd7ffa783c4335c0b87621437447cd499d0))
|
||||
- Renamed properties based on community recommendations; estimate to estimateGas and addressPromise to resovledAddress. ([fe3b3fa](https://github.com/ethers-io/ethers.js/commit/fe3b3fa1aded67827fec1131931d95d8153d8f32))
|
||||
- Better error reporting and fixed look-ahead for data labels. ([e52312e](https://github.com/ethers-io/ethers.js/commit/e52312e783b8d0fdd7e9992716cbe2e179751b38))
|
||||
|
||||
ethers/v5.0.0-beta.175 (2020-02-27 19:53)
|
||||
-----------------------------------------
|
||||
|
||||
- Fix address-less filter listening in Provider. ([#741](https://github.com/ethers-io/ethers.js/issues/741); [64dccb2](https://github.com/ethers-io/ethers.js/commit/64dccb275c68ebb40328350d4ab5be0f29b8a02e))
|
||||
- Added sync version of wallet decryption. ([0ad94cd](https://github.com/ethers-io/ethers.js/commit/0ad94cdf8137259bedb38c0dc949b61570bcdac0), [6809c37](https://github.com/ethers-io/ethers.js/commit/6809c370c027aea148466c00d3ce09c6d0ee6ddc))
|
||||
|
||||
ethers/v5.0.0-beta.175 (2020-02-27 19:38)
|
||||
-----------------------------------------
|
||||
|
||||
- Fix address-less filter listening in Provider. ([#741](https://github.com/ethers-io/ethers.js/issues/741); [64dccb2](https://github.com/ethers-io/ethers.js/commit/64dccb275c68ebb40328350d4ab5be0f29b8a02e))
|
||||
- Added sync version of wallet decryption. ([0ad94cd](https://github.com/ethers-io/ethers.js/commit/0ad94cdf8137259bedb38c0dc949b61570bcdac0))
|
||||
|
||||
ethers/v5.0.0-beta.174 (2020-02-25 14:57)
|
||||
-----------------------------------------
|
||||
|
||||
- Reduced default Provider quorum for testnets. ([1cfab31](https://github.com/ethers-io/ethers.js/commit/1cfab3173c3d0519beffc054efe73f70b7d28501))
|
||||
- Added JSON-RPC debugging on error responses. ([ad27600](https://github.com/ethers-io/ethers.js/commit/ad27600c699827858e7343adff2d4fa622248e42))
|
||||
- Fixed setLogLevel to affect global logging. ([ac51a88](https://github.com/ethers-io/ethers.js/commit/ac51a88c2913d7055e050c91d7d96bb42abf6656))
|
||||
- Renamed interface getTopic to getEventTopic. ([f61f34b](https://github.com/ethers-io/ethers.js/commit/f61f34bfb295bafee3b7ee426efa696aaa9bbafe))
|
||||
- Fix log parsing when no matching topic hash is found. ([#733](https://github.com/ethers-io/ethers.js/issues/733); [a5d2ec5](https://github.com/ethers-io/ethers.js/commit/a5d2ec534f75b21eebe69a789a3c43c33014a825), [4b8e198](https://github.com/ethers-io/ethers.js/commit/4b8e198bf209fcf0aea55018d8940355ea4345de), [89ac9f4](https://github.com/ethers-io/ethers.js/commit/89ac9f4f298ac340c4429e8ebdacd29962eba7f4))
|
||||
|
||||
ethers/v5.0.0-beta.173 (2020-02-12 17:09)
|
||||
-----------------------------------------
|
||||
|
||||
- Added experimental EipWrappedProvider. ([944600d](https://github.com/ethers-io/ethers.js/commit/944600d779564c500ab98d3265286a0717642614))
|
||||
- Updated signature for JsonRpcProvider.send to match EIP-1193. ([b962b59](https://github.com/ethers-io/ethers.js/commit/b962b59ab72e67bc4566a361964e42cf1b791025))
|
||||
- Added binary literal support to ASM grammar. ([375bd15](https://github.com/ethers-io/ethers.js/commit/375bd15594a3179432e8452d819d91ea72b4bdd8))
|
||||
- Added explicit pop placeholders to ASM dialect. ([a6b696d](https://github.com/ethers-io/ethers.js/commit/a6b696d8bd03c4027b52fe23745f066d158f1420))
|
||||
- Added position independent code option for asm. ([89615c5](https://github.com/ethers-io/ethers.js/commit/89615c59d385a58fa79b6bbd8eae53c30e45fe96))
|
||||
- Added ASM semantic checking and the Pop placeholder. ([a33bf0e](https://github.com/ethers-io/ethers.js/commit/a33bf0e37f4f969cc03b85ebf0dbadcf3e9b068a))
|
||||
- Better type safety for defineReadOnly. ([e7adc84](https://github.com/ethers-io/ethers.js/commit/e7adc84a972968f39a983efb6f21b6ceaacd6cc5))
|
||||
- Fixed CLI sandbox quiting after prompt entry. ([ff9bc2a](https://github.com/ethers-io/ethers.js/commit/ff9bc2a282e617125bbca76702dec85149661390))
|
||||
|
||||
ethers/v5.0.0-beta.172 (2020-02-04 00:59)
|
||||
-----------------------------------------
|
||||
|
||||
- Synced GitHub issue cache. ([13dbf1f](https://github.com/ethers-io/ethers.js/commit/13dbf1f965eab344d2a304f7612d19ea96391261))
|
||||
- Better typing for Timers. ([5622f70](https://github.com/ethers-io/ethers.js/commit/5622f703d962993442623ef1450a595825c4efa8))
|
||||
- Safer transaction serialization, matching signature.v with chainId. ([#708](https://github.com/ethers-io/ethers.js/issues/708); [edb7c5d](https://github.com/ethers-io/ethers.js/commit/edb7c5da91ce271688561364d867998b0f0675e3))
|
||||
- Fixed Opcode typo and added check to prevent future typos. ([15bb840](https://github.com/ethers-io/ethers.js/commit/15bb8409077f96b22e8bd60c426cddd015454e6b))
|
||||
- Renamed AST nodes for teh assembler. ([f02c7db](https://github.com/ethers-io/ethers.js/commit/f02c7db4109d1785b4528757aa50f24948e896ae))
|
||||
- Added timeout to waitForTransaction. ([#477](https://github.com/ethers-io/ethers.js/issues/477); [bacc440](https://github.com/ethers-io/ethers.js/commit/bacc4403979fa423890e269e7a5c7d11c6891a9f))
|
||||
- Added CLI for asm package. ([aafa42a](https://github.com/ethers-io/ethers.js/commit/aafa42a32b2a5c7481a409ad048dfc06112c6599))
|
||||
- Prevent Signer.checkTransaction from creating conflicting from properties. ([1decb13](https://github.com/ethers-io/ethers.js/commit/1decb1379902b60a15925b9b1de39633393db825))
|
||||
- Include asm in generated TypeScript dependencies. ([ba29618](https://github.com/ethers-io/ethers.js/commit/ba296188960fb345dfdab12f2bb3ed3dc5eab51a))
|
||||
- Clean up some asm checks and dead code. ([fa317eb](https://github.com/ethers-io/ethers.js/commit/fa317ebc032f8a5f9fb2dd10e23496252ae744e1))
|
||||
- More contained Opcode API. ([da8153c](https://github.com/ethers-io/ethers.js/commit/da8153c87753b79e5e4cd34d484b8e0e717426d9))
|
||||
- Added initial codedrop for the asm package. ([0296594](https://github.com/ethers-io/ethers.js/commit/0296594aba8d1e90e9ef7a18d2324f6cac815953))
|
||||
|
||||
ethers/v5.0.0-beta.171 (2020-02-01 05:05)
|
||||
-----------------------------------------
|
||||
|
||||
- Added CLI for asm package. ([aafa42a](https://github.com/ethers-io/ethers.js/commit/aafa42a32b2a5c7481a409ad048dfc06112c6599))
|
||||
- Added more flatworm documentation. ([1c85fe9](https://github.com/ethers-io/ethers.js/commit/1c85fe95b2b536828e83087676becba85c9a90bb))
|
||||
- Prevent Signer.checkTransaction from creating conflicting from properties. ([1decb13](https://github.com/ethers-io/ethers.js/commit/1decb1379902b60a15925b9b1de39633393db825))
|
||||
- Include asm in generated TypeScript dependencies. ([ba29618](https://github.com/ethers-io/ethers.js/commit/ba296188960fb345dfdab12f2bb3ed3dc5eab51a))
|
||||
- Clean up some asm checks and dead code. ([fa317eb](https://github.com/ethers-io/ethers.js/commit/fa317ebc032f8a5f9fb2dd10e23496252ae744e1))
|
||||
- More contained Opcode API. ([da8153c](https://github.com/ethers-io/ethers.js/commit/da8153c87753b79e5e4cd34d484b8e0e717426d9))
|
||||
- Added initial codedrop for the asm package. ([0296594](https://github.com/ethers-io/ethers.js/commit/0296594aba8d1e90e9ef7a18d2324f6cac815953))
|
||||
|
||||
ethers/v5.0.0-beta.171 (2020-01-29 21:41)
|
||||
-----------------------------------------
|
||||
|
||||
- Better solc support in CLI; it will search the local pacakge for an existing solc version. ([7428776](https://github.com/ethers-io/ethers.js/commit/7428776f75222d5c07282bc29c3dd8ed99f5d2cc))
|
||||
- Update ENS registry address and lower default quorum for testnets. ([edb49da](https://github.com/ethers-io/ethers.js/commit/edb49da15518f25b3d60813ebb84f54171e308f3))
|
||||
- Exposed isBytes and isBytesLike in ethers.utils. ([99329b0](https://github.com/ethers-io/ethers.js/commit/99329b013ce7f3af301d40c41f7eb35bff288910))
|
||||
|
||||
ethers/v5.0.0-beta.170 (2020-01-21 20:37)
|
||||
-----------------------------------------
|
||||
|
||||
- Better, easier and more provider testing. ([e0d1d38](https://github.com/ethers-io/ethers.js/commit/e0d1d3866d2559f39627254873a0a1d4c0fcaf3d))
|
||||
- Fixed out-of-bounds difficulty in getBlock, which can affect PoA networks. ([#711](https://github.com/ethers-io/ethers.js/issues/711); [251882c](https://github.com/ethers-io/ethers.js/commit/251882ced4379931ec82ba28a4db10bc7dbf3580))
|
||||
|
||||
ethers/v5.0.0-beta.169 (2020-01-20 19:42)
|
||||
-----------------------------------------
|
||||
|
||||
- Fixed imports after refactor. ([adf5622](https://github.com/ethers-io/ethers.js/commit/adf56229c6cc83003d319ea9a004677e2555d478))
|
||||
- Refactor some enum names and add UTF-8 error support to the umbrella package. ([931da2f](https://github.com/ethers-io/ethers.js/commit/931da2f77446fc9266cf07f0d7d78d4376625005))
|
||||
- Allow arbitrary apiKey for UrlJsonRpcProvider. ([5878b54](https://github.com/ethers-io/ethers.js/commit/5878b54d6eded1329a6dc3b4023f876a87f72b6e))
|
||||
- Added more general error handling (e.g. error, ignore, replace) for calling toUtf8String. ([a055edb](https://github.com/ethers-io/ethers.js/commit/a055edb5855b96fdf179403458c1694b96fd906c))
|
||||
|
||||
ethers/v5.0.0-beta.168 (2020-01-18 21:46)
|
||||
-----------------------------------------
|
||||
|
||||
- Much more resiliant FallbackProvider which can ignore properties that are only approximate and supports per-provider priorities. ([#635](https://github.com/ethers-io/ethers.js/issues/635), [#588](https://github.com/ethers-io/ethers.js/issues/588); [f4bcf24](https://github.com/ethers-io/ethers.js/commit/f4bcf24a257a17ec9beb98f3d0b3682de543534c))
|
||||
- Fixed some typing for receipts and logs. ([#497](https://github.com/ethers-io/ethers.js/issues/497); [ea102ef](https://github.com/ethers-io/ethers.js/commit/ea102ef7c4fa5df7b9389fbc8a2947bbbd4c471e))
|
||||
- Abstracting mnemonic phrases. ([#685](https://github.com/ethers-io/ethers.js/issues/685); [92a383f](https://github.com/ethers-io/ethers.js/commit/92a383ff0dad4587e44953efca3c6ab795a1b1bd))
|
||||
- Sync GitHub issues. ([75e1a37](https://github.com/ethers-io/ethers.js/commit/75e1a37bb5935d5d538ffcfce5b0073e1334d457))
|
||||
- Fixed 304 status for fetchJson. ([c66d81e](https://github.com/ethers-io/ethers.js/commit/c66d81e96f7c9b0808f181085ffe1c92f6219d46))
|
||||
|
||||
ethers/v5.0.0-beta.167 (2020-01-11 04:16)
|
||||
-----------------------------------------
|
||||
|
||||
- Fixed testcases for provider changes. ([90ed07c](https://github.com/ethers-io/ethers.js/commit/90ed07c74e7230ea0f02288b140d497d8b9779e0))
|
||||
- Add support for legacy flat signatures with recid instead of normalized v. ([245cd0e](https://github.com/ethers-io/ethers.js/commit/245cd0e48e07eef35f5bf45ee7fe5ed5ef31338a))
|
||||
- Fix TransactionResponse to have chainId instead of legacy networkId. ([#700](https://github.com/ethers-io/ethers.js/issues/700); [72b3bc9](https://github.com/ethers-io/ethers.js/commit/72b3bc9909074893038c768f3da1564ed96a6a20))
|
||||
- Fixed splitSignature computing wrong v for BytesLike. ([#700](https://github.com/ethers-io/ethers.js/issues/700); [4151c0e](https://github.com/ethers-io/ethers.js/commit/4151c0eacd22287e2369a8656ffa00359db6f84b))
|
||||
- Added dist files for hardware-wallets. ([c846649](https://github.com/ethers-io/ethers.js/commit/c84664953d2f50ee0d704a8aa18fe6c08668dabb))
|
||||
- Browser support (with dist files) for Ledger. ([6f7fbf3](https://github.com/ethers-io/ethers.js/commit/6f7fbf3858c82417933a5e5595a919c0ec0487c7))
|
||||
|
||||
ethers/v5.0.0-beta.166 (2020-01-10 03:09)
|
||||
-----------------------------------------
|
||||
|
||||
- Relaxed joinSignature API to allow SignauteLike. ([602e6a8](https://github.com/ethers-io/ethers.js/commit/602e6a8973480299843a0158f75451a2c6aac749))
|
||||
- Initial code drop of new hardware wallet package. ([2e8f5ca](https://github.com/ethers-io/ethers.js/commit/2e8f5ca7ed498261079da75713b18f3370dfd236))
|
||||
- Added more docs. ([381a72d](https://github.com/ethers-io/ethers.js/commit/381a72ddaa7fb59ef2ded84d228296d693df05c3))
|
||||
|
||||
ethers/v5.0.0-beta.165 (2020-01-09 03:31)
|
||||
-----------------------------------------
|
||||
|
||||
- Fixed require resolution for CLI scripts. ([c04f9a7](https://github.com/ethers-io/ethers.js/commit/c04f9a7fff727bb04a4aa3a0fa05fd5cd8e795a6))
|
||||
- Added new URLs for default ETC (and ETC testnets) providers. ([#351](https://github.com/ethers-io/ethers.js/issues/351); [3c184ac](https://github.com/ethers-io/ethers.js/commit/3c184ace21aafbb27f4d44cce1bb738af899d59f))
|
||||
|
||||
ethers/v5.0.0-beta.164 (2020-01-07 19:57)
|
||||
-----------------------------------------
|
||||
|
||||
- Use better Description typing. ([2d5492c](https://github.com/ethers-io/ethers.js/commit/2d5492cd2ee722c818c249244af7b5bea05d67b0))
|
||||
- Better property access on ABI decoded results. ([#698](https://github.com/ethers-io/ethers.js/issues/698); [13f50ab](https://github.com/ethers-io/ethers.js/commit/13f50abd847f7ddcc7e54c102da54e2d23b86fae))
|
||||
- Better typing support for Description. ([d0f4642](https://github.com/ethers-io/ethers.js/commit/d0f4642f6d2c9f5119f1910a0082894c60e81191))
|
||||
- Fixed resolveName when name is an address with an invalid checksum. ([#694](https://github.com/ethers-io/ethers.js/issues/694); [1e72fc7](https://github.com/ethers-io/ethers.js/commit/1e72fc7d6f7c3be4410dbdcfbab9a0463ceb52bd))
|
||||
|
||||
ethers/v5.0.0-beta.163 (2020-01-06 18:57)
|
||||
-----------------------------------------
|
||||
|
||||
- Added function to generate CREATE2 addresses. ([#697](https://github.com/ethers-io/ethers.js/issues/697); [eb26a6d](https://github.com/ethers-io/ethers.js/commit/eb26a6d95022a241c44f859e7b2f29646afb4914))
|
||||
- Force constructor name to be null (instead of undefined). ([a648f2b](https://github.com/ethers-io/ethers.js/commit/a648f2bd1e5e52a3662896f04fe7025884866972))
|
||||
- Added documentation uploading script. ([e593aba](https://github.com/ethers-io/ethers.js/commit/e593aba2946c98820b0c2edf9c5dab6cb30c7402))
|
||||
- Added Czech wordlist to default wordlists export. ([#691](https://github.com/ethers-io/ethers.js/issues/691); [5724fa5](https://github.com/ethers-io/ethers.js/commit/5724fa5d9c6fe73f14ec8bdea1f7226a222537ef))
|
||||
- Added Czech BIP-39 wordlist. ([#691](https://github.com/ethers-io/ethers.js/issues/691); [f54f06b](https://github.com/ethers-io/ethers.js/commit/f54f06b5c8092997fd3c9055d69a3e0796ce44f3))
|
||||
- Updated README. ([e809ead](https://github.com/ethers-io/ethers.js/commit/e809eadf8d608cd8c8a78c08a2e3547dd09156cf))
|
||||
- Updating docs. ([184c459](https://github.com/ethers-io/ethers.js/commit/184c459fab0d089a8a879584b72e5eb3560b33ce))
|
||||
- Merge branch 'yuetloo-ethers-v5-beta' into ethers-v5-beta ([06cafe3](https://github.com/ethers-io/ethers.js/commit/06cafe3437ef129b47f5f9c02f4759f2c4854d3c))
|
||||
- Add circleci and parity test files ([fdf0980](https://github.com/ethers-io/ethers.js/commit/fdf0980663ffead0faf3e9b7b233b22ca1574e21))
|
||||
- Fixed typo in package test dist scripts. ([9c78c7f](https://github.com/ethers-io/ethers.js/commit/9c78c7fee69d07733048d898d58205ae7f5c82d7))
|
||||
|
||||
ethers/v5.0.0-beta.162 (2019-11-25 00:02)
|
||||
-----------------------------------------
|
||||
|
||||
- Update elliptic package to protect from Minerva timing attack. ([#666](https://github.com/ethers-io/ethers.js/issues/666); [cf036e1](https://github.com/ethers-io/ethers.js/commit/cf036e1ffad3340fcf1c7559d0032493ccc08e6e))
|
||||
- Browser and node testing works again. ([4470477](https://github.com/ethers-io/ethers.js/commit/4470477d7fd3031f2f3a1fbd9c538468c33c7350))
|
||||
|
||||
ethers/v5.0.0-beta.161 (2019-11-23 21:43)
|
||||
-----------------------------------------
|
||||
|
||||
- Updated dist files (sorted package.json to reduce package version change chatter). ([f308ba3](https://github.com/ethers-io/ethers.js/commit/f308ba3540ed0d282d099456d0369873ad9596b0))
|
||||
- Stubs for adding throttle support. ([2f0e679](https://github.com/ethers-io/ethers.js/commit/2f0e679f0bc81bf901cf60a79e50f9715cddec5a))
|
||||
- Refactor wordlists. ([abab9f6](https://github.com/ethers-io/ethers.js/commit/abab9f6aa27d1870d1053e7caa951408b86c454d))
|
||||
- Browser testcases work again. ([c11c2e2](https://github.com/ethers-io/ethers.js/commit/c11c2e2e3376a6764f07ed443245823f2792b8cc))
|
||||
- Added dist files for non-English wordlists. ([3d75c52](https://github.com/ethers-io/ethers.js/commit/3d75c52dac668af5eeede3e7764dadd3055a0707))
|
||||
- Sync GitHub issue cache. ([29f0e9d](https://github.com/ethers-io/ethers.js/commit/29f0e9dd627a7b4b7f772300497f27718c9ecc7b))
|
||||
|
||||
ethers/v5.0.0-beta.160 (2019-11-20 18:36)
|
||||
-----------------------------------------
|
||||
|
||||
- Updated API in testcases. ([3ab3733](https://github.com/ethers-io/ethers.js/commit/3ab373334c75800f2b20b6639ed8eb1b11e453ef))
|
||||
- Fixed scrypt import in ESM build. ([b72ef27](https://github.com/ethers-io/ethers.js/commit/b72ef27b2a8f9941fb9d79122ec449fed9d2464d))
|
||||
- Fixed null apiKey problem for InfuraProvider. ([e518151](https://github.com/ethers-io/ethers.js/commit/e51815150912d10e2734707986b10b37c87d6d12))
|
||||
- Added support for sighash-style tuple parsing. ([19aaade](https://github.com/ethers-io/ethers.js/commit/19aaade9c62510012cfd50ae487ebd1705a28678))
|
||||
- Fixed solc imports for cli. ([c35ddaf](https://github.com/ethers-io/ethers.js/commit/c35ddaf646efa25e738fee604585a0a7af45b206))
|
||||
- Added nonce manager to experimental index. ([8316406](https://github.com/ethers-io/ethers.js/commit/8316406977ea26ca2044d16f7b3bb6ba21ef5b43))
|
||||
- Removing NodesmithProvider from default provider as it is being discontinued. ([01ca350](https://github.com/ethers-io/ethers.js/commit/01ca35036ca11a47f60890e5cae62e46a00f3da8))
|
||||
- Moved bare ABI named functions and events from Interface into Contracts to simplify other consumers of Interface. ([da8ca2e](https://github.com/ethers-io/ethers.js/commit/da8ca2e8bc982fc3ea0343bb3c593a485ca1fef0))
|
||||
- Added support for complex API keys including support for INFURA project secrets. ([#464](https://github.com/ethers-io/ethers.js/issues/464), [#651](https://github.com/ethers-io/ethers.js/issues/651), [#652](https://github.com/ethers-io/ethers.js/issues/652); [1ec5804](https://github.com/ethers-io/ethers.js/commit/1ec5804bd460f6948d4813469fdc7bf739baa6a6))
|
||||
- Migrated to scrypt-js v3. ([75895fa](https://github.com/ethers-io/ethers.js/commit/75895fa1491e7542c755a102f4e4c190685fd2b6))
|
||||
- Moved getDefaultProvider to providers package. ([51e4ef2](https://github.com/ethers-io/ethers.js/commit/51e4ef2b45b83a8d82923600a2fac544d70b0807))
|
||||
- Migrating providers to modern syntax and scoping. ([#634](https://github.com/ethers-io/ethers.js/issues/634); [e1509a6](https://github.com/ethers-io/ethers.js/commit/e1509a6326dd2cb8bf7ed64b82dd3947b768a314))
|
||||
- Migrating to modern syntax and scoping. ([#634](https://github.com/ethers-io/ethers.js/issues/634); [394c36c](https://github.com/ethers-io/ethers.js/commit/394c36cad43f229a94c72d21f94d1c7982a887a1))
|
||||
- Added provider property to Web3Provider. ([#641](https://github.com/ethers-io/ethers.js/issues/641); [1d4f90a](https://github.com/ethers-io/ethers.js/commit/1d4f90a958da6364117353850d62535c9702abd2))
|
||||
- Updated GitHub issue cache. ([494381a](https://github.com/ethers-io/ethers.js/commit/494381a6284cc8ed90bd8002d42a6b6d94dc1200))
|
||||
- Force deploy receipt to address to be null. ([#573](https://github.com/ethers-io/ethers.js/issues/573); [d9d438a](https://github.com/ethers-io/ethers.js/commit/d9d438a119bb11f8516fc9cf02c534ab3816fcb3))
|
||||
- Updated experimental NonceManager. ([3d514c8](https://github.com/ethers-io/ethers.js/commit/3d514c8dbb94e1c4ce5754463e683dd9dbe7c0aa))
|
||||
- Fixed typo in error message. ([28339a9](https://github.com/ethers-io/ethers.js/commit/28339a9c8585392086da159a46df4afb8958915c))
|
||||
- Added GitHub issue caching. ([fea867a](https://github.com/ethers-io/ethers.js/commit/fea867a206f007a17718396e486883a5e718aa29))
|
||||
|
||||
ethers/v5.0.0-beta.159 (2019-10-17 01:08)
|
||||
-----------------------------------------
|
||||
|
||||
- Removing TypeScript build files from npm to fix excessive package diffs.
|
||||
- Fixed getBlock for blockhashes with a leading 0. ([#629](https://github.com/ethers-io/ethers.js/issues/629); [12cfc59](https://github.com/ethers-io/ethers.js/commit/12cfc599656d7e3a6d3d9aa4e468592865a711cc))
|
||||
|
||||
ethers/v5.0.0-beta.158 (2019-09-28 01:56)
|
||||
-----------------------------------------
|
||||
|
||||
- Added less-common, but useful, coding functions to Interface. ([778eb3b](https://github.com/ethers-io/ethers.js/commit/778eb3b425b5ab5b23d28e75be92feccd0fc56bc))
|
||||
- Add response handling and 304 support to fetchJson. ([3d25882](https://github.com/ethers-io/ethers.js/commit/3d25882d6bf689740506b9c569f6e0d30da6f6a5))
|
||||
- Allow numeric values in a transaction to be odd-lengthed hexstrings. ([#614](https://github.com/ethers-io/ethers.js/issues/614); [a12030a](https://github.com/ethers-io/ethers.js/commit/a12030ad29aa13c02aa75d9e0860f4986a0043b4))
|
||||
- Simpler crypt for admin tools. ([828c8cf](https://github.com/ethers-io/ethers.js/commit/828c8cfd419ac4f8d11d978c2e2ff83eba5ae909))
|
||||
|
||||
ethers/v5.0.0-beta.157 (2019-09-08 02:43)
|
||||
-----------------------------------------
|
||||
|
||||
- Fixed getContractAddress for odd-length hex values. ([#572](https://github.com/ethers-io/ethers.js/issues/572); [751793e](https://github.com/ethers-io/ethers.js/commit/751793ea25183d54d7fc4c610a789608f91c062e))
|
||||
- Fixed typo in error message. ([#592](https://github.com/ethers-io/ethers.js/issues/592); [6f4291f](https://github.com/ethers-io/ethers.js/commit/6f4291f65f0ea20c65fef7fd7b09b4d5bf5f0dcd))
|
||||
- Fixed typo in error message. ([#580](https://github.com/ethers-io/ethers.js/issues/580); [9c63b4a](https://github.com/ethers-io/ethers.js/commit/9c63b4a7535f423a802bb1c17c325ce968987349))
|
||||
- Fixed typo in error message. ([#574](https://github.com/ethers-io/ethers.js/issues/574); [22a2673](https://github.com/ethers-io/ethers.js/commit/22a26736cc332fe6e896c9d2707cc99ceee2fb10))
|
||||
|
||||
ethers/v5.0.0-beta.156 (2019-09-06 17:56)
|
||||
-----------------------------------------
|
||||
|
||||
- Removed export star to fix UMD dist file. ([4c17c4d](https://github.com/ethers-io/ethers.js/commit/4c17c4db0455e1b89fd597c4c929cdc36aa3d90d))
|
||||
- Updated TypeScript version. ([e8028d0](https://github.com/ethers-io/ethers.js/commit/e8028d0e73368257b76b394bb8e2bf63f8aecd71))
|
||||
- Fixed test suites and reporter. ([1e0ed4e](https://github.com/ethers-io/ethers.js/commit/1e0ed4e99a22a27fe5057336f8cb320809768f3e))
|
||||
- Added lock-versions admin tool. ([2187604](https://github.com/ethers-io/ethers.js/commit/21876049137644af2b3afa31120ee95d032843a8))
|
||||
- Updated packages with version lock and moved types. ([85b4db7](https://github.com/ethers-io/ethers.js/commit/85b4db7d6db37b853f11a90cf4648c34404edcf9))
|
||||
- Fixed typo in error message. ([#592](https://github.com/ethers-io/ethers.js/issues/592); [019c1fc](https://github.com/ethers-io/ethers.js/commit/019c1fc7089b3da2d7bd41c933b6c6bc35c8dade))
|
||||
- Fixed build process to re-target browser field to ES version. ([3a91e91](https://github.com/ethers-io/ethers.js/commit/3a91e91df56c1ef6cf096c0322f74fd5060891e0))
|
||||
- Major overhaul in compilation to enable ES6 module generation. ([73a0077](https://github.com/ethers-io/ethers.js/commit/73a0077fd38c6ae79f33a9d4d3cc128a904b4a6c))
|
||||
- Updated some of the flatworm docs. ([81fd942](https://github.com/ethers-io/ethers.js/commit/81fd9428cab4be7eee7ddeb564bf91f282cae475))
|
||||
- Fixed package descriptions. ([#561](https://github.com/ethers-io/ethers.js/issues/561); [ebfca98](https://github.com/ethers-io/ethers.js/commit/ebfca98dc276d6f6ca6961632635e8203bb17645))
|
||||
|
||||
ethers/v5.0.0-beta.155 (2019-08-22 17:11)
|
||||
-----------------------------------------
|
||||
|
||||
- Added Wrapped Ether and Token transfers to CLI. ([c031a13](https://github.com/ethers-io/ethers.js/commit/c031a1336815923bae85d9982dba0985a79cfaed))
|
||||
- Fixed sendTransaction and use median gas price in FallbackProvider. ([07e1599](https://github.com/ethers-io/ethers.js/commit/07e15993ba181cfbff987778d158dbde6bb84de2))
|
||||
- Port optional Secret Storage wallet address to v5. ([#582](https://github.com/ethers-io/ethers.js/issues/582); [a12d60d](https://github.com/ethers-io/ethers.js/commit/a12d60d722dfcf998a2e06eba5e46390d7d442e5))
|
||||
- Updated flatworm docs output. ([8745a81](https://github.com/ethers-io/ethers.js/commit/8745a81b11b710036ddb546308c13958be1affb9))
|
||||
- Added initial flatworm documentation stubs. ([0333a76](https://github.com/ethers-io/ethers.js/commit/0333a76f4ff382b5b59b24c672b702721e7a386a))
|
||||
|
||||
ethers/v5.0.0-beta.154 (2019-08-21 01:51)
|
||||
-----------------------------------------
|
||||
|
||||
- Use safe transfer for ENS in CLI. ([b7494d8](https://github.com/ethers-io/ethers.js/commit/b7494d8618001797a4e856f3d1886273897e6ba4))
|
||||
- Fixed quorum-matching logic for FallbackProvider. ([b304ec1](https://github.com/ethers-io/ethers.js/commit/b304ec1f008ec5301c0dbd1a493d790fe3528512))
|
||||
- Added CloudflareProvider. ([#587](https://github.com/ethers-io/ethers.js/issues/587); [621313d](https://github.com/ethers-io/ethers.js/commit/621313d2a697bc6e1dd25eb5b08d67e832a28d05))
|
||||
- Added receipt to CALL_EXCEPTION errors. ([724c32e](https://github.com/ethers-io/ethers.js/commit/724c32e8c08b55404594f263e52babb0550a15b8))
|
||||
|
||||
ethers/v5.0.0-beta.153 (2019-08-06 19:15)
|
||||
-----------------------------------------
|
||||
|
||||
- Updated gas estimate failure messaging to include that the tx may simple be causing a revert. ([edb26b1](https://github.com/ethers-io/ethers.js/commit/edb26b16354afd707e5d03e174c4cc809b951c4f))
|
||||
- Additional sanity checks in ethers-ens. ([de4b2a4](https://github.com/ethers-io/ethers.js/commit/de4b2a449ca3a49807c8bedb3e21e8e8d71e63fc))
|
||||
- Fix bug in --wait for CLI. ([9977c9f](https://github.com/ethers-io/ethers.js/commit/9977c9f66a7007dcc1963128c88c584b6b6c064b))
|
||||
- Added content-hash support to ENS CLI. ([7dfef46](https://github.com/ethers-io/ethers.js/commit/7dfef463f83a9190d1b89cf81e0fb692da3dd813))
|
||||
|
||||
ethers/v5.0.0-beta.152 (2019-08-05 14:37)
|
||||
-----------------------------------------
|
||||
|
||||
- Using CLI --wait instead of custom Plugin flag for ethers-ens. ([19ee2b5](https://github.com/ethers-io/ethers.js/commit/19ee2b516005b2c35b846f19457ec9bbfa0c283b))
|
||||
- Added --wait as a general flag to CLI. ([7640292](https://github.com/ethers-io/ethers.js/commit/7640292ac8b7b9e6de3ad6699d23e2debf26cc1b))
|
||||
- Added migrate-registrar and transfer to ENS CLI. ([31e8e1b](https://github.com/ethers-io/ethers.js/commit/31e8e1b0520bc8be390fbf7e2b473c36a8649eb3))
|
||||
- Include data in the CLI transaction dump. ([53bd96a](https://github.com/ethers-io/ethers.js/commit/53bd96a9f675233906033290f1e0c71ca4e9d389))
|
||||
- Better errors on gas estimation failure. ([0e6b810](https://github.com/ethers-io/ethers.js/commit/0e6b810def390309240508a99b2cf0736848dedd))
|
||||
|
||||
ethers/v5.0.0-beta.151 (2019-08-05 14:29)
|
||||
-----------------------------------------
|
||||
|
||||
- Added package name prefix to all _version for Logger. ([692589d](https://github.com/ethers-io/ethers.js/commit/692589db54cbca10a2a453e9a1801a8612056559))
|
||||
|
||||
ethers/v5.0.0-beta.150 (2019-08-03 01:07)
|
||||
-----------------------------------------
|
||||
|
||||
- Fixed old references to errors package. ([1cabce7](https://github.com/ethers-io/ethers.js/commit/1cabce7e1c23b15cc2b630c0b403dd72d815a5ba))
|
||||
- Added generation scripts for Table A.1 for stringprep. ([#42](https://github.com/ethers-io/ethers.js/issues/42); [b21681a](https://github.com/ethers-io/ethers.js/commit/b21681a7f4292b0e77315caad3a59fe814e9292b))
|
||||
|
||||
ethers/v5.0.0-beta.149 (2019-08-03 00:45)
|
||||
-----------------------------------------
|
||||
|
||||
- Fixed some case-folding and added Table A.1 for IDNA. ([#42](https://github.com/ethers-io/ethers.js/issues/42); [f955dca](https://github.com/ethers-io/ethers.js/commit/f955dca417a6f86690cf33a81b08baa99e1b1a5c))
|
||||
- Removed references to legacy errors pacakge and updated umbrella pacakge. ([c09de16](https://github.com/ethers-io/ethers.js/commit/c09de163473c361cac11ddef9ec852f4cbb7d8e3))
|
||||
- Updated admin module to use new fetchJson. ([226c100](https://github.com/ethers-io/ethers.js/commit/226c100c72c3fcb0c0e3b62be5f579fd9cc4c904))
|
||||
- Updated dist files. ([8354c3f](https://github.com/ethers-io/ethers.js/commit/8354c3f9fe5487f21acaaeccd4450d9a5d495bc1))
|
||||
- Full case-folding for IDNA in namehash. ([0af95f4](https://github.com/ethers-io/ethers.js/commit/0af95f4a655106e67c2ba8f445af88c9e9e24339))
|
||||
- Deprecating errors for logger. ([0b224e8](https://github.com/ethers-io/ethers.js/commit/0b224e8fb5811cd06727063c909ca1e1e5cde57e))
|
||||
- More consistent debug events for Providers. ([e8f28b5](https://github.com/ethers-io/ethers.js/commit/e8f28b55d7dd62e29f03628232ffe7c75dc811b5))
|
||||
|
||||
ethers/v5.0.0-beta.148 (2019-07-27 18:56)
|
||||
-----------------------------------------
|
||||
|
||||
- Initial drop of new ENS CLI tool. ([c3c65b2](https://github.com/ethers-io/ethers.js/commit/c3c65b2fa19e117d6433c2e0b3d20decfe506c74))
|
||||
- Added TypeScript tool support for functions with multiple outputs. ([6de4a5d](https://github.com/ethers-io/ethers.js/commit/6de4a5d8a9d114c4c33c58f8a304b60e7370eeff))
|
||||
- Added CLI support for stand-alone (no sub-command) tools. ([b67b121](https://github.com/ethers-io/ethers.js/commit/b67b12123996f1aaf7cbe3c8648fd85a22d6674e))
|
||||
- Make utils.resolveProperties preserve object parameter order. ([74dbc28](https://github.com/ethers-io/ethers.js/commit/74dbc281ede042c5eeaa7b45150b215dea860a88))
|
||||
- Added initial IDNA support for full UTF-8 support in namehash. ([#42](https://github.com/ethers-io/ethers.js/issues/42); [28eb38e](https://github.com/ethers-io/ethers.js/commit/28eb38ee703288aaad9f730b2d93fe3aeea7ada6))
|
||||
|
||||
ethers/v5.0.0-beta.147 (2019-07-23 01:04)
|
||||
-----------------------------------------
|
||||
|
||||
- Use the CLI solc instead of solc directly for ABI testcase generation. ([99c7b1c](https://github.com/ethers-io/ethers.js/commit/99c7b1ca94382490b9757fd51375a7ad4259b831))
|
||||
- Added experimental UTF-8 functions for escaping non-ascii strings. ([b132e32](https://github.com/ethers-io/ethers.js/commit/b132e32172c9d63e59209628dadd5796dd6291c8))
|
||||
- Bump Solidity version in CLI to 0.5.10. ([6005248](https://github.com/ethers-io/ethers.js/commit/600524842e1a4b857e8428a45c0c7d1baa0624ee))
|
||||
|
||||
ethers/v5.0.0-beta.146 (2019-07-20 21:06)
|
||||
-----------------------------------------
|
||||
|
||||
- Keep extra filter topics when using Frgment filters in Contracts. ([efaafb2](https://github.com/ethers-io/ethers.js/commit/efaafb203feaf703de803df7e346652372e9fb75))
|
||||
- Updated package.json description for Contract package. ([#561](https://github.com/ethers-io/ethers.js/issues/561); [d88ee45](https://github.com/ethers-io/ethers.js/commit/d88ee45937b3484b68f72e3f72ad6c29556c984b))
|
||||
|
||||
ethers/v5.0.0-beta.145 (2019-07-20 20:12)
|
||||
-----------------------------------------
|
||||
|
||||
- Export provider.Formatter. ([#562](https://github.com/ethers-io/ethers.js/issues/562); [083fd76](https://github.com/ethers-io/ethers.js/commit/083fd76a3a638ec16d5f9bf652101e5a150c7347))
|
||||
- Update CLI to use new Fragment.format style. ([9a41199](https://github.com/ethers-io/ethers.js/commit/9a4119910b07d1ad61bafafb38ac18a9dae1d9ed))
|
||||
- Added FormatTypes to utils. ([a05027c](https://github.com/ethers-io/ethers.js/commit/a05027c744102bbe1be5e13dd89b9c1e64b3b526))
|
||||
- Added experimental memory-hard password scheme for password-protected mnemonics to the CLI. ([5877418](https://github.com/ethers-io/ethers.js/commit/5877418de94256a69fdf2ad466ba579309b9dee8))
|
||||
- Added more flexible output options to fragment.format (JSON and minimal) and better JSON object parsing. ([e9558c8](https://github.com/ethers-io/ethers.js/commit/e9558c8d4fe6df889f4d7ba6ac6448aa543ef99d))
|
||||
|
||||
ethers/v5.0.0-beta.144 (2019-07-09 17:28)
|
||||
-----------------------------------------
|
||||
|
||||
- Make mnemonic phrases case agnostic. ([#557](https://github.com/ethers-io/ethers.js/issues/557); [e4423b7](https://github.com/ethers-io/ethers.js/commit/e4423b7a277e7e1be1c02d345d4ab1eab484c9b8))
|
||||
|
||||
ethers/v5.0.0-beta.143 (2019-07-02 16:12)
|
||||
-----------------------------------------
|
||||
|
||||
- Adding more support for offline signing in the CLI. ([9cc269c](https://github.com/ethers-io/ethers.js/commit/9cc269ceb5d33b2d88542d4bc6771279f729e733))
|
||||
- Allow providers to prepare their Network object. ([6484908](https://github.com/ethers-io/ethers.js/commit/6484908cb25dd35e5d98b2672dca72ed3f30cbe1))
|
||||
- Export BIP-44 default path in ethers.utils. ([04bdf45](https://github.com/ethers-io/ethers.js/commit/04bdf456eb07aa72872265e0ee01e3231d2b6cf1))
|
||||
|
||||
ethers/v5.0.0-beta.142 (2019-06-28 16:13)
|
||||
-----------------------------------------
|
||||
|
||||
- Do not require a Signer for contract.populateTransaction. ([0e78386](https://github.com/ethers-io/ethers.js/commit/0e78386a08d3d3a0a98c8d03cd665b8992ab3ea2))
|
||||
- Bumping version of solc to 0.5.9. ([e2da447](https://github.com/ethers-io/ethers.js/commit/e2da447c7bc05937966bc4909c47291e4819d2a9))
|
||||
|
||||
ethers/v5.0.0-beta.141 (2019-06-24 21:25)
|
||||
-----------------------------------------
|
||||
|
||||
- Fix non-ES6 import in keccak256. ([5eb393d](https://github.com/ethers-io/ethers.js/commit/5eb393d828328b34567566d3c0d622b4aef1e202))
|
||||
- Refactored wordlist exports to export Wordlist directly. ([746d255](https://github.com/ethers-io/ethers.js/commit/746d255b741844b615583b2de3ffd07631b4e872))
|
||||
|
||||
ethers/v5.0.0-beta.140 (2019-06-12 01:25)
|
||||
-----------------------------------------
|
||||
|
||||
- Move from node-fetch to cross-fetch; better browser fallback implementation. ([826ffbc](https://github.com/ethers-io/ethers.js/commit/826ffbc7c4ed1c301f30e6f264eedeaf3c243ca8))
|
||||
- Added getStatic with support for inheritance of static methods. ([5e4535e](https://github.com/ethers-io/ethers.js/commit/5e4535e939fdb9d9d23bd14b3e2590873d3eb508))
|
||||
- Fixed node-fetch for Safari (todo: push this fix upstream to node-fetch). ([7164e51](https://github.com/ethers-io/ethers.js/commit/7164e51131215ae3201b49f8c7f5ade8cbd8a420))
|
||||
- Migrated XMLHttpRequest to fetch API. ([#506](https://github.com/ethers-io/ethers.js/issues/506); [62201c5](https://github.com/ethers-io/ethers.js/commit/62201c5eebc52e9723dbbb2cc64823155ce1e0f9))
|
||||
|
||||
ethers/v5.0.0-beta.139 (2019-06-11 17:55)
|
||||
-----------------------------------------
|
||||
|
||||
- Removed freeze option from deepCopy; all properties are read-only and only objects may have new properties added. ([1bc792d](https://github.com/ethers-io/ethers.js/commit/1bc792d9dcc6a06a1be4fc5e5b9a538a3f6b7ada))
|
||||
- Moved away from isNamedInstance which breaks after Browserify name mangling. ([257d67c](https://github.com/ethers-io/ethers.js/commit/257d67c9625fa237bcfb3d651c49aa3b79175cae))
|
||||
- Expose poll function in utils. ([#512](https://github.com/ethers-io/ethers.js/issues/512); [e6f6383](https://github.com/ethers-io/ethers.js/commit/e6f6383346818fa67423f1f20450e011242eb554))
|
||||
- Make TransactionResponse hash required. ([#537](https://github.com/ethers-io/ethers.js/issues/537); [095c1fe](https://github.com/ethers-io/ethers.js/commit/095c1fe579068a3204ea0d1bc1893f293f61e719))
|
||||
|
||||
ethers/v5.0.0-beta.138 (2019-06-04 16:05)
|
||||
-----------------------------------------
|
||||
|
||||
- Fixed INFURA project ID checking. ([#534](https://github.com/ethers-io/ethers.js/issues/534); [5bf763f](https://github.com/ethers-io/ethers.js/commit/5bf763fe2307e8570ab5e91e30c43e2e5731fc39))
|
||||
|
||||
ethers/v5.0.0-beta.137 (2019-06-01 14:06)
|
||||
-----------------------------------------
|
||||
|
||||
- Fixed invalid arrayify value in browser for SHA2-HMAC. ([#530](https://github.com/ethers-io/ethers.js/issues/530); [c4a494b](https://github.com/ethers-io/ethers.js/commit/c4a494b528f2e5f706c159d916d8ff0ffd96a211))
|
||||
- Fix event and function fragment formatting. ([a2d4b29](https://github.com/ethers-io/ethers.js/commit/a2d4b2907184d9480a72fe6f67652489074af86e))
|
||||
- Fixed default JsonRpcSigner. ([#532](https://github.com/ethers-io/ethers.js/issues/532); [5ba6a61](https://github.com/ethers-io/ethers.js/commit/5ba6a616a6f969b1f28f8c6367c21488f497a7ae))
|
||||
- Added changelog management to update-versions. ([4a3f719](https://github.com/ethers-io/ethers.js/commit/4a3f7190dc04275030d313289e1ba6a2b31407ec))
|
||||
|
||||
ethers/v5.0.0-beta.136
|
||||
----------------------
|
||||
|
||||
- Added queryFilter to Contracts. ([#463](https://github.com/ethers-io/ethers.js/issues/463); [eea53bb](https://github.com/ethers-io/ethers.js/commit/eea53bb1be29ad2bd1b229a13c85b12be264b019))
|
||||
- Allow storage class in Human-Readable ABI. ([#476](https://github.com/ethers-io/ethers.js/issues/476); [cf39adb](https://github.com/ethers-io/ethers.js/commit/cf39adb09020ca0393e028b330bfd07fb4869236))
|
||||
- Track per-provider JSON-RPC ID in JsonRpcProvider. ([#337](https://github.com/ethers-io/ethers.js/issues/337), [#489](https://github.com/ethers-io/ethers.js/issues/489); [044554b](https://github.com/ethers-io/ethers.js/commit/044554b58525d1677646a74119f86ea867a06d1e))
|
||||
- Fixed typo in error message. ([#470](https://github.com/ethers-io/ethers.js/issues/470); [47d92ae](https://github.com/ethers-io/ethers.js/commit/47d92aeff02cacfb26793850c7faef7cb21ce4cf))
|
||||
|
||||
ethers/v5.0.0-beta.135
|
||||
----------------------
|
||||
|
||||
- Better error message for unconfigured ENS names. ([#504](https://github.com/ethers-io/ethers.js/issues/504); [3cbc4b4](https://github.com/ethers-io/ethers.js/commit/3cbc4b462262ba61fa7d99a7a12e7bbf8049afb1))
|
||||
- Fixed contract events. ([#404](https://github.com/ethers-io/ethers.js/issues/404); [8cdda37](https://github.com/ethers-io/ethers.js/commit/8cdda37095df28f828ccd2ac5437ccb6541b16cc))
|
||||
- Updated license for BaseX to include original authors; was only included in the source. ([03c9725](https://github.com/ethers-io/ethers.js/commit/03c97259c46de10dbe6ce62921de2f32ffff0522))
|
||||
|
||||
@ -1,7 +0,0 @@
|
||||
{
|
||||
"drips": {
|
||||
"ethereum": {
|
||||
"ownedBy": "0x89EdE5cBE53473A64d6C8DF14176a0d658dAAeDC"
|
||||
}
|
||||
}
|
||||
}
|
||||
@ -1,6 +1,6 @@
|
||||
MIT License
|
||||
|
||||
Copyright (c) 2016-2023 Richard Moore
|
||||
Copyright (c) 2019 Richard Moore
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||
of this software and associated documentation files (the "Software"), to deal
|
||||
|
||||
118
README.md
118
README.md
@ -2,79 +2,57 @@ The Ethers Project
|
||||
==================
|
||||
|
||||
[](https://www.npmjs.com/package/ethers)
|
||||
[](https://github.com/ethers-io/ethers.js/actions/workflows/test-ci.yml)
|
||||
|
||||
|
||||
[](https://www.gitpoap.io/gh/ethers-io/ethers.js)
|
||||
[](https://twitter.com/ricmoo)
|
||||
[](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).
|
||||
|
||||
A complete, compact and simple library for Ethereum and ilk, written
|
||||
in [TypeScript](https://www.typescriptlang.org).
|
||||
|
||||
**Features**
|
||||
**Features:**
|
||||
|
||||
- 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), [Ankr](https://ankr.com) or [MetaMask](https://metamask.io)
|
||||
- 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
|
||||
- **Small** (~144kb compressed; 460kb uncompressed)
|
||||
- **Tree-shaking** focused; include only what you need during bundling
|
||||
- **Tiny** (~104kb compressed; 322kb uncompressed)
|
||||
- **Modular** packages; include only what you need
|
||||
- **Complete** functionality for all your Ethereum desires
|
||||
- Extensive [documentation](https://docs.ethers.org/v6/)
|
||||
- Extensive [documentation](https://docs.ethers.io/v5/)
|
||||
- Large collection of **test cases** which are maintained and added to
|
||||
- Fully written in **TypeScript**, with strict types for security and safety
|
||||
- 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 advisories and important notices, follow [@ethersproject](https://twitter.com/ethersproject)
|
||||
For the latest news and advisories, please follow the [@ethersproject](https://twitter.com/ethersproject)
|
||||
on Twitter (low-traffic, non-marketing, important information only) as well as watch this GitHub project.
|
||||
|
||||
For more general news, discussions, and feedback, follow or DM me,
|
||||
[@ricmoo](https://twitter.com/ricmoo) on Twitter or on the
|
||||
[Ethers Discord](https://discord.gg/qYtSscGYYc).
|
||||
|
||||
|
||||
For the latest changes, see the
|
||||
[CHANGELOG](https://github.com/ethers-io/ethers.js/blob/main/CHANGELOG.md).
|
||||
|
||||
|
||||
**Summaries**
|
||||
|
||||
- [August 2023](https://blog.ricmoo.com/highlights-ethers-js-august-2023-fb68354c576c)
|
||||
- [September 2022](https://blog.ricmoo.com/highlights-ethers-js-september-2022-d7bda0fc37ed)
|
||||
- [June 2022](https://blog.ricmoo.com/highlights-ethers-js-june-2022-f5328932e35d)
|
||||
- [March 2022](https://blog.ricmoo.com/highlights-ethers-js-march-2022-f511fe1e88a1)
|
||||
- [December 2021](https://blog.ricmoo.com/highlights-ethers-js-december-2021-dc1adb779d1a)
|
||||
- [September 2021](https://blog.ricmoo.com/highlights-ethers-js-september-2021-1bf7cb47d348)
|
||||
- [May 2021](https://blog.ricmoo.com/highlights-ethers-js-may-2021-2826e858277d)
|
||||
- [March 2021](https://blog.ricmoo.com/highlights-ethers-js-march-2021-173d3a545b8d)
|
||||
- [December 2020](https://blog.ricmoo.com/highlights-ethers-js-december-2020-2e2db8bc800a)
|
||||
|
||||
For the latest changes, see the [CHANGELOG](https://github.com/ethers-io/ethers.js/blob/master/CHANGELOG.md).
|
||||
|
||||
|
||||
Installing
|
||||
----------
|
||||
|
||||
**NodeJS**
|
||||
**node.js**
|
||||
|
||||
```
|
||||
/home/ricmoo/some_project> npm install ethers
|
||||
/home/ricmoo/some_project> npm install --save ethers
|
||||
```
|
||||
|
||||
**Browser (ESM)**
|
||||
**browser (UMD)**
|
||||
|
||||
The bundled library is available in the `./dist/` folder in this repo.
|
||||
```
|
||||
<script src="https://cdn.ethers.io/lib/ethers-5.1.umd.min.js" type="text/javascript">
|
||||
</script>
|
||||
```
|
||||
|
||||
**browser (ESM)**
|
||||
|
||||
```
|
||||
<script type="module">
|
||||
import { ethers } from "./dist/ethers.min.js";
|
||||
import { ethers } from "https://cdn.ethers.io/lib/ethers-5.1.esm.min.js";
|
||||
</script>
|
||||
```
|
||||
|
||||
@ -82,55 +60,29 @@ The bundled library is available in the `./dist/` folder in this repo.
|
||||
Documentation
|
||||
-------------
|
||||
|
||||
Browse the [documentation](https://docs.ethers.org) online:
|
||||
Browse the [documentation](https://docs.ethers.io/v5/) online:
|
||||
|
||||
- [Getting Started](https://docs.ethers.org/v6/getting-started/)
|
||||
- [Full API Documentation](https://docs.ethers.org/v6/api/)
|
||||
- [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 browse the entire documentation as a [single page](https://docs.ethers.io/v5/single-page/) to make searching easier.
|
||||
|
||||
|
||||
Providers
|
||||
---------
|
||||
|
||||
Ethers works closely with an ever-growing list of third-party providers
|
||||
to ensure getting started is quick and easy, by providing default keys
|
||||
to each service.
|
||||
|
||||
These built-in keys mean you can use `ethers.getDefaultProvider()` and
|
||||
start developing right away.
|
||||
|
||||
However, the API keys provided to ethers are also shared and are
|
||||
intentionally throttled to encourage developers to eventually get
|
||||
their own keys, which unlock many other features, such as faster
|
||||
responses, more capacity, analytics and other features like archival
|
||||
data.
|
||||
|
||||
When you are ready to sign up and start using for your own keys, please
|
||||
check out the [Provider API Keys](https://docs.ethers.org/v5/api-keys/) in
|
||||
the documentation.
|
||||
|
||||
A special thanks to these services for providing community resources:
|
||||
|
||||
- [Ankr](https://www.ankr.com/)
|
||||
- [QuickNode](https://www.quicknode.com/)
|
||||
- [Etherscan](https://etherscan.io/)
|
||||
- [INFURA](https://infura.io/)
|
||||
- [Alchemy](https://dashboard.alchemyapi.io/signup?referral=55a35117-028e-4b7c-9e47-e275ad0acc6d)
|
||||
|
||||
|
||||
Extension Packages
|
||||
Ancillary Packages
|
||||
------------------
|
||||
|
||||
The `ethers` package only includes the most common and most core
|
||||
functionality to interact with Ethereum. There are many other
|
||||
packages designed to further enhance the functionality and experience.
|
||||
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 packages, which can be included by those who need them, while not bloating
|
||||
everyone else with packages they do not need.
|
||||
|
||||
- [MulticallProvider](https://github.com/ethers-io/ext-provider-multicall) - A Provider which bundles multiple call requests into a single `call` to reduce latency and backend request capacity
|
||||
- [MulticoinPlugin](https://github.com/ethers-io/ext-provider-plugin-multicoin) - A Provider plugin to expand the support of ENS coin types
|
||||
- [GanaceProvider](https://github.com/ethers-io/ext-provider-ganache) - A Provider for in-memory node instances, for fast debugging, testing and simulating blockchain operations
|
||||
- [Optimism Utilities](https://github.com/ethers-io/ext-utils-optimism) - A collection of Optimism utilities
|
||||
- [LedgerSigner](https://github.com/ethers-io/ext-signer-ledger) - A Signer to interact directly with Ledger Hardware Wallets
|
||||
We will keep a list of useful packages here.
|
||||
|
||||
- `@ethersproject/experimental` ([documentation](https://docs.ethers.io/v5/api/experimental/))
|
||||
- `@ethersproject/cli` ([documentation](https://docs.ethers.io/v5/cli/))
|
||||
- `@ethersproject/hardware-wallets` ([documentation](https://docs.ethers.io/v5/api/other/hardware/))
|
||||
|
||||
|
||||
License
|
||||
|
||||
@ -10,9 +10,8 @@ please [contact me](mailto:github@ricmoo.com).
|
||||
|
||||
| Version | Supported | Initial Release |
|
||||
| ------- | ------------------------------------------ | ----------------- |
|
||||
| 6.0.x | :white_check_mark: | 2023-02-02 |
|
||||
| 5.0.x | :white_check_mark: (security updates) | 2020-06-12 |
|
||||
| 4.0.x | :x: | 2018-10-01 |
|
||||
| 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 |
|
||||
|
||||
22
dist/README.md
vendored
22
dist/README.md
vendored
@ -1,22 +0,0 @@
|
||||
Distribution Folder
|
||||
===================
|
||||
|
||||
The contents of this folder are for using `import` in ESM
|
||||
browser-base projects.
|
||||
|
||||
The `ethers.js` (and `ethers.min.js`) files only include the
|
||||
English wordlist to conserve space.
|
||||
|
||||
For additional Wordlist support, the `wordlist-extra.js` (and
|
||||
`wordlist-extra.min.js`) should be imported too.
|
||||
|
||||
|
||||
Notes
|
||||
-----
|
||||
|
||||
The contents are generated via the `npm build dist` target using
|
||||
`rollup` and the `/rollup.config.js` configuration.
|
||||
|
||||
Do not modify the files in this folder. They are deleted on `build-clean`.
|
||||
|
||||
To modify this `README.md`, see the `/output/post-build/dist`.
|
||||
25628
dist/ethers.js
vendored
25628
dist/ethers.js
vendored
File diff suppressed because one or more lines are too long
1
dist/ethers.js.map
vendored
1
dist/ethers.js.map
vendored
File diff suppressed because one or more lines are too long
1
dist/ethers.min.js
vendored
1
dist/ethers.min.js
vendored
File diff suppressed because one or more lines are too long
25825
dist/ethers.umd.js
vendored
25825
dist/ethers.umd.js
vendored
File diff suppressed because one or more lines are too long
1
dist/ethers.umd.js.map
vendored
1
dist/ethers.umd.js.map
vendored
File diff suppressed because one or more lines are too long
1
dist/ethers.umd.min.js
vendored
1
dist/ethers.umd.min.js
vendored
File diff suppressed because one or more lines are too long
1540
dist/wordlists-extra.js
vendored
1540
dist/wordlists-extra.js
vendored
File diff suppressed because one or more lines are too long
1
dist/wordlists-extra.js.map
vendored
1
dist/wordlists-extra.js.map
vendored
File diff suppressed because one or more lines are too long
1
dist/wordlists-extra.min.js
vendored
1
dist/wordlists-extra.min.js
vendored
File diff suppressed because one or more lines are too long
1
docs.wrm/.gitignore
vendored
Normal file
1
docs.wrm/.gitignore
vendored
Normal file
@ -0,0 +1 @@
|
||||
**.bak
|
||||
@ -1,5 +1,23 @@
|
||||
Documentation Source
|
||||
====================
|
||||
Documentation
|
||||
=============
|
||||
|
||||
This folder contains all the Flatworm source for the documentation.
|
||||
These docs are built using [Flatworm Docs](https://github.com/ricmoo/flatworm).
|
||||
|
||||
The output is placed in [docs](../docs) and generates both HTML and Markdown
|
||||
files.
|
||||
|
||||
|
||||
Building
|
||||
--------
|
||||
|
||||
```
|
||||
/home/ricmoo/ethers.js> npm run build-docs
|
||||
```
|
||||
|
||||
|
||||
License
|
||||
-------
|
||||
|
||||
All documentation for ethers.js and Flatworm is released under the
|
||||
[Creative Commons Attribution 4.0 International License](https://choosealicense.com/licenses/cc-by-4.0/)
|
||||
license.
|
||||
|
||||
126
docs.wrm/api-keys.wrm
Normal file
126
docs.wrm/api-keys.wrm
Normal file
@ -0,0 +1,126 @@
|
||||
_section: Provider API Keys @<api-keys>
|
||||
|
||||
//( **TL; DR** – sign up for your own API keys with the links below to improve your application performance )//
|
||||
|
||||
When using a [[Provider]] backed by an API service (such as [[link-alchemy]],
|
||||
[[link-etherscan]] or [[link-infura]]), the service requires an API key,
|
||||
which allows each service to track individual projects and their usage and
|
||||
permissions.
|
||||
|
||||
The ethers library offers default API keys for each service, so that each
|
||||
[[Provider]] works out-of-the-box.
|
||||
|
||||
These API keys are provided as a community resource by the backend services
|
||||
for low-traffic projects and for early prototyping.
|
||||
|
||||
Since these API keys are shared by all users (that have not acquired their
|
||||
own API key), they are aggressively throttled which means retries occur more
|
||||
frequently and the responses are slower.
|
||||
|
||||
It is **highly recommended** that you sign up for a free API key from each service for their
|
||||
free tier, which (depending on the service) includes many advantages:
|
||||
|
||||
- a much **higher request rate** and concurrent request limit
|
||||
- **faster** responses with fewer retries and timeouts
|
||||
- useful **metric tracking** for performance tuning and to analyze your customer behaviour
|
||||
- more **advanced APIs**, such as archive data or advanced log queries
|
||||
|
||||
_subsection: Etherscan @<api-keys--etherscan>
|
||||
|
||||
Etherscan is an Ethereum block explorer, which is possibly the most useful
|
||||
developer tool for building and debugging Ethereum applications.
|
||||
|
||||
They offer an extensive collection of API endpoints which provide all the
|
||||
operations required to interact with the Ethereum Blockchain.
|
||||
|
||||
[Sign up for a free API key on Etherscan](link-etherscan-signup)
|
||||
|
||||
**Benefits:**
|
||||
|
||||
- higher rate limit (since you are not using the [shared rate limit](link-etherscan-ratelimit))
|
||||
- customer usage metrics
|
||||
|
||||
_subsection: INFURA @<api-keys--infura>
|
||||
|
||||
The INFURA service has been around for quite some time and is very robust
|
||||
and reliable and highly recommended.
|
||||
|
||||
They offer a standard JSON-RPC interface and a WebSocket interface, which makes
|
||||
interaction with standard tools versatile, simple and straight forward.
|
||||
|
||||
[Sign up for a free Project ID on INFURA](link-infura-signup)
|
||||
|
||||
**Benefits:**
|
||||
|
||||
- higher rate limit
|
||||
- customer usage metrics
|
||||
- access to archive data (requires paid upgrade)
|
||||
|
||||
_subsection: Alchemy @<api-keys--alchemy>
|
||||
|
||||
The Alchemy service has been around a few years and is also very robust
|
||||
and reliable.
|
||||
|
||||
They offer a standard JSON-RPC interface and a WebSocket interface, as well
|
||||
as a collection of advanced APIs for interacting with tokens and to assist
|
||||
with debugging.
|
||||
|
||||
[Sign up for a free API key on Alchemy](link-alchemy-signup)
|
||||
|
||||
**Benefits:**
|
||||
|
||||
- higher rate limit
|
||||
- customer usage metrics
|
||||
- access to advanced token balance and metadata APIs
|
||||
- access to advanced debugging trace and revert reason APIs
|
||||
|
||||
_subsection: Pocket Gateway@<api-keys--pocket-gateway>
|
||||
|
||||
|
||||
[Sign up for a free API key on Pocket](link-pocket-signup)
|
||||
|
||||
**Benefits:**
|
||||
|
||||
- customer usage metrics
|
||||
- decentralized Access to Blockchain Infrastructure
|
||||
- Stake as opposed to paying a monthly fee
|
||||
- Highly redundant global set of nodes incentivized by cryptoeconomic incentives
|
||||
|
||||
|
||||
_subsection: Creating a Default Provider @<api-keys--getDefaultProvider>
|
||||
|
||||
The [default provider](providers-getDefaultProvider) connects to multiple
|
||||
backends and verifies their results internally, making it simple to have
|
||||
a high level of trust in third-party services.
|
||||
|
||||
A second optional parameter allows API keys to be specified to each
|
||||
Provider created internally and any API key omitted will fallback onto
|
||||
using the default API key for that service.
|
||||
|
||||
It is **highly recommended** that you provide an API for each service, to
|
||||
maximize your applications performance.
|
||||
|
||||
_code: Passing API Keys into getDefaultProvider @lang<script>
|
||||
|
||||
// Use the mainnet
|
||||
const network = "homestead";
|
||||
|
||||
// Specify your own API keys
|
||||
// Each is optional, and if you omit it the default
|
||||
// API key for that service will be used.
|
||||
const provider = ethers.getDefaultProvider(network, {
|
||||
etherscan: YOUR_ETHERSCAN_API_KEY,
|
||||
infura: YOUR_INFURA_PROJECT_ID,
|
||||
// Or if using a project secret:
|
||||
// infura: {
|
||||
// projectId: YOUR_INFURA_PROJECT_ID,
|
||||
// projectSecret: YOUR_INFURA_PROJECT_SECRET,
|
||||
// },
|
||||
alchemy: YOUR_ALCHEMY_API_KEY,
|
||||
pocket: YOUR_POCKET_APPLICATION_KEY
|
||||
// Or if using an application secret key:
|
||||
// pocket: {
|
||||
// applicationId: ,
|
||||
// applicationSecretKey:
|
||||
// }
|
||||
});
|
||||
119
docs.wrm/api/contract/contract-factory.wrm
Normal file
119
docs.wrm/api/contract/contract-factory.wrm
Normal file
@ -0,0 +1,119 @@
|
||||
_section: ContractFactory @<ContractFactory> @SRC<contracts:class.ContractFactory>
|
||||
|
||||
To deploy a [[Contract]], additional information is needed
|
||||
that is not available on a Contract object itself.
|
||||
|
||||
Mainly, the bytecode (more specifically the initcode) of a contract is required.
|
||||
|
||||
The **Contract Factory** sends a special type of transaction, an initcode
|
||||
transaction (i.e. the ``to`` field is null, and the ``data`` field is the
|
||||
initcode) where the initcode will be evaluated and the result becomes the
|
||||
new code to be deployed as a new contract.
|
||||
|
||||
_subsection: Creating Instances @<ContractFactory--creating>
|
||||
|
||||
_property: new ethers.ContractFactory(interface, bytecode [ , signer ]) @SRC<contracts:constructor.ContractFactory>
|
||||
|
||||
Creates a new instance of a **ContractFactory** for the contract described
|
||||
by the //interface// and //bytecode// initcode.
|
||||
|
||||
_property: ContractFactory.fromSolidity(compilerOutput [ , signer ]) => [[ContractFactory]]
|
||||
|
||||
Consumes the output of the Solidity compiler, extracting the ABI
|
||||
and bytecode from it, allowing for the various formats the solc
|
||||
compiler has emitted over its life.
|
||||
|
||||
_property: contractFactory.connect(signer) => [[Contract]] @<ContractFactory-connect>
|
||||
|
||||
Returns a **new instance** of the ContractFactory with the same //interface//
|
||||
and //bytecode//, but with a different //signer//.
|
||||
|
||||
_subsection: Properties @<ContractFactory--properties>
|
||||
|
||||
_property: contractFactory.interface => [[Interface]]
|
||||
|
||||
The [[Contract]] interface.
|
||||
|
||||
_property: contractFactory.bytecode => string<[[DataHexString]]>
|
||||
|
||||
The bytecode (i.e. initcode) that this **ContractFactory** will
|
||||
use to deploy the Contract.
|
||||
|
||||
_property: contractFactory.signer => [[Signer]]
|
||||
|
||||
The [[Signer]] (if any) this ContractFactory will use to deploy instances
|
||||
of the Contract to the Blockchain.
|
||||
|
||||
|
||||
_subsection: Methods @<ContractFactory--methods>
|
||||
|
||||
_property: contractFactory.attach(address) => [[Contract]] @<ContractFactory-attach>
|
||||
|
||||
Return an instance of a [[Contract]] attached to //address//. This is the
|
||||
same as using the [Contract constructor](Contract--creating) with
|
||||
//address// and this the //interface// and //signerOrProvider// passed
|
||||
in when creating the ContractFactory.
|
||||
|
||||
_property: contractFactory.getDeployTransaction(...args [ , overrides ]) => [[UnsignedTransaction]]
|
||||
|
||||
Returns the unsigned transaction which would deploy this Contract with //args// passed
|
||||
to the Contract's constructor.
|
||||
|
||||
If the optional //overrides// is specified, they can be used to
|
||||
override the endowment ``value``, transaction ``nonce``, ``gasLimit`` or
|
||||
``gasPrice``.
|
||||
|
||||
_property: contractFactory.deploy(...args [ , overrides ]) => Promise<[[Contract]]> @<ContractFactory-deploy>
|
||||
|
||||
Uses the signer to deploy the Contract with //args// passed into the constructor and
|
||||
returns a Contract which is attached to the address where this contract **will** be
|
||||
deployed once the transaction is mined.
|
||||
|
||||
The transaction can be found at ``contract.deployTransaction``, and no interactions
|
||||
should be made until the transaction is mined.
|
||||
|
||||
If the optional //overrides// is specified, they can be used to
|
||||
override the endowment ``value``, transaction ``nonce``, ``gasLimit`` or
|
||||
``gasPrice``.
|
||||
|
||||
_code: Deploying a Contract @lang<javascript>
|
||||
|
||||
//_hide: const signer = localSigner;
|
||||
//_hide: const ContractFactory = ethers.ContractFactory;
|
||||
//_hide: const bytecode = "608060405234801561001057600080fd5b5060405161012e38038061012e8339818101604052604081101561003357600080fd5b81019080805190602001909291908051906020019092919050505081600160006101000a81548173ffffffffffffffffffffffffffffffffffffffff021916908373ffffffffffffffffffffffffffffffffffffffff1602179055508060008190555050506088806100a66000396000f3fe6080604052348015600f57600080fd5b506004361060285760003560e01c80633fa4f24514602d575b600080fd5b60336049565b6040518082815260200191505060405180910390f35b6000805490509056fea2646970667358221220926465385af0e8706644e1ff3db7161af699dc063beaadd55405f2ccd6478d7564736f6c63430007040033";
|
||||
|
||||
// If your contract constructor requires parameters, the ABI
|
||||
// must include the constructor
|
||||
const abi = [
|
||||
"constructor(address owner, uint256 initialValue)",
|
||||
"function value() view returns (uint)"
|
||||
];
|
||||
|
||||
// The factory we use for deploying contracts
|
||||
factory = new ContractFactory(abi, bytecode, signer)
|
||||
|
||||
// Deploy an instance of the contract
|
||||
contract = await factory.deploy("ricmoo.eth", 42);
|
||||
|
||||
// The address is available immediately, but the contract
|
||||
// is NOT deployed yet
|
||||
//_result:
|
||||
contract.address
|
||||
//_log:
|
||||
|
||||
// The transaction that the signer sent to deploy
|
||||
//_result:
|
||||
contract.deployTransaction
|
||||
//_log:
|
||||
|
||||
// Wait until the transaction is mined (i.e. contract is deployed)
|
||||
// - returns the receipt
|
||||
// - throws on failure (the reciept is on the error)
|
||||
//_result:
|
||||
await contract.deployTransaction.wait()
|
||||
//_log:
|
||||
|
||||
// Now the contract is safe to interact with
|
||||
//_result:
|
||||
await contract.value()
|
||||
//_log:
|
||||
254
docs.wrm/api/contract/contract.wrm
Normal file
254
docs.wrm/api/contract/contract.wrm
Normal file
@ -0,0 +1,254 @@
|
||||
_section: Contract @<Contract> @SRC<contracts:class.Contract>
|
||||
|
||||
A **Contract** is an abstraction of code that has been deployed
|
||||
to the blockchain.
|
||||
|
||||
A Contract may be sent transactions, which will trigger its code
|
||||
to be run with the input of the transaction data.
|
||||
|
||||
_subsection: Creating Instances @<Contract--creating>
|
||||
|
||||
_property: new ethers.Contract(address, abi, signerOrProvider) @src<contracts:class.Contract>
|
||||
|
||||
_property: contract.attach(addressOrName) => [[Contract]] @<Contract-attach> @SRC<contracts:BaseContract.attach>
|
||||
Returns a new instance of the **Contract** attached to a new
|
||||
address. This is useful if there are multiple similar or identical
|
||||
copies of a Contract on the network and you wish to interact with
|
||||
each of them.
|
||||
|
||||
_property: contract.connect(providerOrSigner) => [[Contract]] @<Contract-connect> @SRC<contracts:BaseContract.connect>
|
||||
Returns a new instance of the Contract, but connected to
|
||||
//providerOrSigner//.
|
||||
|
||||
By passing in a [[Provider]], this will return a downgraded
|
||||
**Contract** which only has read-only access (i.e. constant calls).
|
||||
|
||||
By passing in a [[Signer]]. this will return a **Contract** which
|
||||
will act on behalf of that signer.
|
||||
|
||||
|
||||
_subsection: Properties @<Contract--properties>
|
||||
|
||||
_property: contract.address => string<[[address]]>
|
||||
This is the address (or ENS name) the contract was constructed with.
|
||||
|
||||
_property: contract.resolvedAddress => string<[[address]]>
|
||||
This is a promise that will resolve to the address the **Contract**
|
||||
object is attached to. If an [[address]] was provided to the constructor,
|
||||
it will be equal to this; if an ENS name was provided, this will be the
|
||||
resolved address.
|
||||
|
||||
_property: contract.deployTransaction => [[providers-TransactionResponse]]
|
||||
If the **Contract** object is the result of a ContractFactory deployment,
|
||||
this is the transaction which was used to deploy the contract.
|
||||
|
||||
_property: contract.interface => [[Interface]]
|
||||
This is the ABI as an [[Interface]].
|
||||
|
||||
_property: contract.provider => [[Provider]]
|
||||
If a provider was provided to the constructor, this is that provider. If
|
||||
a signer was provided that had a [[Provider]], this is that provider.
|
||||
|
||||
_property: contract.signer => [[Signer]]
|
||||
If a signer was provided to the constructor, this is that signer.
|
||||
|
||||
|
||||
_subsection: Methods @<Contract--methods>
|
||||
|
||||
_property: contract.deployed() => Promise<[[Contract]]> @<Contract-deployed> @SRC<contracts>
|
||||
|
||||
_property: Contract.isIndexed(value) => boolean @<Contract-isIndexed> @SRC<contracts>
|
||||
|
||||
|
||||
_subsection: Events @<Contract--events>
|
||||
|
||||
_property: contract.queryFilter(event [ , fromBlockOrBlockHash [ , toBlock ]) => Promise<Array<Event>> @<Contract-queryFilter> @SRC<contracts>
|
||||
Return Events that match the //event//.
|
||||
|
||||
_property: contract.listenerCount([ event ]) => number @<Contract-listenerCount> @SRC<contracts:BaseContract.listenerCount>
|
||||
Return the number of listeners that are subscribed to //event//. If
|
||||
no event is provided, returns the total count of all events.
|
||||
|
||||
_property: contract.listeners(event) => Array<Listener> @<Contract-listeners> @SRC<contracts:BaseContract.listeners>
|
||||
Return a list of listeners that are subscribed to //event//.
|
||||
|
||||
_property: contract.off(event, listener) => this @<Contract-off> @SRC<contracts>
|
||||
Unsubscribe //listener// to //event//.
|
||||
|
||||
_property: contract.on(event, listener) => this @<Contract-on> @SRC<contracts>
|
||||
Subscribe to //event// calling //listener// when the event occurs.
|
||||
|
||||
_property: contract.once(event, listener) => this @<Contract-once> @SRC<contracts>
|
||||
Subscribe once to //event// calling //listener// when the event
|
||||
occurs.
|
||||
|
||||
_property: contract.removeAllListeners([ event ]) => this @<Contract-removeAllListeners> @SRC<contracts:BaseContract.removeAllListeners>
|
||||
Unsubscribe all listeners for //event//. If no event is provided,
|
||||
all events are unsubscribed.
|
||||
|
||||
|
||||
_subsection: Meta-Class @<Contract--metaclass>
|
||||
|
||||
A Meta-Class is a Class which has any of its properties determined
|
||||
at run-time. The **Contract** object uses a Contract's ABI to
|
||||
determine what methods are available, so the following sections
|
||||
describe the generic ways to interact with the properties added
|
||||
at run-time during the **Contract** constructor.
|
||||
|
||||
|
||||
_heading: Read-Only Methods (constant) @<Contract--readonly>
|
||||
|
||||
A constant method is read-only and evaluates a small amount of EVM
|
||||
code against the current blockchain state and can be computed by
|
||||
asking a single node, which can return a result. It is therefore
|
||||
free and does not require any ether, but **cannot make changes** to
|
||||
the blockchain state..
|
||||
|
||||
_property: contract.METHOD_NAME(...args [, overrides ]) => Promise<any> @<Contract-functionsCall>
|
||||
The type of the result depends on the ABI. If the method returns a single
|
||||
value, it will be returned directly, otherwise a [[Result]] object will
|
||||
be returned with each parameter available positionally and if the parameter
|
||||
is named, it will also be available by its name.
|
||||
|
||||
For values that have a simple meaning in JavaScript, the types are fairly
|
||||
straight forward; strings and booleans are returned as JavaScript strings
|
||||
and booleans.
|
||||
|
||||
For numbers, if the **type** is in the JavaScript safe range (i.e. less
|
||||
than 53 bits, such as an ``int24`` or ``uint48``) a normal JavaScript
|
||||
number is used. Otherwise a [[BigNumber]] is returned.
|
||||
|
||||
For bytes (both fixed length and dynamic), a [[DataHexString]] is returned.
|
||||
|
||||
If the call reverts (or runs out of gas), a [CALL_EXCEPTION](errors--call-exception)
|
||||
will be thrown which will include:
|
||||
|
||||
- ``error.address`` - the contract address
|
||||
- ``error.args`` - the arguments passed into the method
|
||||
- ``error.transaction`` - the transaction
|
||||
|
||||
The //overrides// object for a read-only method may include any of:
|
||||
|
||||
- ``overrides.from`` - the ``msg.sender`` (or ``CALLER``) to use during the
|
||||
execution of the code
|
||||
- ``overrides.value`` - the ``msg.value`` (or ``CALLVALUE``) to use during the
|
||||
exectuiont of the code
|
||||
- ``overrides.gasPrice`` - the price to pay per gas (theoretically); since there
|
||||
is no transaction, there is not going to be any fee charged, but the EVM still
|
||||
requires a value to report to ``tx.gasprice`` (or ``GASPRICE``);
|
||||
//most developers will not require this//
|
||||
- ``overrides.gasLimit`` - the amount of gas (theoretically) to allow a node
|
||||
to use during the execution of the code; since there is no transaction, there
|
||||
is not going to be any fee charged, but the EVM still processes gas metering
|
||||
so calls like ``gasleft`` (or ``GAS``) report meaningful values
|
||||
- ``overrides.blockTag`` - a block tag to simulate the execution at, which
|
||||
can be used for hypothetical historic analysis; note that many backends
|
||||
do not support this, or may require paid plans to access as the node database
|
||||
storage and processing requirements are much higher
|
||||
|
||||
_property: contract.functions.METHOD_NAME(...args [, overrides ]) => Promise<[[Result]]>
|
||||
|
||||
The result will always be a [[Result]], even if there is only a single
|
||||
return value type.
|
||||
|
||||
This simplifies frameworks which wish to use the [[Contract]] object,
|
||||
since they do not need to inspect the return types to unwrap simplified
|
||||
functions.
|
||||
|
||||
Another use for this method is for error recovery. For example, if a
|
||||
function result is an invalid UTF-8 string, the normal call using the
|
||||
above meta-class function will throw an exception. This allows using the
|
||||
Result access error to access the low-level bytes and reason for the error
|
||||
allowing an alternate UTF-8 error strategy to be used.
|
||||
|
||||
Most developers should not require this.
|
||||
|
||||
The //overrides// are identical to the read-only operations above.
|
||||
|
||||
_heading: Write Methods (non-constant) @<Contract--write>
|
||||
|
||||
A non-constant method requires a transaction to be signed and requires
|
||||
payment in the form of a fee to be paid to a miner. This transaction
|
||||
will be verified by every node on the entire network as well by the
|
||||
miner who will compute the new state of the blockchain after executing
|
||||
it against the current state.
|
||||
|
||||
It cannot return a result. If a result is required, it should be logged
|
||||
using a Solidity event (or EVM log), which can then be queried from the
|
||||
transaction receipt.
|
||||
|
||||
_property: contract.METHOD_NAME(...args [ , overrides ]) => Promise<[[providers-TransactionResponse]]> @<contract-functionsSend>
|
||||
Returns a [[providers-TransactionResponse]] for the transaction after
|
||||
it is sent to the network. This requires the **Contract** has a
|
||||
signer.
|
||||
|
||||
The //overrides// object for write methods may include any of:
|
||||
|
||||
- ``overrides.gasPrice`` - the price to pay per gas
|
||||
- ``overrides.gasLimit`` - the limit on the amount of gas to allow the transaction
|
||||
to consume; any unused gas is returned at the gasPrice
|
||||
- ``overrides.value`` - the amount of ether (in wei) to forward with the call
|
||||
- ``overrides.nonce`` - the nonce to use for the [[Signer]]
|
||||
|
||||
If the ``wait()`` method on the returned [[providers-TransactionResponse]]
|
||||
is called, there will be additional properties on the receipt:
|
||||
|
||||
- ``receipt.events`` - an array of the logs, with additional properties
|
||||
(if the ABI included a description for the events)
|
||||
- ``receipt.events[n].args`` - the parsed arguments
|
||||
- ``receipt.events[n].decode`` - a method that can be used to parse the
|
||||
log topics and data (this was used to compute ``args``)
|
||||
- ``receipt.events[n].event`` - the name of the event
|
||||
- ``receipt.events[n].eventSignature`` - the full signature of the event
|
||||
- ``receipt.removeListener()`` - a method to remove the listener that trigger
|
||||
this event
|
||||
- ``receipt.getBlock()`` - a method to return the [Block](providers-Block) this event occurred in
|
||||
- ``receipt.getTransaction()`` - a method to return the
|
||||
[Transaction](providers-TransactionResponse) this event occurred in
|
||||
- ``receipt.getTransactionReceipt()`` - a method to return the
|
||||
[Transaction Receipt](providers-TransactionReceipt) this event occurred in
|
||||
|
||||
|
||||
_heading: Write Methods Analysis @<Contract--check>
|
||||
|
||||
There are several options to analyze properties and results of a
|
||||
write method without actually executing it.
|
||||
|
||||
_property: contract.estimateGas.METHOD_NAME(...args [ , overrides ]) => Promise<[[BigNumber]]> @<contract-estimateGas>
|
||||
Returns the estimate units of gas that would be required to
|
||||
execute the //METHOD_NAME// with //args// and //overrides//.
|
||||
|
||||
The //overrides// are identical to the overrides above for read-only
|
||||
or write methods, depending on the type of call of //METHOD_NAME//.
|
||||
|
||||
_property: contract.populateTransaction.METHOD_NAME(...args [ , overrides ]) => Promise<[UnsignedTx](UnsignedTransaction)> @<contract-populateTransaction>
|
||||
Returns an [[UnsignedTransaction]] which represents the transaction
|
||||
that would need to be signed and submitted to the network to execute
|
||||
//METHOD_NAME// with //args// and //overrides//.
|
||||
|
||||
The //overrides// are identical to the overrides above for read-only
|
||||
or write methods, depending on the type of call of //METHOD_NAME//.
|
||||
|
||||
_property: contract.callStatic.METHOD_NAME(...args [ , overrides ]) => Promise<any> @<contract-callStatic>
|
||||
Rather than executing the state-change of a transaction, it is possible
|
||||
to ask a node to //pretend// that a call is not state-changing and
|
||||
return the result.
|
||||
|
||||
This does not actually change any state, but is free. This in some cases
|
||||
can be used to determine if a transaction will fail or succeed.
|
||||
|
||||
This otherwise functions the same as a [Read-Only Method](Contract--readonly).
|
||||
|
||||
The //overrides// are identical to the read-only operations above.
|
||||
|
||||
_heading: Event Filters @<Contract--filters>
|
||||
An event filter is made up of topics, which are values logged in a
|
||||
[[link-wiki-bloomfilter]], allowing efficient searching for entries
|
||||
which match a filter.
|
||||
|
||||
_property: contract.filters.EVENT_NAME(...args) => Filter
|
||||
Return a filter for //EVENT_NAME//, optionally filtering by additional
|
||||
constraints.
|
||||
|
||||
Only ``indexed`` event parameters may be filtered. If a parameter is
|
||||
null (or not provided) then any value in that field matches.
|
||||
186
docs.wrm/api/contract/example.wrm
Normal file
186
docs.wrm/api/contract/example.wrm
Normal file
@ -0,0 +1,186 @@
|
||||
_section: Example: ERC-20 Contract
|
||||
|
||||
_subsection: Connecting to a Contract
|
||||
|
||||
_code: A simple ERC-20 contract @lang<javascript>
|
||||
|
||||
// A Human-Readable ABI; any supported ABI format could be used
|
||||
const abi = [
|
||||
// Read-Only Functions
|
||||
"function balanceOf(address owner) view returns (uint256)",
|
||||
"function decimals() view returns (uint8)",
|
||||
"function symbol() view returns (string)",
|
||||
|
||||
// Authenticated Functions
|
||||
"function transfer(address to, uint amount) returns (boolean)",
|
||||
|
||||
// Events
|
||||
"event Transfer(address indexed from, address indexed to, uint amount)"
|
||||
];
|
||||
|
||||
// This can be an address or an ENS name
|
||||
const address = "dai.tokens.ethers.eth";
|
||||
|
||||
// An example Provider
|
||||
const provider = ethers.getDefaultProvider();
|
||||
|
||||
// An example Signer
|
||||
const signer = ethers.Wallet.createRandom().connect(provider);
|
||||
|
||||
// Read-Only; By connecting to a Provider, allows:
|
||||
// - Any constant function
|
||||
// - Querying Filters
|
||||
// - Populating Unsigned Transactions for non-constant methods
|
||||
// - Estimating Gas for non-constant (as an anonymous sender)
|
||||
// - Static Calling non-constant methods (as anonymous sender)
|
||||
const erc20 = new ethers.Contract(address, abi, provider);
|
||||
|
||||
// Read-Write; By connecting to a Signer, allows:
|
||||
// - Everything from Read-Only (except as Signer, not anonymous)
|
||||
// - Sending transactions for non-constant functions
|
||||
const erc20_rw = new ethers.Contract(address, abi, signer)
|
||||
|
||||
|
||||
_heading: ERC20Contract @INHERIT<[[Contract]]>
|
||||
|
||||
_property: new ethers.Contract(address, abi, providerOrSigner)
|
||||
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 //abi// to a **Contract**
|
||||
connected to //address// using the //providerOrSigner//.
|
||||
|
||||
|
||||
_subsection: Properties @NOTE<(inheritted from [[Contract]])>
|
||||
|
||||
_property: erc20.address => string<[[address]]>
|
||||
This is the address (or ENS name) the contract was constructed with.
|
||||
|
||||
_property: erc20.resolvedAddress => string<[[address]]>
|
||||
This is a promise that will resolve to the address the **Contract**
|
||||
object is attached to. If an [[address]] was provided to the constructor,
|
||||
it will be equal to this; if an ENS name was provided, this will be the
|
||||
resolved address.
|
||||
|
||||
_property: erc20.deployTransaction => [[providers-TransactionResponse]]
|
||||
If the **Contract** object is the result of a ContractFactory deployment,
|
||||
this is the transaction which was used to deploy the contract.
|
||||
|
||||
_property: erc20.interface => [[Interface]]
|
||||
This is the ABI as an [[Interface]].
|
||||
|
||||
_property: erc20.provider => [[Provider]]
|
||||
If a provider was provided to the constructor, this is that provider. If
|
||||
a signer was provided that had a [[Provider]], this is that provider.
|
||||
|
||||
_property: erc20.signer => [[Signer]]
|
||||
If a signer was provided to the constructor, this is that signer.
|
||||
|
||||
|
||||
_subsection: Methods @NOTE<(inheritted from [[Contract]])>
|
||||
|
||||
_property: erc20.attach(addressOrName) => [[Contract]]
|
||||
Returns a new instance of the **Contract** attached to a new
|
||||
address. This is useful if there are multiple similar or identical
|
||||
copies of a Contract on the network and you wish to interact with
|
||||
each of them.
|
||||
|
||||
_property: erc20.connect(providerOrSigner) => [[Contract]]
|
||||
Returns a new instance of the Contract, but connected to
|
||||
//providerOrSigner//.
|
||||
|
||||
By passing in a [[Provider]], this will return a downgraded
|
||||
**Contract** which only has read-only access (i.e. constant calls).
|
||||
|
||||
By passing in a [[Signer]]. this will return a **Contract** which
|
||||
will act on behalf of that signer.
|
||||
|
||||
_property: erc20.deployed() => Promise<Contract>
|
||||
|
||||
_property: Contract.isIndexed(value) => boolean
|
||||
|
||||
|
||||
_subsection: Events @NOTE<(inheritted from [[Contract]])> @<erc20-events>
|
||||
|
||||
_property: erc20.queryFilter(event [ , fromBlockOrBlockHash [ , toBlock ]) => Promise<Array<Event>> @<erc20-queryfilter>
|
||||
Return Events that match the //event//.
|
||||
|
||||
_property: erc20.listenerCount([ event ]) => number
|
||||
Return the number of listeners that are subscribed to //event//. If
|
||||
no event is provided, returns the total count of all events.
|
||||
|
||||
_property: erc20.listeners(event) => Array<Listener>
|
||||
Return a list of listeners that are subscribed to //event//.
|
||||
|
||||
_property: erc20.off(event, listener) => this
|
||||
Unsubscribe //listener// to //event//.
|
||||
|
||||
_property: erc20.on(event, listener) => this
|
||||
Subscribe to //event// calling //listener// when the event occurs.
|
||||
|
||||
_property: erc20.once(event, listener) => this
|
||||
Subscribe once to //event// calling //listener// when the event
|
||||
occurs.
|
||||
|
||||
_property: erc20.removeAllListeners([ event ]) => this
|
||||
Unsubscribe all listeners for //event//. If no event is provided,
|
||||
all events are unsubscribed.
|
||||
|
||||
|
||||
_subsection: Meta-Class Methods @NOTE<(added at Runtime)>
|
||||
|
||||
Since the Contract is a Meta-Class, the methods available here depend
|
||||
on the ABI which was passed into the **Contract**.
|
||||
|
||||
_property: erc20.decimals([ overrides ]) => Promise<number>
|
||||
Returns the number of decimal places used by this ERC-20 token. This can be
|
||||
used with [parseUnits](utils-parseUnits) when taking input from the user or
|
||||
[formatUnits](utils-formatunits] when displaying the token amounts in the UI.
|
||||
|
||||
_property: erc20.balanceOf(owner [, overrides ]) => Promise<[[BigNumber]]>
|
||||
Returns the balance of //owner// for this ERC-20 token.
|
||||
|
||||
_property: erc20.symbol([ overrides ]) => Promise<string>
|
||||
Returns the symbol of the token.
|
||||
|
||||
_property: erc20_rw.transfer(target, amount [, overrides ]) => Promise<[[providers-TransactionResponse]]>
|
||||
Transfers //amount// tokens to //target// from the current signer.
|
||||
The return value (a boolean) is inaccessible during a write operation
|
||||
using a transaction. Other techniques (such as events) are required
|
||||
if this value is required. On-chain contracts calling the ``transfer``
|
||||
function have access to this result, which is why it is possible.
|
||||
|
||||
_property: erc20.callStatic.transfer(target, amount [, overrides ]) => Promise<boolean>
|
||||
Performs a dry-run of transferring //amount// tokens to //target// from
|
||||
the current signer, without actually signing or sending a transaction.
|
||||
|
||||
This can be used to preflight check that a transaction will be successful.
|
||||
|
||||
_property: erc20.estimateGas.transfer(target, amount [, overrides ]) => Promise<[[BigNumber]]>
|
||||
Returns an estimate for how many units of gas would be required
|
||||
to transfer //amount// tokens to //target//.
|
||||
|
||||
_property: erc20.populateTransaction.transfer(target, amount [, overrides ]) => Promise<[UnsignedTx](UnsignedTransaction)>
|
||||
Returns an [[UnsignedTransaction]] which could be signed and submitted
|
||||
to the network to transaction //amount// tokens to //target//.
|
||||
|
||||
|
||||
_note: Note on Estimating and Static Calling
|
||||
|
||||
When you perform a static call, the current state is taken into account as
|
||||
best as Ethereum can determine. There are many cases where this can provide
|
||||
false positives and false negatives. The eventually consistent model of the
|
||||
blockchain also means there are certain consistency modes that cannot be
|
||||
known until an actual transaction is attempted.
|
||||
|
||||
|
||||
_subsection: Meta-Class Filters @NOTE<(added at Runtime)>
|
||||
|
||||
Since the Contract is a Meta-Class, the methods available here depend
|
||||
on the ABI which was passed into the **Contract**.
|
||||
|
||||
_property: erc20.filters.Transfer([ fromAddress [ , toAddress ] ]) => Filter
|
||||
Returns a new Filter which can be used to [query](erc20-queryfilter) or
|
||||
to [subscribe/unsubscribe to events](erc20-events).
|
||||
|
||||
If //fromAddress// is null or not provided, then any from address matches.
|
||||
If //toAddress// is null or not provided, then any to address matches.
|
||||
14
docs.wrm/api/contract/index.wrm
Normal file
14
docs.wrm/api/contract/index.wrm
Normal file
@ -0,0 +1,14 @@
|
||||
_section: Contract Interaction @<contracts>
|
||||
|
||||
A **Contract** object is an abstraction of a contract (EVM bytecode)
|
||||
deployed on the Ethereum network. It allows for a simple way to
|
||||
serialize calls and transactions to an on-chain contract and
|
||||
deserialize their results and emitted logs.
|
||||
|
||||
A **ContractFactory** is an abstraction of a contract's //bytecode//
|
||||
and facilitates deploying a contract.
|
||||
|
||||
_toc:
|
||||
contract
|
||||
contract-factory
|
||||
example
|
||||
93
docs.wrm/api/experimental.wrm
Normal file
93
docs.wrm/api/experimental.wrm
Normal file
@ -0,0 +1,93 @@
|
||||
_section: Experimental
|
||||
|
||||
The **Experimental** package is used for features that are not ready
|
||||
to be included in the base library. The API should not be considered
|
||||
stable and does not follow [[link-semver]] versioning, so applications
|
||||
requiring it should specify the //exact version// needed.
|
||||
|
||||
These features are not available in the core ethers package, so to use them
|
||||
you must install the ``@ethersproject/experimental`` package and import them
|
||||
from that.
|
||||
|
||||
_subsection: BrainWallet @<experimental-brainwallet> @INHERIT<[[Wallet]]>
|
||||
|
||||
Ethers removed support for BrainWallets in v4, since they are unsafe and
|
||||
many can be easily guessed, allowing attackers to steal the funds. This
|
||||
class is offered to ensure older systems which used brain wallets can
|
||||
still recover their funds and assets.
|
||||
|
||||
_property: BrainWallet.generate(username, password [ , progressCallback ]) => [[experimental-brainwallet]]
|
||||
Generates a brain wallet, with a slightly improved experience, in which
|
||||
the generated wallet has a mnemonic.
|
||||
|
||||
_property: BrainWallet.generateLegacy(username, password [ , progressCallback ]) => [[experimental-brainwallet]]
|
||||
Generate a brain wallet which is compatible with the ethers v3 and earlier.
|
||||
|
||||
_code: Importing @lang<script>
|
||||
|
||||
// Node
|
||||
const { BrainWallet } = require("@ethersproject/experimental");
|
||||
|
||||
// ESM/TypeScript
|
||||
import { BrainWallet } from "@ethersproject/experimental";
|
||||
|
||||
|
||||
_subsection: EIP1193Bridge @<experimental-eip1193bridge> @INHERIT<[[link-npm-events]]>
|
||||
|
||||
The **EIP1193Bridge** allows a normal Ethers [[Signer]] and [[Provider]] to be
|
||||
exposed in as a standard [EIP-1193 Provider](link-eip-1193), which may be useful
|
||||
when interacting with other libraries.
|
||||
|
||||
_code: Importing @lang<script>
|
||||
|
||||
// Node
|
||||
const { Eip1193Bridge } = require("@ethersproject/experimental");
|
||||
|
||||
// ESM/TypeScript
|
||||
import { Eip1193Bridge } from "@ethersproject/experimental";
|
||||
|
||||
|
||||
_subsection: NonceManager @<experimental-noncemanager> @INHERIT<[[Signer]]>
|
||||
|
||||
The **NonceManager** is designed to manage the nonce for a Signer,
|
||||
automatically increasing it as it sends transactions.
|
||||
|
||||
Currently the NonceManager does not handle re-broadcast. If you attempt
|
||||
to send a lot of transactions to the network on a node that does not
|
||||
control that account, the transaction pool may drop your transactions.
|
||||
|
||||
In the future, it'd be nice if the **NonceManager** remembered transactions
|
||||
and watched for them on the network, rebroadcasting transactions that
|
||||
appear to have been dropped.
|
||||
|
||||
Another future feature will be some sort of failure mode. For example, often
|
||||
a transaction is dependent on another transaction being mined first.
|
||||
|
||||
_property: new NonceManager(signer)
|
||||
Create a new NonceManager.
|
||||
|
||||
_property: nonceManager.signer => [[Signer]]
|
||||
The signer whose nonce is being managed.
|
||||
|
||||
_property: nonceManager.provider => [[Provider]]
|
||||
The provider associated with the signer.
|
||||
|
||||
_property: nonceManager.setTransactionCount(count) => void
|
||||
Set the current transaction count (nonce) for the signer.
|
||||
|
||||
This may be useful in interacting with the signer outside of using
|
||||
this class.
|
||||
|
||||
_property: nonceManager.incrementTransactionCount( [ count = 1 ]) => void
|
||||
Bump the current transaction count (nonce) by //count//.
|
||||
|
||||
This may be useful in interacting with the signer outside of using
|
||||
this class.
|
||||
|
||||
_code: Importing @lang<script>
|
||||
|
||||
// Node
|
||||
const { NonceManager } = require("@ethersproject/experimental");
|
||||
|
||||
// ESM/TypeScript
|
||||
import { NonceManager } from "@ethersproject/experimental";
|
||||
12
docs.wrm/api/index.wrm
Normal file
12
docs.wrm/api/index.wrm
Normal file
@ -0,0 +1,12 @@
|
||||
_section: Application Programming Interface @<api> @NAV<API>
|
||||
|
||||
An Application Programming Interface (API) is the formal
|
||||
specification of the library.
|
||||
|
||||
_toc:
|
||||
providers
|
||||
signer
|
||||
contract
|
||||
utils
|
||||
other
|
||||
experimental
|
||||
86
docs.wrm/api/other/assembly/api.wrm
Normal file
86
docs.wrm/api/other/assembly/api.wrm
Normal file
@ -0,0 +1,86 @@
|
||||
_section: Utilities @<asm-utilities>
|
||||
|
||||
_subsection: Assembler
|
||||
|
||||
The assembler utilities allow parsing and assembling an
|
||||
[Ethers ASM Dialect](asm-dialect) source file.
|
||||
|
||||
_property: asm.parse(code) => [[asm-node]] @<asm-parse> @SRC<asm/assembler>
|
||||
Parse an ethers-format assembly file and return the [[asm-ast]].
|
||||
|
||||
_property: asm.assemble(node) => string<[[DataHexString]]> @SRC<asm/assembler:function.assemble>
|
||||
Performs assembly of the [[asm-ast]] //node// and return the
|
||||
resulting bytecode representation.
|
||||
|
||||
|
||||
_subsection: Disassembler
|
||||
|
||||
The **Disassembler** utilities make it easy to convert bytecode
|
||||
into an object which can easily be examined for program structure.
|
||||
|
||||
_property: asm.disassemble(bytecode) => [[asm-bytecode]] @SRC<asm/assembler>
|
||||
Returns an array of Operations given //bytecode//.
|
||||
|
||||
_property: asm.formatBytecode(operations) => string @SRC<asm/assembler>
|
||||
Create a formatted output of an array of [[asm-operation]].
|
||||
|
||||
_heading: Bytecode @<asm-bytecode> @INHERIT<Array\<[[asm-operation]]\>>
|
||||
|
||||
Each array index represents an operation, collapsing multi-byte operations
|
||||
(i.e. ``PUSH``) into a single operation.
|
||||
|
||||
_property: bytecode.getOperation(offset) => [[asm-operation]]
|
||||
Get the operation at a given //offset// into the bytecode. This ensures that
|
||||
the byte at //offset// is an operation and not data contained within a ``PUSH``,
|
||||
in which case null it returned.
|
||||
|
||||
_heading: Operation @<asm-operation>
|
||||
|
||||
An **Operation** is a single command from a disassembled bytecode
|
||||
stream.
|
||||
|
||||
_property: operation.opcode => [[asm-opcode]]
|
||||
The opcode for this Operation.
|
||||
|
||||
_property: operation.offset => number
|
||||
The offset into the bytecode for this Operation.
|
||||
|
||||
_property: operation.pushValue => string<[[DataHexString]]>
|
||||
If the opcode is a ``PUSH``, this is the value of that push
|
||||
|
||||
|
||||
_subsection: Opcode @<asm-opcode> @SRC<asm/opcodes:class.Opcode>
|
||||
|
||||
_property: asm.Opcode.from(valueOrMnemonic) => [[asm-opcode]]
|
||||
Create a new instance of an Opcode for a given numeric value
|
||||
(e.g. 0x60 is PUSH1) or mnemonic string (e.g. "PUSH1").
|
||||
|
||||
_heading: Properties
|
||||
|
||||
_property: opcode.value => number
|
||||
The value (bytecode as a number) of this opcode.
|
||||
|
||||
_property: opcode.mnemonic => string
|
||||
The mnemonic string of this opcode.
|
||||
|
||||
_property: opcode.delta => number
|
||||
The number of items this opcode will consume from the stack.
|
||||
|
||||
_property: opcode.alpha => number
|
||||
The number of items this opcode will push onto the stack.
|
||||
|
||||
_property: opcode.doc => string
|
||||
A short description of what this opcode does.
|
||||
|
||||
_property: opcode.isMemory() => "read" | "write" | "full"
|
||||
Returns true if the opcode accesses memory.
|
||||
|
||||
_property: opcode.isStatic() => boolean
|
||||
Returns true if the opcode cannot change state.
|
||||
|
||||
_property: opcode.isJump() => boolean
|
||||
Returns true if the opcode is a jumper operation.
|
||||
|
||||
_property: opcode.isPush() => number
|
||||
Returns 0 if the opcode is not a ``PUSH*``, or the number
|
||||
of bytes this opcode will push if it is.
|
||||
150
docs.wrm/api/other/assembly/ast.wrm
Normal file
150
docs.wrm/api/other/assembly/ast.wrm
Normal file
@ -0,0 +1,150 @@
|
||||
_section: Abstract Syntax Tree @<asm-ast>
|
||||
|
||||
Parsing a file using the [Ethers ASM Dialect](asm-dialect) will
|
||||
generate an Abstract Syntax Tree. The root node will always
|
||||
be a [[asm-scopenode]] whose name is ``_``.
|
||||
|
||||
To parse a file into an Abstract Syntax tree, use the [parse](asm-parse)
|
||||
function.
|
||||
|
||||
|
||||
_subsection: Types
|
||||
|
||||
_heading: Location @<asm-location>
|
||||
|
||||
_property: offset => number
|
||||
The offset into the source code to the start of this node.
|
||||
|
||||
_property: length => number
|
||||
The length of characters in the source code to the end of this node.
|
||||
|
||||
_property: source => string
|
||||
The source code of this node.
|
||||
|
||||
|
||||
_subsection: Nodes
|
||||
|
||||
@TODO: Place a diagram here showing the hierarchy
|
||||
|
||||
_heading: Node @<asm-node> @SRC<asm:class.Node>
|
||||
|
||||
_property: node.tag => string
|
||||
A unique tag for this node for the lifetime of the process.
|
||||
|
||||
_property: node.location => [[asm-location]]
|
||||
The source code and location within the source code that this
|
||||
node represents.
|
||||
|
||||
|
||||
_heading: ValueNode @<asm-valuenode> @INHERIT<[[asm-node]]> @SRC<asm:class.ValueNode>
|
||||
|
||||
A **ValueNode** is a node which may manipulate the stack.
|
||||
|
||||
|
||||
_heading: LiteralNode @<asm-literalnode> @INHERIT<[[asm-valuenode]]> @SRC<asm:class.LiteralNode>
|
||||
|
||||
_property: literalNode.value => string
|
||||
The literal value of this node, which may be a [[DataHexString]] or
|
||||
string of a decimal number.
|
||||
|
||||
_property: literalNode.verbatim => boolean
|
||||
This is true in a [[asm-datanode]] context, since in that case the
|
||||
value should be taken verbatim and no ``PUSH`` operation should be
|
||||
added, otherwise false.
|
||||
|
||||
|
||||
_heading: PopNode @<asm-popnode> @INHERIT<[[asm-valuenode]]> @SRC<asm:class.PopNode>
|
||||
|
||||
A **PopNode** is used to store a place-holder for an implicit pop from the
|
||||
stack. It represents the code for an implicit place-holder (i.e. ``$$``) or an
|
||||
explicit place-holder (e.g. ``$1``), which indicates the expected stack position
|
||||
to consume.
|
||||
|
||||
_property: literalNode.index => number
|
||||
|
||||
The index this **PopNode** is representing. For an implicit place-holder
|
||||
this is ``0``.
|
||||
|
||||
|
||||
_heading: LinkNode @<asm-linknode> @INHERIT<[[asm-valuenode]]> @SRC<asm:class.LinkNode>
|
||||
|
||||
A **LinkNode** represents a link to another [[asm-node]]'s data,
|
||||
for example ``$foo`` or ``#bar``.
|
||||
|
||||
_property: linkNode.label => string
|
||||
The name of the target node.
|
||||
|
||||
_property: linkNode.type => "offset" | "length"
|
||||
Whether this node is for an offset or a length value of the
|
||||
target node.
|
||||
|
||||
|
||||
_heading: OpcodeNode @<asm-opcodenode> @INHERIT<[[asm-valuenode]]> @SRC<asm:class.OpcodeNode>
|
||||
|
||||
_property: opcodeNode.opcode => [[asm-opcode]]
|
||||
The opcode for this Node.
|
||||
|
||||
_property: opcodeNode.operands => Array<[[asm-valuenode]]>
|
||||
A list of all operands passed into this Node.
|
||||
|
||||
|
||||
_heading: EvaluationNode @<asm-evaluationnode> @INHERIT<[[asm-valuenode]]> @SRC<asm:class.EvaluationNode>
|
||||
|
||||
An **EvaluationNode** is used to execute code and insert the results
|
||||
but does not generate
|
||||
any output assembly, using the ``{{! code here }}`` syntax.
|
||||
|
||||
_property: literalNode.verbatim => boolean
|
||||
This is true in a [[asm-datanode]] context, since in that case the
|
||||
value should be taken verbatim and no ``PUSH`` operation should be
|
||||
added, otherwise false.
|
||||
|
||||
_property: evaluationNode.script => string
|
||||
The code to evaluate and produce the result to use as a literal.
|
||||
|
||||
|
||||
_heading: ExecutionNode @<asm-executionnode> @INHERIT<[[asm-node]]> @SRC<asm:class.ExecutionNode>
|
||||
|
||||
An **ExecutionNode** is used to execute code but does not generate
|
||||
any output assembly, using the ``{{! code here }}`` syntax.
|
||||
|
||||
_property: evaluationNode.script => string
|
||||
The code to execute. Any result is ignored.
|
||||
|
||||
|
||||
_heading: LabelledNode @<asm-labellednode> @INHERIT<[[asm-node]]> @SRC<asm:class.LabelledNode>
|
||||
|
||||
A **LabelledNode** is used for any Node that has a name, and can therefore
|
||||
be targeted by a [[asm-linknode]].
|
||||
|
||||
_property: labelledNode.name => string
|
||||
The name of this node.
|
||||
|
||||
|
||||
_heading: LabelNode @<asm-labelnode> @INHERIT<[[asm-labellednode]]> @SRC<asm:class.LabelNode>
|
||||
|
||||
A **LabelNode** is used as a place to ``JUMP`` to by referencing it
|
||||
name, using ``@myLabel:``. A ``JUMPDEST`` is automatically inserted
|
||||
at the bytecode offset.
|
||||
|
||||
|
||||
_heading: DataNode @<asm-datanode> @INHERIT<[[asm-labellednode]]> @SRC<asm:class.DataNode>
|
||||
|
||||
A **DataNode** allows for data to be inserted directly into the output
|
||||
assembly, using ``@myData[ ... ]``. The data is padded if needed to ensure
|
||||
values that would otherwise be regarded as a ``PUSH`` value does not impact
|
||||
anything past the data.
|
||||
|
||||
_property: dataNode.data => Array<[[asm-valuenode]]>
|
||||
The child nodes, which each represent a verbatim piece of data in insert.
|
||||
|
||||
_heading: ScopeNode @<asm-scopenode> @INHERIT<[[asm-labellednode]]> @SRC<asm:class.ScopeNode>
|
||||
|
||||
|
||||
A **ScopeNode** allows a new frame of reference that all [[asm-linknode]]'s
|
||||
will use when resolving offset locations, using ``@myScope{ ... }``.
|
||||
|
||||
_property: scopeNode.statements => Array<[[asm-node]]>
|
||||
The list of child nodes for this scope.
|
||||
|
||||
|
||||
115
docs.wrm/api/other/assembly/dialect.wrm
Normal file
115
docs.wrm/api/other/assembly/dialect.wrm
Normal file
@ -0,0 +1,115 @@
|
||||
_section: Ethers ASM Dialect @<asm-dialect>
|
||||
|
||||
This provides a quick, high-level overview of the **Ethers ASM Dialect**
|
||||
for EVM, which is defined by the [Ethers ASM Dialect Grammar](link-ethers-asm-grammar)
|
||||
|
||||
Once a program is compiled by a higher level language into ASM (assembly),
|
||||
or hand-coded directly in ASM, it needs to be assembled into bytecode.
|
||||
|
||||
The assembly process performs a very small set of operations and is
|
||||
intentionally simple and closely related to the underlying EVM bytecode.
|
||||
|
||||
Operations include embedding programs within programs (for example the
|
||||
deployment bootstrap has the runtime embedded in it) and computing the
|
||||
necessary offsets for jump operations.
|
||||
|
||||
The [Command-Line Assembler](cli-asm) can be used to assemble an
|
||||
//Ethers ASM Dialect// file or to disassemble bytecode into its
|
||||
human-readable (ish) opcodes and literals.
|
||||
|
||||
|
||||
_subsection: Opcodes @<asm-dialect-opcode>
|
||||
|
||||
An **Opcode** may be provided in either a //functional// or
|
||||
//instructional// syntax. For Opcodes that require parameters,
|
||||
the //functional// syntax is recommended and the //instructional//
|
||||
syntax will raise a warning.
|
||||
|
||||
@TODO: Examples
|
||||
|
||||
|
||||
_subsection: Labels @<asm-dialect-label>
|
||||
|
||||
A **Label** is a position in the program which can be jumped to. A
|
||||
``JUMPDEST`` is automatically added to this point in the assembled
|
||||
output.
|
||||
|
||||
@TODO: Examples
|
||||
|
||||
|
||||
_subsection: Literals @<asm-dialect-literal>
|
||||
|
||||
A **Literal** puts data on the stack when executed using a ``PUSH``
|
||||
operation.
|
||||
|
||||
A **Literal** can be provided using a [[DataHexString]] or a decimal
|
||||
byte value.
|
||||
|
||||
@TODO: examples
|
||||
|
||||
|
||||
_subsection: Comments @<asm-dialect-comment>
|
||||
|
||||
To enter a comment in the **Ethers ASM Dialect**, any text following
|
||||
a semi-colon (i.e. ``;``) is ignored by the assembler.
|
||||
|
||||
|
||||
_subsection: Scopes @<asm-dialect-scope>
|
||||
|
||||
A common case in Ethereum is to have one program embedded in another.
|
||||
|
||||
The most common use of this is embedding a Contract **runtime bytecode**
|
||||
within a **deployment bytecode**, which can be used as **init code**.
|
||||
|
||||
When deploying a program to Ethereum, an **init transaction** is used. An
|
||||
//init transaction// has a null ``to`` address and contains bytecode in
|
||||
the ``data``. This ``data`` bytecode is a program, that when executed
|
||||
returns some other bytecode as a result, this result is the bytecode
|
||||
to be installed.
|
||||
|
||||
Therefore it is important that embedded code uses jumps relative to itself,
|
||||
not the entire program it is embedded in, which also means that a jump
|
||||
can **only** target its own scope, no parent or child scopes. This is
|
||||
enforced by the assembler.
|
||||
|
||||
A scope may access the offset of any child [[asm-dialect-datasegment]] or
|
||||
child [[asm-dialect-scope]] (with respect to itself) and may access the length
|
||||
of any [[asm-dialect-datasegment]] or [[asm-dialect-scope]] anywhere in the program.
|
||||
|
||||
Every program in the **Ethers ASM Dialect** has a top-level scope named ``_``.
|
||||
|
||||
|
||||
_subsection: Data Segment @<asm-dialect-datasegment>
|
||||
|
||||
A **Data Segment** allows arbitrary data to be embedded into a program,
|
||||
which can be useful for lookup tables or deploy-time constants.
|
||||
|
||||
An empty **Data Segment** can also be used when a labelled location is
|
||||
required, but without the ``JUMPDEST`` which a [[asm-dialect-label]] adds.
|
||||
|
||||
@TODO: Example
|
||||
|
||||
|
||||
_subsection: Links @<asm-dialect-links>
|
||||
|
||||
A **Link** allows access to a [[asm-dialect-scope]], [[asm-dialect-datasegment]] or [[asm-dialect-label]].
|
||||
|
||||
To access the byte offset of a labelled item, use ``$foobar``.
|
||||
|
||||
For a [[asm-dialect-label]], the target must be directly reachable within this scope. For
|
||||
a [[asm-dialect-datasegment]] or a [[asm-dialect-scope]], it can be inside the same scope or any
|
||||
child scope.
|
||||
|
||||
For a [[asm-dialect-datasegment]] or a [[asm-dialect-label]], there is an additional type of
|
||||
**Link**, which provides the length of the data or bytecode respectively. A
|
||||
**Length Link** is accessed by ``#foobar`` and is pushed on the stack as a
|
||||
literal.
|
||||
|
||||
|
||||
_subsection: Stack Placeholders @<asm-dialect-placeholder>
|
||||
|
||||
@TODO: exampl
|
||||
|
||||
|
||||
_subsection: Evaluation and Execution @<asm-dialect-scripting>
|
||||
|
||||
8
docs.wrm/api/other/assembly/index.wrm
Normal file
8
docs.wrm/api/other/assembly/index.wrm
Normal file
@ -0,0 +1,8 @@
|
||||
_section: Assembly
|
||||
|
||||
This module should still be considered fairly experimental.
|
||||
|
||||
_toc:
|
||||
dialect
|
||||
api
|
||||
ast
|
||||
20
docs.wrm/api/other/hardware/index.wrm
Normal file
20
docs.wrm/api/other/hardware/index.wrm
Normal file
@ -0,0 +1,20 @@
|
||||
_section: Hardware Wallets
|
||||
|
||||
|
||||
_subsection: LedgerSigner @<hw-ledger> @INHERIT<[[Signer]]> @SRC<hardware-wallets:class.LedgerSigner>
|
||||
|
||||
The [Ledger Hardware Wallets](link-ledger) are a fairly
|
||||
popular brand.
|
||||
|
||||
|
||||
_code: Importing in ES6 or TypeScript @lang<script>
|
||||
|
||||
import { LedgerSigner } from "@ethersproject/hardware-wallets";
|
||||
|
||||
|
||||
_heading: API
|
||||
|
||||
_property: new LedgerSigner([provider [, type [ , path ] ] ]) => [[hw-ledger]]
|
||||
Connects to a Ledger Hardware Wallet. The //type// if left unspecified is
|
||||
determined by the environment; in node the default is "hid" and in the browser
|
||||
"u2f" is the default. The default Ethereum path is used if //path// is left unspecified.
|
||||
9
docs.wrm/api/other/index.wrm
Normal file
9
docs.wrm/api/other/index.wrm
Normal file
@ -0,0 +1,9 @@
|
||||
_section: Other Libraries
|
||||
|
||||
Now that ethers is more modular, it is possible to have additional
|
||||
ancillary packages, which are not part of the core but optionally
|
||||
add functionality only needed in certain situations.
|
||||
|
||||
_toc:
|
||||
assembly
|
||||
hardware
|
||||
207
docs.wrm/api/providers/api-providers.wrm
Normal file
207
docs.wrm/api/providers/api-providers.wrm
Normal file
@ -0,0 +1,207 @@
|
||||
_section: API Providers @<api-providers>
|
||||
|
||||
There are many services which offer a web API for accessing
|
||||
the Ethereum Blockchain. These Providers allow connecting
|
||||
to them, which simplifies development, since you do not need
|
||||
to run your own instance or cluster of Ethereum nodes.
|
||||
|
||||
However, this reliance on third-party services can reduce
|
||||
resilience, security and increase the amount of required trust.
|
||||
To mitigate these issues, it is recommended you use a
|
||||
[Default Provider](providers-getDefaultProvider).
|
||||
|
||||
|
||||
_subsection: EtherscanProvider @<EtherscanProvider> @inherit<[[Provider]]> @src<providers:class.EtherscanProvider>
|
||||
|
||||
The **EtherscanProvider** is backed by a combination of the various
|
||||
[Etherscan APIs](link-etherscan-api).
|
||||
|
||||
_property: new ethers.providers.EtherscanProvider([ network = "homestead", [ apiKey ] ])
|
||||
Create a new **EtherscanProvider** connected to //network// with the
|
||||
optional //apiKey//.
|
||||
|
||||
The //network// may be specified as a **string** for a common
|
||||
network name, a **number** for a common chain ID or a
|
||||
[Network Object]provider-(network).
|
||||
|
||||
If no //apiKey// is provided, a shared API key will be used,
|
||||
which may result in reduced performance and throttled requests.
|
||||
It is highly recommended for production, you register with
|
||||
[Etherscan](link-etherscan) for your own API key.
|
||||
|
||||
_note: Note: Default API keys
|
||||
If no //apiKey// is provided, a shared API key will be used,
|
||||
which may result in reduced performance and throttled requests.
|
||||
|
||||
It is highly recommended for production, you register with
|
||||
[Etherscan](link-etherscan) for your own API key.
|
||||
|
||||
|
||||
_definition: **Supported Networks**
|
||||
|
||||
- Homestead (Mainnet)
|
||||
- Ropsten (proof-of-work testnet)
|
||||
- Rinkeby (proof-of-authority testnet)
|
||||
- Görli (clique testnet)
|
||||
- Kovan (proof-of-authority testnet)
|
||||
|
||||
_code: Etherscan Examples @lang<javascript>
|
||||
|
||||
//_hide: const EtherscanProvider = ethers.providers.EtherscanProvider;
|
||||
//_hide: const apiKey = "...";
|
||||
|
||||
// Connect to mainnet (homestead)
|
||||
provider = new EtherscanProvider();
|
||||
|
||||
// Connect to rinkeby testnet (these are equivalent)
|
||||
provider = new EtherscanProvider("rinkeby");
|
||||
provider = new EtherscanProvider(4);
|
||||
|
||||
network = ethers.providers.getNetwork("rinkeby");
|
||||
//_hide: delete network._defaultProvider;
|
||||
//_log: network
|
||||
|
||||
provider = new EtherscanProvider(network);
|
||||
|
||||
// Connect to mainnet (homestead) with an API key
|
||||
provider = new EtherscanProvider(null, apiKey);
|
||||
provider = new EtherscanProvider("homestead", apiKey);
|
||||
|
||||
|
||||
_property: provider.getHistory(address) => Array<History> @src<providers>
|
||||
@TODO... Explain
|
||||
|
||||
|
||||
_subsection: InfuraProvider @<InfuraProvider> @INHERIT<[[UrlJsonRpcProvider]]> @src<providers:class.InfuraProvider>
|
||||
|
||||
The **InfuraProvider** is backed by the popular [INFURA](link-infura)
|
||||
Ethereum service.
|
||||
|
||||
_property: new ethers.providers.InfuraProvider([ network = "homestead", [ apiKey ] ]) @SRC<providers>
|
||||
Create a new **InfuraProvider** connected to //network// with
|
||||
the optional //apiKey//.
|
||||
|
||||
The //network// may be specified as a **string** for a common
|
||||
network name, a **number** for a common chain ID or a
|
||||
[Network Object]provider-(network).
|
||||
|
||||
The //apiKey// can be a **string** Project ID or an **object**
|
||||
with the properties ``projectId`` and ``projectSecret`` to
|
||||
specify a [Project Secret](link-infura-secret) which can be used
|
||||
on non-public sources (like on a server) to further secure your
|
||||
API access and quotas.
|
||||
|
||||
_property: InfuraProvider.getWebSocketProvider([ network [ , apiKey ] ]) => [[WebSocketProvider]] @<InfuraProvider-getWebSocketProvider> @SRC<providers:InfuraProvider.getWebSocketProvider>
|
||||
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.
|
||||
|
||||
It is highly recommended for production, you register with
|
||||
[INFURA](link-infura) for your own API key.
|
||||
|
||||
_definition: **Supported Networks**
|
||||
|
||||
- Homestead (Mainnet)
|
||||
- Ropsten (proof-of-work testnet)
|
||||
- Rinkeby (proof-of-authority testnet)
|
||||
- Görli (clique testnet)
|
||||
- Kovan (proof-of-authority testnet)
|
||||
|
||||
_code: INFURA Examples @lang<javascript>
|
||||
|
||||
//_hide: const InfuraProvider = ethers.providers.InfuraProvider;
|
||||
//_hide: const projectId = "...";
|
||||
//_hide: const projectSecret = "...";
|
||||
|
||||
// Connect to mainnet (homestead)
|
||||
provider = new InfuraProvider();
|
||||
|
||||
// Connect to the ropsten testnet
|
||||
// (see EtherscanProvider above for other network examples)
|
||||
provider = new InfuraProvider("ropsten");
|
||||
|
||||
// Connect to mainnet with a Project ID (these are equivalent)
|
||||
provider = new InfuraProvider(null, projectId);
|
||||
provider = new InfuraProvider("homestead", projectId);
|
||||
|
||||
// Connect to mainnet with a Project ID and Project Secret
|
||||
provider = new InfuraProvider("homestead", {
|
||||
projectId: projectId,
|
||||
projectSecret: projectSecret
|
||||
});
|
||||
|
||||
// Connect to the INFURA WebSocket endpoints with a WebSocketProvider
|
||||
provider = InfuraProvider.getWebSocketProvider()
|
||||
//_hide: await provider.destroy();
|
||||
|
||||
|
||||
_subsection: AlchemyProvider @<AlchemyProvider> @inherit<[[UrlJsonRpcProvider]]> @src<providers:class.AlchemyProvider>
|
||||
|
||||
The **AlchemyProvider** is backed by [Alchemy](link-alchemy).
|
||||
|
||||
_property: new ethers.providers.AlchemyProvider([ network = "homestead", [ apiKey ] ])
|
||||
Create a new **AlchemyProvider** connected to //network// with
|
||||
the optional //apiKey//.
|
||||
|
||||
The //network// may be specified as a **string** for a common
|
||||
network name, a **number** for a common chain ID or a
|
||||
[Network Object](providers-Network).
|
||||
|
||||
_note: Note: Default API keys
|
||||
If no //apiKey// is provided, a shared API key will be used,
|
||||
which may result in reduced performance and throttled requests.
|
||||
|
||||
It is highly recommended for production, you register with
|
||||
[Alchemy](link-alchemy) for your own API key.
|
||||
|
||||
_definition: **Supported Networks**
|
||||
|
||||
- Homestead (Mainnet)
|
||||
- Ropsten (proof-of-work testnet)
|
||||
- Rinkeby (proof-of-authority testnet)
|
||||
- Görli (clique testnet)
|
||||
- Kovan (proof-of-authority testnet)
|
||||
|
||||
_code: Alchemy Examples @lang<javascript>
|
||||
|
||||
//_hide: const AlchemyProvider = ethers.providers.AlchemyProvider;
|
||||
//_hide: const apiKey = "...";
|
||||
|
||||
// Connect to mainnet (homestead)
|
||||
provider = new AlchemyProvider();
|
||||
|
||||
// Connect to the ropsten testnet
|
||||
// (see EtherscanProvider above for other network examples)
|
||||
provider = new AlchemyProvider("ropsten");
|
||||
|
||||
// Connect to mainnet with an API key (these are equivalent)
|
||||
provider = new AlchemyProvider(null, apiKey);
|
||||
provider = new AlchemyProvider("homestead", apiKey);
|
||||
|
||||
// Connect to the Alchemy WebSocket endpoints with a WebSocketProvider
|
||||
provider = AlchemyProvider.getWebSocketProvider()
|
||||
//_hide: provider.destroy();
|
||||
|
||||
|
||||
_subsection: CloudflareProvider @<CloudflareProvider> @inherit<[[UrlJsonRpcProvider]]> @src<providers:class.CloudflareProvider>
|
||||
|
||||
The CloudflareProvider is backed by the [Cloudflare Ethereum Gateway](link-cloudflare).
|
||||
|
||||
_property: new ethers.providers.CloudflareProvider()
|
||||
Create a new **CloudflareProvider** connected to mainnet (i.e. "homestead").
|
||||
|
||||
_definition: **Supported Networks**
|
||||
|
||||
- Homestead (Mainnet)
|
||||
|
||||
_code: Cloudflare Examples @lang<javascript>
|
||||
|
||||
//_hide: const CloudflareProvider = ethers.providers.CloudflareProvider;
|
||||
|
||||
// Connect to mainnet (homestead)
|
||||
provider = new CloudflareProvider();
|
||||
131
docs.wrm/api/providers/index.wrm
Normal file
131
docs.wrm/api/providers/index.wrm
Normal file
@ -0,0 +1,131 @@
|
||||
_section: Providers @<providers>
|
||||
|
||||
A **Provider** is an abstraction of a connection to the
|
||||
Ethereum network, providing a concise, consistent interface
|
||||
to standard Ethereum node functionality.
|
||||
|
||||
The ethers.js library provides several options which should
|
||||
cover the vast majority of use-cases, but also includes the
|
||||
necessary functions and classes for sub-classing if a more
|
||||
custom configuration is necessary.
|
||||
|
||||
Most users should use the [[providers-getDefaultProvider]].
|
||||
|
||||
|
||||
_subsection: Default Provider @<providers-getDefaultProvider>
|
||||
|
||||
The default provider is the safest, easiest way to begin
|
||||
developing on //Ethereum//, and it is also robust enough
|
||||
for use in production.
|
||||
|
||||
It creates a [[FallbackProvider]] connected to as many backend
|
||||
services as possible. When a request is made, it is sent to
|
||||
multiple backends simultaneously. As responses from each backend
|
||||
are returned, they are checked that they agree. Once a quorum
|
||||
has been reached (i.e. enough of the backends agree), the response
|
||||
is provided to your application.
|
||||
|
||||
This ensures that if a backend has become out-of-sync, or if it
|
||||
has been compromised that its responses are dropped in favor of
|
||||
responses that match the majority.
|
||||
|
||||
_property: ethers.getDefaultProvider([ network, [ options ] ]) => [[Provider]]
|
||||
Returns a new Provider, backed by multiple services, connected
|
||||
to //network//. If no //network// is provided, **homestead**
|
||||
(i.e. mainnet) is used.
|
||||
|
||||
The //network// may also be a URL to connect to, such as ``http:/\/localhost:8545``
|
||||
or ``wss:/\/example.com``.
|
||||
|
||||
The //options// is an object, with the following properties:
|
||||
|
||||
_table: Option Properties
|
||||
|
||||
$Alchemy: [[link-alchemy]] API Token
|
||||
$Etherscan: [[link-etherscan]] API Token
|
||||
$Infura: [[link-infura]] Project ID or ``{ projectId, projectSecret }``
|
||||
$Pocket: [[link-pocket]] Application ID or ``{ applicationId, applicationSecretKey }``
|
||||
$Quorum: The number of backends that must agree
|
||||
//(default: 2 for mainnet, 1 for testnets)//
|
||||
|
||||
| **Property** | **Description** |
|
||||
| //alchemy// | $Alchemy |
|
||||
| //etherscan// | $Etherscan |
|
||||
| //infura// | $Infura |
|
||||
| //pocket// | $Pocket |
|
||||
| //quorum// | $Quorum |
|
||||
|
||||
_note: Note: API Keys
|
||||
|
||||
It is highly recommended for production services to acquire
|
||||
and specify an API Key for each service.
|
||||
|
||||
The default API Keys used by ethers are shared across all users,
|
||||
so services may throttle all services that are using the default
|
||||
API Keys during periods of load without realizing it.
|
||||
|
||||
Many services also have monitoring and usage metrics, which are
|
||||
only available if an API Key is specified. This allows tracking
|
||||
how many requests are being sent and which methods are being
|
||||
used the most.
|
||||
|
||||
Some services also provide additional paid features, which are only
|
||||
available when specifying an API Key.
|
||||
|
||||
_subsection: Networks
|
||||
|
||||
There are several official common Ethereum networks as well as custom
|
||||
networks and other compatible projects.
|
||||
|
||||
Any API that accept a [[providers-Networkish]] can be passed a common
|
||||
name (such as ``"mainnet"`` or ``"ropsten"``) or chain ID to use that
|
||||
network definition or may specify custom parameters.
|
||||
|
||||
_property: ethers.providers.getNetwork(aNetworkish) => [[providers-Network]]
|
||||
|
||||
Returns the full [[providers-Network]] for the given standard
|
||||
//aNetworkish// [[providers-Networkish]].
|
||||
|
||||
This is useful for functions and classes which wish to accept [[providers-Networkish]]
|
||||
as an input parameter.
|
||||
|
||||
_code: @lang<javascript>
|
||||
|
||||
//_hide: const getNetwork = ethers.providers.getNetwork;
|
||||
|
||||
// By Chain Name
|
||||
//_result:
|
||||
getNetwork("homestead");
|
||||
//_hide: delete _._defaultProvider;
|
||||
//_log:
|
||||
|
||||
// By Chain ID
|
||||
//_result:
|
||||
getNetwork(1);
|
||||
//_hide: delete _._defaultProvider;
|
||||
//_log:
|
||||
|
||||
_heading: Custom ENS Contract
|
||||
|
||||
One common reason to specify custom properties for a [[providers-Network]] is to override
|
||||
the address of the root ENS registry, either on a common network to intercept
|
||||
the [ENS Methods](Provider--ens-methods) or to specify the ENS registry on a
|
||||
dev network (on most dev networks you must deploy the ENS contracts manually).
|
||||
|
||||
_code: Example: Override the ENS registry @lang<script>
|
||||
|
||||
const network = {
|
||||
name: "dev",
|
||||
chianId: 1337,
|
||||
ensAddress: customEnsAddress
|
||||
};
|
||||
|
||||
|
||||
_subsection: Provider Documentation
|
||||
|
||||
_toc:
|
||||
provider
|
||||
jsonrpc-provider
|
||||
api-providers
|
||||
other
|
||||
types
|
||||
94
docs.wrm/api/providers/jsonrpc-provider.wrm
Normal file
94
docs.wrm/api/providers/jsonrpc-provider.wrm
Normal file
@ -0,0 +1,94 @@
|
||||
_section: JsonRpcProvider @<JsonRpcProvider> @INHERIT<[[Provider]]> @SRC<providers:class.JsonRpcProvider>
|
||||
|
||||
The [JSON-RPC API](link-jsonrpc) is a popular method for interacting
|
||||
with Ethereum and is available in all major Ethereum node implementations
|
||||
(e.g. [[link-geth]] and [[link-parity]]) as well as many
|
||||
third-party web services (e.g. [[link-infura]])
|
||||
|
||||
_property: new ethers.providers.JsonRpcProvider([ urlOrConnectionInfo [ , networkish ] ]) @SRC<providers:constructor.JsonRpcProvider>
|
||||
Connect to a JSON-RPC HTTP API using the URL or [[ConnectionInfo]] //urlOrConnectionInfo//
|
||||
connected to the //networkish// network.
|
||||
|
||||
If //urlOrConnectionInfo// is not specified, the default (i.e. ``http:/\/localhost:8545``)
|
||||
is used and if no network is specified, it will be determined automatically by querying the
|
||||
node using ``eth_chaindId`` and falling back on ``eth_networkId``.
|
||||
|
||||
_note: Note: Connecting to a Local Node
|
||||
Each node implementation is slightly different and may require specific
|
||||
command-line flags, configuration or settings in their UI to enable
|
||||
JSON-RPC, unlock accounts or expose specific APIs. Please consult
|
||||
their documentation.
|
||||
|
||||
_property: jsonRpcProvider.getSigner([ addressOrIndex ]) => [[JsonRpcSigner]] @<JsonRpcProvider-getSigner> @SRC<providers/json-rpc-provider>
|
||||
Returns a [[JsonRpcSigner]] which is managed by this Ethereum node, at
|
||||
//addressOrIndex//. If no //addressOrIndex// is provided, the first
|
||||
account (account #0) is used.
|
||||
|
||||
_property: jsonRpcProvider.getUncheckedSigner([ addressOrIndex ]) => [[UncheckedJsonRpcSigner]] @<JsonRpcProvider-getUncheckedSigner> @SRC<providers/json-rpc-provider>
|
||||
|
||||
_property: jsonRpcProvider.listAccounts() => Array<string> @<JsonRpcProvider-listAccounts> @SRC<providers/json-rpc-provider>
|
||||
Returns a list of all account addresses managed by this provider.
|
||||
|
||||
_property: jsonRpcProvider.send(method, params) => Promise<any> @<JsonRpcProvider-send> @SRC<providers/json-rpc-provider>
|
||||
Allows sending raw messages to the provider.
|
||||
|
||||
This can be used for backend-specific calls, such as for debugging or
|
||||
specific account management.
|
||||
|
||||
|
||||
_subsection: JsonRpcSigner @<JsonRpcSigner> @INHERIT<[[Signer]]> @SRC<providers:class.JsonRpcSigner>
|
||||
A **JsonRpcSigner** is a simple Signer which is backed by a connected
|
||||
[[JsonRpcProvider]].
|
||||
|
||||
_property: signer.provider => [[JsonRpcProvider]]
|
||||
The provider this signer was established from.
|
||||
|
||||
_property: signer.connectUnchecked() => [[UncheckedJsonRpcSigner]] @<JsonRpcSigner-connectUnchecked> @SRC<providers>
|
||||
Returns a new Signer object which does not perform additional checks when
|
||||
sending a transaction. See [getUncheckedSigner](JsonRpcProvider-getUncheckedSigner) for more details.
|
||||
|
||||
_property: signer.sendUncheckedTransaction(transaction) => Promise<string<[[DataHexString]]\<32>\>> @<JsonRpcSigner-sendUncheckedTransaction> @SRC<providers>
|
||||
Sends the //transaction// and returns a Promise which resolves to the
|
||||
opaque transaction hash.
|
||||
|
||||
_property: signer.unlock(password) => Promise<boolean> @<JsonRpcSigner-unlock> @SRC<providers>
|
||||
Request the node unlock the account (if locked) using //password//.
|
||||
|
||||
|
||||
_subsection: JsonRpcUncheckedSigner @<UncheckedJsonRpcSigner> @INHERIT<[[Signer]]> @SRC<providers:class.UncheckedJsonRpcSigner>
|
||||
The JSON-RPC API only provides a transaction hash as the response when a
|
||||
transaction is sent, but the ethers Provider requires populating all details
|
||||
of a transaction before returning it. For example, the gas price and gas limit
|
||||
may be adjusted by the node or the nonce automatically included, in which case
|
||||
the opaque transaction hash has discarded this.
|
||||
|
||||
To remedy this, the [[JsonRpcSigner]] immediately queries the provider for
|
||||
the details using the returned transaction hash to populate the [[providers-TransactionResponse]]
|
||||
object.
|
||||
|
||||
Some backends do not respond immediately and instead defer releasing the
|
||||
details of a transaction it was responsible for signing until it is mined.
|
||||
|
||||
The **UncheckedSigner** does not populate any additional information and will
|
||||
immediately return the result as a mock [[providers-TransactionResponse]]-like
|
||||
object, with most of the properties set to null, but allows access to the
|
||||
transaction hash quickly, if that is all that is required.
|
||||
|
||||
|
||||
_subsection: Node-Specific Methods @<JsonRpcProvider--other>
|
||||
|
||||
Many methods are less common or specific to certain Ethereum Node implementations
|
||||
(e.g. [Parity](link-parity) vs [Geth](link-geth). These include account and admin management,
|
||||
debugging, deeper block and transaction exploration and other services (such as
|
||||
Swarm and Whisper).
|
||||
|
||||
The [jsonRpcProvider.send](JsonRpcProvider-send) method can be used to access these.
|
||||
|
||||
- [All JSON-RPC methods](link-json-rpc) (including the less common methods) which most
|
||||
Ethereum Nodes support.
|
||||
- [Parity's Trace Module](link-parity-trace) can be used to trace and debug EVM
|
||||
execution of a transaction (requires custom configuration)
|
||||
- [Geth's Debug Module](link-geth-debug) can be used to debug transactions and
|
||||
internal cache state, etc.
|
||||
- [Additional Geth Methods](link-geth-rpc)
|
||||
- [Additional Parity Methods](link-parity-rpc)
|
||||
161
docs.wrm/api/providers/other.wrm
Normal file
161
docs.wrm/api/providers/other.wrm
Normal file
@ -0,0 +1,161 @@
|
||||
_section: Other Providers
|
||||
|
||||
_subsection: FallbackProvider @<FallbackProvider> @INHERIT<[[Provider]]> @SRC<providers/fallback-provider:class.FallbackProvider>
|
||||
|
||||
The **FallbackProvider** is the most advanced [[Provider]] available in
|
||||
ethers.
|
||||
|
||||
It uses a quorum and connects to multiple [Providers](Provider) as backends,
|
||||
each configured with a //priority// and a //weight// .
|
||||
|
||||
When a request is made, the request is dispatched to multiple backends, randomly
|
||||
chosen (lower-value priority backends are always selected first) and the results from
|
||||
each are compared against the others. Only once the quorum has been reached will that
|
||||
result be accepted and returned to the caller.
|
||||
|
||||
By default the quorum requires 50% (rounded up) of the backends to agree. The //weight//
|
||||
can be used to give a backend Provider more influence.
|
||||
|
||||
_property: new ethers.providers.FallbackProvider(providers [ , quorum ])
|
||||
Creates a new instance of a FallbackProvider connected to //providers//. If
|
||||
quorum is not specified, half of the total sum of the provider weights is
|
||||
used.
|
||||
|
||||
The //providers// can be either an array of [[Provider]] or [[FallbackProviderConfig]].
|
||||
If a [[Provider]] is provided, the defaults are a priority of 1 and a weight of 1.
|
||||
|
||||
_property: provider.providerConfigs => Array<[[FallbackProviderConfig]]>
|
||||
The list of Provider Configurations that describe the backends.
|
||||
|
||||
_property: provider.quorum => number
|
||||
The quorum the backend responses must agree upon before a result will be
|
||||
resolved. By default this is //half the sum of the weights//.
|
||||
|
||||
|
||||
_heading: FallbackProviderConfig @<FallbackProviderConfig>
|
||||
|
||||
_property: fallbackProviderConfig.provider => [[Provider]]
|
||||
The provider for this configuration.
|
||||
|
||||
_property: fallbackProviderConfig.priority => number
|
||||
The priority used for the provider. Lower-value priorities are favoured over
|
||||
higher-value priorities. If multiple providers share the same priority, they
|
||||
are chosen at random.
|
||||
|
||||
_property: fallbackProviderConfig.stallTimeout => number
|
||||
The timeout (in ms) after which another [[Provider]] will be attempted. This
|
||||
does not affect the current Provider; if it returns a result it is counted
|
||||
as part of the quorum.
|
||||
|
||||
Lower values will result in more network traffic, but may reduce the response
|
||||
time of requests.
|
||||
|
||||
_property: fallbackProviderConfig.weight => number
|
||||
The weight a response from this provider provides. This can be used if a given
|
||||
[[Provider]] is more trusted, for example.
|
||||
|
||||
|
||||
_subsection: IpcProvider @<IpcProvider> @INHERIT<[[JsonRpcProvider]]> @SRC<providers:class.IpcProvider>
|
||||
|
||||
The **IpcProvider** allows the JSON-RPC API to be used over a local
|
||||
filename on the file system, exposed by Geth, Parity and other nodes.
|
||||
|
||||
This is only available in //node.js// (as it requires file system access,
|
||||
and may have additional complications due to file permissions. See any
|
||||
related notes on the documentation for the actual node implementation websites.
|
||||
|
||||
_property: ipcProvider.path => string
|
||||
The path this [[Provider]] is connected to.
|
||||
|
||||
|
||||
_subsection: UrlJsonRpcProvider @<UrlJsonRpcProvider> @INHERIT<[[JsonRpcProvider]]> @SRC<providers:class.UrlJsonRpcProvider>
|
||||
|
||||
This class is intended to be sub-classed and not used directly. It
|
||||
simplifies creating a [[Provider]] where a normal [[JsonRpcProvider]]
|
||||
would suffice, with a little extra effort needed to generate the JSON-RPC
|
||||
URL.
|
||||
|
||||
_property: new ethers.providers.UrlJsonRpcProvider([ network [ , apiKey ] ])
|
||||
Sub-classes do not need to override this. Instead they should override the
|
||||
static method ``getUrl`` and optionally ``getApiKey``.
|
||||
|
||||
_property: urlJsonRpcProvider.apiKey => any
|
||||
The value of the apiKey that was returned from ``InheritedClass.getApiKey``.
|
||||
|
||||
_property: InheritingClass.getApiKey(apiKey) => any
|
||||
This function should examine the //apiKey// to ensure it is valid and
|
||||
return a (possible modified) value to use in ``getUrl``.
|
||||
|
||||
_property: InheritingClass.getUrl(network, apiKey) => string
|
||||
The URL to use for the JsonRpcProvider instance.
|
||||
|
||||
|
||||
|
||||
_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 wrapping an existing Web3-compatible (such as a
|
||||
[Web3HttpProvider](link-web3-http), [Web3IpcProvider](link-web3-ipc) or
|
||||
[Web3WsProvider](link-web3-ws)) and exposing it as an ethers.js [[Provider]]
|
||||
which can then be used with the rest of the library.
|
||||
|
||||
This may also be used to wrap a standard [EIP-1193 Provider](link-eip-1193].
|
||||
|
||||
_property: new ethers.providers.Web3Provider(externalProvider [, network ])
|
||||
Create a new **Web3Provider**, which wraps an [EIP-1193 Provider](link-eip-1193) or
|
||||
Web3Provider-compatible Provider.
|
||||
|
||||
_property: web3Provider.provider => Web3CompatibleProvider
|
||||
The provider used to create this instance.
|
||||
|
||||
_heading: ExternalProvider @<Web3Provider--ExternalProvider>
|
||||
|
||||
An **ExternalProvider** can be either one for the above mentioned Web3
|
||||
Providers (or otherwise compatible) or an [[link-eip-1193]] provider.
|
||||
|
||||
An ExternalProvider must offer one of the following signatures, and the
|
||||
first matching is used:
|
||||
|
||||
_property: externalProvider.request(request) => Promise<any>
|
||||
|
||||
This follows the [[link-eip-1193]] API signature.
|
||||
|
||||
The //request// should be a standard JSON-RPC payload, which should at
|
||||
a minimum specify the ``method`` and ``params``.
|
||||
|
||||
The result should be the actual result, which differs from the Web3.js
|
||||
response, which is a wrapped JSON-RPC response.
|
||||
|
||||
_property: externalProvider.sendAsync(request, callback) => void
|
||||
|
||||
This follows the [Web3.js Provider Signature](link-web3-send).
|
||||
|
||||
The //request// should be a standard JSON-RPC payload, which should at
|
||||
a minimum specify the ``method`` and ``params``.
|
||||
|
||||
The //callback// should use the error-first calling semantics, so
|
||||
``(error, result)`` where the result is a JSON-RPC wrapped result.
|
||||
|
||||
_property: externalProvider.send(request, callback) => void
|
||||
|
||||
This is identical to ``sendAsync``. Historically, this used a synchronous
|
||||
web request, but no current browsers support this, so its use this way
|
||||
was deprecated quite a long time ago
|
||||
|
||||
|
||||
_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 resources, 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.providers.WebSocketProvider([ 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.
|
||||
511
docs.wrm/api/providers/provider.wrm
Normal file
511
docs.wrm/api/providers/provider.wrm
Normal file
@ -0,0 +1,511 @@
|
||||
_section: Provider @<Provider>
|
||||
|
||||
A **Provider** in ethers is a read-only abstraction to
|
||||
access the blockchain data.
|
||||
|
||||
_note: Coming from Web3.js?
|
||||
If you are coming from Web3.js, this is one of the biggest
|
||||
differences you will encounter using ethers.
|
||||
|
||||
The ethers library creates a strong division between the
|
||||
operation a **Provider** can perform and those of a [[Signer]],
|
||||
which Web3.js lumps together.
|
||||
|
||||
This separation of concerns and a stricted subset of Provider
|
||||
operations allows for a larger variety of backends, a more
|
||||
consistent API and ensures other libraries to operate without
|
||||
being able to rely on any underlying assumption.
|
||||
|
||||
_subsection: Accounts Methods @<Provider--account-methods>
|
||||
|
||||
_property: provider.getBalance(address [ , blockTag = latest ]) => Promise<[[BigNumber]]> @<Provider-getBalance> @SRC<providers/base-provider>
|
||||
Returns the balance of //address// as of the //blockTag// block height.
|
||||
|
||||
_code: @lang<javascript>
|
||||
|
||||
//_result:
|
||||
await provider.getBalance("ricmoo.eth");
|
||||
//_log:
|
||||
|
||||
_property: provider.getCode(address [ , blockTag = latest ]) => Promise<string<[[DataHexString]]>> @<Provider-getCode> @SRC<providers/base-provider>
|
||||
Returns the contract code of //address// as of the //blockTag// block height. If there is
|
||||
no contract currently deployed, the result is ``0x``.
|
||||
|
||||
_code: @lang<javascript>
|
||||
|
||||
//_result:
|
||||
await provider.getCode("registrar.firefly.eth");
|
||||
//_log:
|
||||
|
||||
_property: provider.getStorageAt(addr, pos [ , blockTag = latest ]) => Promise<string<[[DataHexString]]>> @<Provider-getStorageAt> @SRC<providers/base-provider>
|
||||
Returns the ``Bytes32`` value of the position //pos// at address //addr//, as of the //blockTag//.
|
||||
|
||||
_code: @lang<javascript>
|
||||
|
||||
//_result:
|
||||
await provider.getStorageAt("registrar.firefly.eth", 0)
|
||||
//_log:
|
||||
|
||||
_property: provider.getTransactionCount(address [ , blockTag = latest ]) => Promise<number> @<Provider-getTransactionCount> @SRC<providers/base-provider>
|
||||
Returns the number of transactions //address// has ever **sent**, as of //blockTag//.
|
||||
This value is required to be the nonce for the next transaction from //address//
|
||||
sent to the network.
|
||||
|
||||
_code: @lang<javascript>
|
||||
|
||||
//_result:
|
||||
await provider.getTransactionCount("ricmoo.eth");
|
||||
//_log:
|
||||
|
||||
|
||||
_subsection: Blocks Methods @<Provider--block-methods>
|
||||
|
||||
_property: provider.getBlock(block) => Promise<[[providers-Block]]> @<Provider-getBlock> @SRC<providers/base-provider>
|
||||
Get the //block// from the network, where the ``result.transactions`` is a list
|
||||
of transaction hashes.
|
||||
|
||||
_code: @lang<javascript>
|
||||
|
||||
//_result:
|
||||
await provider.getBlock(100004)
|
||||
//_log:
|
||||
|
||||
_property: provider.getBlockWithTransactions(block) => Promise<[[providers-BlockWithTransactions]]> @<Provider-getBlockWithTransactions> @SRC<providers/base-provider>
|
||||
Get the //block// from the network, where the ``result.transactions`` is
|
||||
an Array of [[providers-TransactionResponse]] objects.
|
||||
|
||||
_code: @lang<javascript>
|
||||
|
||||
//_result:
|
||||
await provider.getBlockWithTransactions(100004)
|
||||
//_log:
|
||||
|
||||
_subsection: Ethereum Naming Service (ENS) Methods @<Provider--ens-methods>
|
||||
|
||||
The [Ethereum Naming Service](link-ens) (ENS) allows a short and
|
||||
easy-to-remember ENS Name to be attached to any set of keys
|
||||
and values.
|
||||
|
||||
One of the most common uses for this is to use a simple name to
|
||||
refer to an [Ethereum Address](address).
|
||||
|
||||
In the ethers API, nearly anywhere that accepts an address, an
|
||||
ENS name may be used instead, which can simplify code and make
|
||||
reading and debugging much simpler.
|
||||
|
||||
The provider offers some basic operations to help resolve and
|
||||
work with ENS names.
|
||||
|
||||
_property: provider.getResolver(name) => Promise<[[EnsResolver]]>
|
||||
Returns an EnsResolver instance which can be used to further inquire
|
||||
about specific entries for an ENS name.
|
||||
|
||||
_code: @lang<javascript>
|
||||
|
||||
//_hide: provider = ethers.getDefaultProvider();
|
||||
|
||||
// See below (Resolver) for examples of using this object
|
||||
const resolver = await provider.getResolver("ricmoo.eth");
|
||||
|
||||
//_hide: _page.resolver = resolver;
|
||||
|
||||
_property: provider.lookupAddress(address) => Promise<string> @<Provider-lookupAddress> @SRC<providers/base-provider>
|
||||
Performs a reverse lookup of the //address// in ENS using the
|
||||
//Reverse Registrar//. If the name does not exist, or the
|
||||
forward lookup does not match, ``null`` is returned.
|
||||
|
||||
An ENS name requries additional configuration to setup a reverse
|
||||
record, they are not automatically set up.
|
||||
|
||||
_code: @lang<javascript>
|
||||
|
||||
//_result:
|
||||
await provider.lookupAddress("0x5555763613a12D8F3e73be831DFf8598089d3dCa");
|
||||
//_log:
|
||||
|
||||
_property: provider.resolveName(name) => Promise<string<[Address](address)>> @<Provider-ResolveName> @SRC<providers/base-provider>
|
||||
Looks up the address of //name//. If the name is not owned, or
|
||||
does not have a //Resolver// configured, or the //Resolver// does
|
||||
not have an address configured, ``null`` is returned.
|
||||
|
||||
_code: @lang<javascript>
|
||||
|
||||
//_result:
|
||||
await provider.resolveName("ricmoo.eth");
|
||||
//_log:
|
||||
|
||||
|
||||
_subsection: EnsResolver @<EnsResolver>
|
||||
|
||||
_property: resolver.name => string
|
||||
The name of this resolver.
|
||||
|
||||
_property: resolver.address => string<[[address]]>
|
||||
The address of the Resolver.
|
||||
|
||||
_property: resolver.getAddress([ cointType = 60 ]) => Promise<string>
|
||||
Returns a Promise which resolves to the [[link-eip-2304]] multicoin address
|
||||
stored for the //coinType//. By default an Ethereum [[address]]
|
||||
(``coinType = 60``) will be returned.
|
||||
|
||||
_code: @lang<javascript>
|
||||
|
||||
//_hide: const resolver = _page.resolver;
|
||||
|
||||
// By default, looks up the Ethereum address
|
||||
// (this will match provider.resolveName)
|
||||
//_result:
|
||||
await resolver.getAddress();
|
||||
//_log:
|
||||
|
||||
// Specify the coinType for other coin addresses (0 = Bitcoin)
|
||||
//_result:
|
||||
await resolver.getAddress(0);
|
||||
//_log:
|
||||
|
||||
_property: resolver.getContentHash() => Promise<string>
|
||||
Returns a Promise which resolves to any stored [[link-eip-1577]] content hash.
|
||||
|
||||
_code: @lang<javascript>
|
||||
|
||||
//_hide: const resolver = _page.resolver;
|
||||
|
||||
//_result:
|
||||
await resolver.getContentHash();
|
||||
//_log:
|
||||
|
||||
_property: resolver.getText(key) => Promise<string>
|
||||
Returns a Promise which resolves to any stored [[link-eip-634]] text entry for //key//.
|
||||
|
||||
_code: @lang<javascript>
|
||||
|
||||
//_hide: const resolver = _page.resolver;
|
||||
|
||||
//_result:
|
||||
await resolver.getText("email");
|
||||
//_log:
|
||||
|
||||
//_result:
|
||||
await resolver.getText("url");
|
||||
//_log:
|
||||
|
||||
//_result:
|
||||
await resolver.getText("com.twitter");
|
||||
//_log:
|
||||
|
||||
_subsection: Logs Methods @<Provider--log-methods>
|
||||
|
||||
_property: provider.getLogs(filter) => Promise<Array<[[providers-Log]]>> @<Provider-getLogs> @SRC<providers/base-provider>
|
||||
Returns the Array of [[providers-Log]] matching the //filter//.
|
||||
|
||||
Keep in mind that many backends will discard old events, and that requests
|
||||
which are too broad may get dropped as they require too many resources to
|
||||
execute the query.
|
||||
|
||||
|
||||
_subsection: Network Status Methods @<Provider--network-methods>
|
||||
|
||||
_property: provider.getNetwork() => Promise<[[providers-Network]]> @<Provider-getNetwork> @SRC<providers/base-provider:method.BaseProvider.getNetwork>
|
||||
Returns the [[providers-Network]] this Provider is connected to.
|
||||
|
||||
_code: @lang<javascript>
|
||||
|
||||
//_result:
|
||||
await provider.getNetwork()
|
||||
//_hide: _ = utils.shallowCopy(_);
|
||||
//_hide: delete _._defaultProvider;
|
||||
//_log:
|
||||
|
||||
_property: provider.getBlockNumber() => Promise<number> @<Provider-getBlockNumber> @SRC<providers/base-provider>
|
||||
Returns the block number (or height) of the most recently mined block.
|
||||
|
||||
_code: @lang<javascript>
|
||||
|
||||
//_result:
|
||||
await provider.getBlockNumber()
|
||||
//_log:
|
||||
|
||||
_property: provider.getGasPrice() => Promise<[[BigNumber]]> @<Provider-getGasPrice> @SRC<providers/base-provider>
|
||||
Returns a //best guess// of the [[gas-price]] to use in a transaction.
|
||||
|
||||
_code: @lang<javascript>
|
||||
|
||||
// The gas price (in wei)...
|
||||
gasPrice = await provider.getGasPrice()
|
||||
//_log: gasPrice
|
||||
|
||||
// ...often this gas price is easier to understand or
|
||||
// display to the user in gwei
|
||||
//_result:
|
||||
utils.formatUnits(gasPrice, "gwei")
|
||||
//_log:
|
||||
|
||||
_property: provider.ready => Promise<[[providers-Network]]> @<Provider-ready> @src<providers/base-provider>
|
||||
Returns a Promise which will stall until the network has heen established,
|
||||
ignoring errors due to the target node not being active yet.
|
||||
|
||||
This can be used for testing or attaching scripts to wait until the node is
|
||||
up and running smoothly.
|
||||
|
||||
|
||||
_subsection: Transactions Methods @<Provider--transaction-methods>
|
||||
|
||||
_property: provider.call(transaction [ , blockTag = latest ]) => Promise<string<[[DataHexString]]>> @<Provider-call> @SRC<providers/base-provider>
|
||||
Returns the result of executing the //transaction//, using //call//. A call
|
||||
does not require any ether, but cannot change any state. This is useful
|
||||
for calling getters on Contracts.
|
||||
|
||||
_code: @lang<javascript>
|
||||
|
||||
//_result:
|
||||
await provider.call({
|
||||
// ENS public resovler address
|
||||
to: "0x4976fb03C32e5B8cfe2b6cCB31c09Ba78EBaBa41",
|
||||
|
||||
// `function addr(namehash("ricmoo.eth")) view returns (address)`
|
||||
data: "0x3b3b57debf074faa138b72c65adbdcfb329847e4f2c04bde7f7dd7fcad5a52d2f395a558"
|
||||
});
|
||||
//_log:
|
||||
|
||||
_property: provider.estimateGas(transaction) => Promise<[[BigNumber]]> @<Provider-estimateGas> @SRC<providers/base-provider>
|
||||
Returns an estimate of the amount of gas that would be required to submit //transaction//
|
||||
to the network.
|
||||
|
||||
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.
|
||||
|
||||
_code: @lang<javascript>
|
||||
|
||||
//_hide: const parseEther = ethers.utils.parseEther;
|
||||
|
||||
//_result:
|
||||
await provider.estimateGas({
|
||||
// Wrapped ETH address
|
||||
to: "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
|
||||
|
||||
// `function deposit() payable`
|
||||
data: "0xd0e30db0",
|
||||
|
||||
// 1 ether
|
||||
value: parseEther("1.0")
|
||||
});
|
||||
//_log:
|
||||
|
||||
_property: provider.getTransaction(hash) => Promise<[[providers-TransactionResponse]]> @<Provider-getTransaction> @src<providers/base-provider>
|
||||
Returns the transaction with //hash// or null if the transaction is unknown.
|
||||
|
||||
If a transaction has not been mined, this method will search the transaction
|
||||
pool. Various backends may have more restrictive transaction pool access (e.g.
|
||||
if the gas price is too low or the transaction was only recently sent and not
|
||||
yet indexed) in which case this method may also return null.
|
||||
|
||||
_code: @lang<javascript>
|
||||
|
||||
//_result:
|
||||
await provider.getTransaction("0x5b73e239c55d790e3c9c3bbb84092652db01bb8dbf49ccc9e4a318470419d9a0");
|
||||
//_log:
|
||||
|
||||
_property: provider.getTransactionReceipt(hash) => Promise<[[providers-TransactionReceipt]]> @<Provider-getTransactionReceipt> @src<providers/base-provider>
|
||||
Returns the transaction receipt for //hash// or null if the transaction
|
||||
has not been mined.
|
||||
|
||||
To stall until the transaction has been mined, consider the ``waitForTransaction``
|
||||
method below.
|
||||
|
||||
_code: @lang<javascript>
|
||||
|
||||
//_result:
|
||||
await provider.getTransactionReceipt("0x5b73e239c55d790e3c9c3bbb84092652db01bb8dbf49ccc9e4a318470419d9a0");
|
||||
//_log:
|
||||
|
||||
_property: provider.sendTransaction(transaction) => Promise<[[providers-TransactionResponse]]> @<Provider-sendTransaction> @SRC<providers/base-provider>
|
||||
Submits //transaction// to the network to be mined. The //transaction// **must** be signed,
|
||||
and be valid (i.e. the nonce is correct and the account has sufficient balance to pay
|
||||
for the transaction).
|
||||
|
||||
_code: @lang<javascript>
|
||||
|
||||
//_hide: const provider = localProvider;
|
||||
//_hide: const wallet = new ethers.Wallet(ethers.utils.id("HelloWorld"), provider);
|
||||
//_hide: const fundTx = await localSigner.sendTransaction({
|
||||
//_hide: to: wallet.address,
|
||||
//_hide: value: ethers.utils.parseEther("2.0")
|
||||
//_hide: });
|
||||
//_hide: await fundTx.wait();
|
||||
|
||||
//_result:
|
||||
await provider.sendTransaction("0xf86e808502540be400825208948ba1f109551bd432803012645ac136ddd64dba72880de0b6b3a764000080820a96a0f0c5bcb11e5a16ab116c60a0e5837ae98ec36e7f217740076572e8183002edd2a01ed1b4411c2840b9793e8be5415a554507f1ea320069be6dcecabd7b9097dbd4");
|
||||
//_log:
|
||||
|
||||
_property: provider.waitForTransaction(hash [ , confirms = 1 [ , timeout ] ]) => Promise<[TxReceipt](providers-TransactionReceipt)> @<Provider-waitForTransaction> @SRC<providers/base-provider>
|
||||
Returns a Promise which will not resolve until //transactionHash// is mined.
|
||||
|
||||
If //confirms// is 0, this method is non-blocking and if the
|
||||
transaction has not been mined returns null. Otherwise,
|
||||
this method will block until the transaction has //confirms//
|
||||
blocks mined on top of the block in which is was mined.
|
||||
|
||||
_subsection: Event Emitter Methods @<Provider--event-methods>
|
||||
|
||||
The EventEmitter API allows applications to use an
|
||||
[[link-wiki-observer-pattern]] to register callbacks for when
|
||||
various events occur.
|
||||
|
||||
This closely follows the Event Emitter provided by other JavaScript
|
||||
libraries with the exception that event names support some more
|
||||
[complex objects](Provider--events), not only strings. The objects
|
||||
are normalized internally.
|
||||
|
||||
_property: provider.on(eventName, listener) => this @<Provider-on> @SRC<providers/base-provider>
|
||||
Add a //listener// to be triggered for each //eventName// [event](Provider--events).
|
||||
|
||||
_property: provider.once(eventName, listener) => this @<Provider-once> @SRC<providers/base-provider>
|
||||
Add a //listener// to be triggered for only the next
|
||||
//eventName// [event](Provider--events), at which time it will be removed.
|
||||
|
||||
_property: provider.emit(eventName, ...args) => boolean @<Provider-emit> @SRC<providers/base-provider>
|
||||
Notify all listeners of the //eventName// [event](Provider--events),
|
||||
passing //args// to each listener. This is generally only used internally.
|
||||
|
||||
_property: provider.off(eventName [ , listener ]) => this @<Provider-off> @SRC<providers/base-provider>
|
||||
Remove a //listener// for the //eventName// [event](Provider--events).
|
||||
If no //listener// is provided, all listeners for //eventName// are removed.
|
||||
|
||||
_property: provider.removeAllListeners([ eventName ]) => this @<Provider-removeAllListeners> @SRC<providers/base-provider>
|
||||
Remove all the listeners for the //eventName// [events](Provider--events).
|
||||
If no //eventName// is provided, **all** events are removed.
|
||||
|
||||
_property: provider.listenerCount([ eventName ]) => number @<Provider-listenerCount> @SRC<providers/base-provider>
|
||||
Returns the number of listeners for the //eventName// [events](Provider--events).
|
||||
If no //eventName// is provided, the total number of listeners is returned.
|
||||
|
||||
_property: provider.listeners(eventName) => Array<Listener> @<Provider-listeners> @SRC<providers/base-provider>
|
||||
Returns the list of Listeners for the //eventName// [events](Provider--events).
|
||||
|
||||
|
||||
_heading: Events @<Provider--events>
|
||||
|
||||
Any of the following may be used as the //eventName// in the above methods.
|
||||
|
||||
_definition: **Log Filter**
|
||||
|
||||
A filter is an object, representing a contract log Filter, which has the optional
|
||||
properties ``address`` (the source contract) and ``topics`` (a topic-set to match).
|
||||
|
||||
If ``address`` is unspecified, the filter matches any contract address.
|
||||
|
||||
See [EventFilters](providers-EventFilter) for more information on filtering events.
|
||||
|
||||
_definition: **Topic-Set Filter**
|
||||
|
||||
The value of a **Topic-Set Filter** is a array of Topic-Sets.
|
||||
|
||||
This event is identical to a //Log Filter// with the address omitted (i.e. from
|
||||
any contract).
|
||||
|
||||
See [EventFilters](providers-EventFilter) for more information on filtering events.
|
||||
|
||||
_definition: **Transaction Filter**
|
||||
|
||||
The value of a **Transaction Filter** is any transaction hash.
|
||||
|
||||
This event is emitted on every block that is part of a chain that
|
||||
includes the given mined transaction. It is much more common that the
|
||||
[once](Provider-once) method is used than the [on](Provider-on) method.
|
||||
|
||||
_null:
|
||||
|
||||
In addition to transaction and filter events, there are several named
|
||||
events.
|
||||
|
||||
_table: Named Provider Events @style<full>
|
||||
|
||||
$Block: emitted when a new block is mined
|
||||
$Error: emitted on any error
|
||||
$Pending: emitted when a new transaction enters the memory pool; only
|
||||
certain providers offer this event and may require
|
||||
running your own node for reliable results
|
||||
$WillPoll: emitted prior to a polling loop is about to begin;
|
||||
//(very rarely used by most developers)//
|
||||
$DidPoll: emitted after all events from a polling loop are emitted;
|
||||
//(very rarely used by most developers)//
|
||||
$Poll: emitted during each poll cycle after `blockNumber` is updated
|
||||
(if changed) and before any other events (if any) are emitted
|
||||
during the poll loop;
|
||||
//(very rarely used by most developers)//
|
||||
$Debug: each Provider may use this to emit useful debugging information
|
||||
and the format is up to the developer;
|
||||
//(very rarely used by most developers)//
|
||||
|
||||
| **Event Name** | **Arguments** <| **Description** <<<|
|
||||
| ``"block"`` | //blockNumber// <| $Block <<<|
|
||||
| ``"error"`` | //error// <| $Error <<<|
|
||||
| ``"pending"`` | //pendingTransaction// <| $Pending <<<|
|
||||
| ``"willPoll"`` | //pollId// <| $WillPoll <<<|
|
||||
| ``"poll"`` | //pollId//, //blockNumber// <| $Poll <<<|
|
||||
| ``"didPoll"`` | //pollId// <| $DidPoll <<<|
|
||||
| ``"debug"`` | provider dependent <| $Debug <<<|
|
||||
|
||||
|
||||
_code: Events Example @lang<javascript>
|
||||
|
||||
//_hide: const txHash = utils.id("dummy-data");
|
||||
//_hide: const myAddress = ethers.constants.HashZero;
|
||||
//_hide: const myOtherAddress = ethers.constants.HashZero;
|
||||
|
||||
provider.on("block", (blockNumber) => {
|
||||
// Emitted on every block change
|
||||
})
|
||||
|
||||
|
||||
provider.once(txHash, (transaction) => {
|
||||
// Emitted when the transaction has been mined
|
||||
})
|
||||
|
||||
|
||||
// This filter could also be generated with the Contract or
|
||||
// Interface API. If address is not specified, any address
|
||||
// matches and if topics is not specified, any log matches
|
||||
filter = {
|
||||
address: "dai.tokens.ethers.eth",
|
||||
topics: [
|
||||
utils.id("Transfer(address,address,uint256)")
|
||||
]
|
||||
}
|
||||
provider.on(filter, (log, event) => {
|
||||
// Emitted whenever a DAI token transfer occurs
|
||||
})
|
||||
|
||||
|
||||
// Notice this is an array of topic-sets and is identical to
|
||||
// using a filter with no address (i.e. match any address)
|
||||
topicSets = [
|
||||
utils.id("Transfer(address,address,uint256)"),
|
||||
null,
|
||||
[
|
||||
myAddress,
|
||||
myOtherAddress
|
||||
]
|
||||
]
|
||||
provider.on(topicSets, (log, event) => {
|
||||
// Emitted any token is sent TO either address
|
||||
})
|
||||
|
||||
|
||||
provider.on("pending", (tx) => {
|
||||
// Emitted when any new pending transaction is noticed
|
||||
});
|
||||
|
||||
|
||||
provider.on("error", (tx) => {
|
||||
// Emitted when any error occurs
|
||||
});
|
||||
|
||||
//_hide: provider.removeAllListeners() /* Make sure the docs build without waiting forever */
|
||||
|
||||
_subsection: Inspection Methods @<Provider--inspection-methods>
|
||||
|
||||
_property: Provider.isProvider(object) => boolean @<Provider-isProvider> @SRC<abstract-provider>
|
||||
Returns true if and only if //object// is a Provider.
|
||||
|
||||
451
docs.wrm/api/providers/types.wrm
Normal file
451
docs.wrm/api/providers/types.wrm
Normal file
@ -0,0 +1,451 @@
|
||||
_section: Types
|
||||
|
||||
_subsection: BlockTag @<providers-BlockTag>
|
||||
A **BlockTag** specifies a specific block location in the Blockchain.
|
||||
|
||||
- **``"latest"``** - The most recently mined block
|
||||
- **``"earliest"``** - Block #0
|
||||
- **``"pending"``** - The block currently being prepared for mining; not all
|
||||
operations and backends support this BlockTag
|
||||
- **//number//** - The block at this height
|
||||
- **//a negative number//** - The block this many blocks ago
|
||||
- **//hex string//** - The block at this height (as a hexidecimal value)
|
||||
|
||||
_subsection: Networkish @<providers-Networkish>
|
||||
A **Networkish** may be any of the following:
|
||||
|
||||
- a [[providers-Network]] object
|
||||
- the name of a common network as a string (e.g. ``"homestead"``)
|
||||
- the chain ID a network as a number; if the chain ID is that of a
|
||||
common network, the ``name`` and ``ensAddress`` will be populated, otherwise,
|
||||
the default name ``"unknown"`` and no ``ensAddress`` is used
|
||||
|
||||
_subsection: Network @<providers-Network>
|
||||
A **Network** represents an Ethereum network.
|
||||
|
||||
_property: network.name => string
|
||||
The human-readable name of the network, such as ``homestead``. If the network
|
||||
name is unknown, this will be ``"unknown"``.
|
||||
|
||||
_property: network.chainId => number
|
||||
The Chain ID of the network.
|
||||
|
||||
_property: network.ensAddress => string<[[address]]>
|
||||
The address at which the ENS registry is deployed on this network.
|
||||
|
||||
|
||||
_subsection: Block @<providers-Block>
|
||||
|
||||
_property: block.hash => string<[[DataHexString]]<32>>
|
||||
The hash of this block.
|
||||
|
||||
_property: block.parentHash => string<[[DataHexString]]<32>>
|
||||
The hash of the previous block.
|
||||
|
||||
_property: block.number => number
|
||||
The height (number) of this block.
|
||||
|
||||
_property: block.timestamp => number
|
||||
The timestamp of this block.
|
||||
|
||||
_property: block.nonce => string<[[DataHexString]]>
|
||||
The nonce used as part of the proof-of-work to mine this block.
|
||||
|
||||
This property is generally of little interest to developers.
|
||||
|
||||
_property: block.difficulty => number
|
||||
The difficulty target required to be met by the miner of the block.
|
||||
|
||||
This property is generally of little interest to developers.
|
||||
|
||||
_property: block.gasLimit => [[BigNumber]]
|
||||
The maximum amount of gas that this block was permitted to use. This
|
||||
is a value that can be voted up or voted down by miners and is used
|
||||
to automatically adjust the bandwidth requirements of the network.
|
||||
|
||||
This property is generally of little interest to developers.
|
||||
|
||||
_property: block.gasUsed => [[BigNumber]]
|
||||
The total amount of gas used by all transactions in this block.
|
||||
|
||||
_property: block.miner => string
|
||||
The coinbase address of this block, which indicates the address the
|
||||
miner that mined this block would like the subsidy reward to go to.
|
||||
|
||||
_property: block.extraData => string
|
||||
This is extra data a miner may choose to include when mining a block.
|
||||
|
||||
This property is generally of little interest to developers.
|
||||
|
||||
_heading: Block (with transaction hashes)
|
||||
|
||||
Often only the hashes of the transactions included in a block are needed,
|
||||
so by default a block only contains this information, as it is
|
||||
substantially less data.
|
||||
|
||||
_property: block.transactions => Array<string<[[DataHexString]]<32>>>
|
||||
A list of the transactions hashes for each transaction this block
|
||||
includes.
|
||||
|
||||
_heading: BlockWithTransactions @<providers-BlockWithTransactions> @INHERIT<[Block](providers-Block)>
|
||||
|
||||
If all transactions for a block are needed, this object instead includes
|
||||
the full details on each transaction.
|
||||
|
||||
_property: block.transactions => Array<[[providers-TransactionResponse]]>
|
||||
A list of the transactions this block includes.
|
||||
|
||||
|
||||
_subsection: Events and Logs
|
||||
|
||||
_heading: EventFilter @<providers-EventFilter>
|
||||
|
||||
_property: filter.address => string<[[address]]>
|
||||
The address to filter by, or ``null`` to match any address.
|
||||
|
||||
_property: filter.topics => Array<string<[Data](DataHexString)<32>> | Array<string<[Data](DataHexString)<32>>>>
|
||||
The topics to filter by or ``null`` to match any topics.
|
||||
|
||||
Each entry represents an **AND** condition that must match, or may
|
||||
be ``null`` to match anything. If a given entry is an Array, then
|
||||
that entry is treated as an **OR** for any value in the entry.
|
||||
|
||||
See [Filters](events--filters) for more details and examples
|
||||
on specifying complex filters.
|
||||
|
||||
_heading: Filter @<providers-Filter> @INHERIT<[[providers-EventFilter]]>
|
||||
|
||||
_property: filter.fromBlock => [[providers-BlockTag]]
|
||||
The starting block (inclusive) to search for logs matching the filter criteria.
|
||||
|
||||
_property: filter.toBlock => [[providers-BlockTag]]
|
||||
The end block (inclusive) to search for logs matching the filter criteria.
|
||||
|
||||
_heading: FilterByBlockHash @<providers-FilterByBlockHash> @INHERIT<[[providers-EventFilter]]>
|
||||
|
||||
_property: filter.blockHash => string<[[DataHexString]]<32>>
|
||||
The specific block (by its block hash) to search for logs matching the filter criteria.
|
||||
|
||||
|
||||
_heading: Log @<providers-Log>
|
||||
|
||||
_property: log.blockNumber => number
|
||||
The block height (number) of the block including the transaction of this log.
|
||||
|
||||
_property: log.blockHash => string<[[DataHexString]]<32>>
|
||||
The block hash of the block including the transaction of this log.
|
||||
|
||||
_property: log.removed => boolean
|
||||
During a re-org, if a transaction is orphaned, this will be set to true
|
||||
to indicate the Log entry has been removed; it will likely be emitted
|
||||
again in the near future when another block is mined with the transaction
|
||||
that triggered this log, but keep in mind the values may change.
|
||||
|
||||
_property: log.transactionLogIndex => number
|
||||
The index of this log in the transaction.
|
||||
|
||||
_property: log.address => string<[[address]]>
|
||||
The address of the contract that generated this log.
|
||||
|
||||
_property: log.data => string<[[DataHexString]]>
|
||||
The data included in this log.
|
||||
|
||||
_property: log.topics => Array<string<[[DataHexString]]<32> > >
|
||||
The list of topics (indexed properties) for this log.
|
||||
|
||||
_property: log.transactionHash => string<[[DataHexString]]<32>>
|
||||
The transaction hash of the transaction of this log.
|
||||
|
||||
_property: log.transactionIndex => number
|
||||
The index of the transaction in the block of the transaction of this log.
|
||||
|
||||
_property: log.logIndex => number
|
||||
The index of this log across all logs in the entire **block**.
|
||||
|
||||
|
||||
_subsection: Transactions
|
||||
|
||||
_heading: TransactionRequest @<providers-TransactionRequest>
|
||||
|
||||
A transaction request describes a transaction that is to
|
||||
be sent to the network or otherwise processed.
|
||||
|
||||
All fields are optional and may be a promise which resolves
|
||||
to the required type.
|
||||
|
||||
_property: transactionRequest.to => string | Promise<string>
|
||||
The address (or ENS name) this transaction it to.
|
||||
|
||||
_property: transactionRequest.from => string<[[address]]> | Promise<string<[[address]]>>
|
||||
The address this transaction is from.
|
||||
|
||||
_property: transactionRequest.nonce => number | Promise<number>
|
||||
The nonce for this transaction. This should be set to the number of
|
||||
transactions ever sent **from** this address.
|
||||
|
||||
_property: transactionRequest.gasLimit => [[BigNumber]] | Promise<[[BigNumber]]>
|
||||
The maximum amount of gas this transaction is permitted to use.
|
||||
|
||||
_property: transactionRequest.gasPrice => [[BigNumber]] | Promise<[[BigNumber]]>
|
||||
The price (in wei) per unit of gas this transaction will pay.
|
||||
|
||||
_property: transactionRequest.data => [[DataHexString]] | Promise<[[DataHexString]]>
|
||||
The transaction data.
|
||||
|
||||
_property: transactionRequest.value => [[BigNumber]] | Promise<[[BigNumber]]>
|
||||
The amount (in wei) this transaction is sending.
|
||||
|
||||
_property: transactionRequest.chainId => number | Promise<number>
|
||||
The chain ID this transaction is authorized on, as specified by
|
||||
[EIP-155](link-eip-155).
|
||||
|
||||
If the chain ID is 0 will disable EIP-155 and the transaction will be valid
|
||||
on any network. This can be **dangerous** and care should be taken, since it
|
||||
allows transactions to be replayed on networks that were possibly not
|
||||
intended. Intentionally-replayable transactions are also disabled by default
|
||||
on recent versions of Geth and require configuration to enable.
|
||||
|
||||
_property: transactionRequest.type => null | number
|
||||
|
||||
The [[link-eip-2718]] type of this transaction envelope, or ``null``
|
||||
for legacy transactions that do not have an envelope.
|
||||
|
||||
_property: transactionRequest.accessList => [[providers-AccessListish]]
|
||||
|
||||
The [[providers-AccessList]] to include in an [[link-eip-2930]] transaction, which will
|
||||
include a ``type`` of ``1``.
|
||||
|
||||
_heading: TransactionResponse @<providers-TransactionResponse> @INHERIT<[[Transaction]]>
|
||||
|
||||
A **TransactionResponse** includes all properties of a [[Transaction]] as well as several
|
||||
properties that are useful once it has been mined.
|
||||
|
||||
_property: transaction.blockNumber => number
|
||||
The number ("height") of the block this transaction was mined in. If the block has not been mined,
|
||||
this is ``null``.
|
||||
|
||||
_property: transaction.blockHash => string<[[DataHexString]]<32>>
|
||||
The hash of the block this transaction was mined in. If the block has not been mined,
|
||||
this is ``null``.
|
||||
|
||||
_property: transaction.timestamp => number
|
||||
The timestamp of the block this transaction was mined in. If the block has not been mined,
|
||||
this is ``null``.
|
||||
|
||||
_property: transaction.confirmations => number
|
||||
The number of blocks that have been mined (including the initial block) since this
|
||||
transaction was mined.
|
||||
|
||||
_property: transaction.raw => string<[[DataHexString]]>
|
||||
The serialized transaction.
|
||||
|
||||
_property: transaction.wait([ confirms = 1 ]) => Promise<[[providers-TransactionReceipt]]>
|
||||
Resolves to the [[providers-TransactionReceipt]] once the transaction
|
||||
has been included in the chain for //confirms// blocks. If //confirms//
|
||||
is 0, and the transaction has not been mined, ``null`` is returned.
|
||||
|
||||
If the transaction execution failed (i.e. the receipt status is ``0``),
|
||||
a [CALL_EXCEPTION](errors--call-exception) error will be rejected with
|
||||
the following properties:
|
||||
|
||||
- ``error.transaction`` - the original transaction
|
||||
- ``error.transactionHash`` - the hash of the transaction
|
||||
- ``error.receipt`` - the actual receipt, with the status of ``0``
|
||||
|
||||
If the transaction is replaced by another transaction, a
|
||||
[TRANSACTION_REPLACED](errors--transaction-replaced) error will be rejected
|
||||
with the following properties:
|
||||
|
||||
- ``error.hash`` - the hash of the original transaction which was replaced
|
||||
- ``error.reason`` - a string reason; one of ``"repriced"``, ``"cancelled"`` or ``"replaced"``
|
||||
- ``error.cancelled`` - a boolean; a ``"repriced"`` transaction is not considered cancelled, but ``"cancelled"`` and ``"replaced"`` are
|
||||
- ``error.replacement`` - the replacement transaction (a [[providers-TransactionResponse]])
|
||||
- ``error.receipt`` - the receipt of the replacement transaction (a [[providers-TransactionReceipt]])
|
||||
|
||||
Transactions are replaced when the user uses an option in their client to
|
||||
send a new transaction from the same account with the original ``nonce``.
|
||||
This is usually to speed up a transaction or to cancel one, by bribing
|
||||
miners with additional fees to prefer the new transaction over the original one.
|
||||
|
||||
_property: transactionRequest.type => null | number
|
||||
|
||||
The [[link-eip-2718]] type of this transaction envelope, or ``null``
|
||||
for legacy transactions that do not have an envelope.
|
||||
|
||||
_property: transactionRequest.accessList => [[providers-AccessList]]
|
||||
|
||||
The [[providers-AccessList]] included in an [[link-eip-2930]] transaction, which will
|
||||
also have its ``type`` equal to ``1``.
|
||||
|
||||
_heading: TransactionReceipt @<providers-TransactionReceipt>
|
||||
|
||||
_property: receipt.to => string<[[address]]>
|
||||
The address this transaction is to. This is ``null`` if the
|
||||
transaction was an **init transaction**, used to deploy a contract.
|
||||
|
||||
_property: receipt.from => string<[[address]]>
|
||||
The address this transaction is from.
|
||||
|
||||
_property: receipt.contractAddress => string<[[address]]>
|
||||
If this transaction has a ``null`` to address, it is an **init transaction**
|
||||
used to deploy a contract, in which case this is the address created by that
|
||||
contract.
|
||||
|
||||
To compute a contract address, the [getContractAddress](utils-getContractAddress)
|
||||
utility function can also be used with a [[providers-TransactionResponse]]
|
||||
object, which requires the transaction nonce and the address of the sender.
|
||||
|
||||
_property: receipt.transactionIndex => number
|
||||
The index of this transaction in the list of transactions included in
|
||||
the block this transaction was mined in.
|
||||
|
||||
_property: receipt.root => string
|
||||
The intermediate state root of a receipt.
|
||||
|
||||
Only transactions included in blocks **before** the [Byzantium Hard Fork](link-eip-609)
|
||||
have this property, as it was replaced by the ``status`` property.
|
||||
|
||||
The property is generally of little use to developers. At the time
|
||||
it could be used to verify a state transition with a fraud-proof
|
||||
only considering the single transaction; without it the full block
|
||||
must be considered.
|
||||
|
||||
_property: receipt.gasUsed => [[BigNumber]]
|
||||
The amount of gas actually used by this transaction.
|
||||
|
||||
_property: receipt.logsBloom => string<[[DataHexString]]>
|
||||
A [bloom-filter](link-wiki-bloomfilter), which
|
||||
includes all the addresses and topics included in any log in this
|
||||
transaction.
|
||||
|
||||
_property: receipt.blockHash => string<[[DataHexString]]<32>>
|
||||
The block hash of the block that this transaction was included in.
|
||||
|
||||
_property: receipt.transactionHash => string<[[DataHexString]]<32>>
|
||||
The transaction hash of this transaction.
|
||||
|
||||
_property: receipt.logs => Array<[[providers-Log]]>
|
||||
All the logs emitted by this transaction.
|
||||
|
||||
_property: receipt.blockNumber => number
|
||||
The block height (number) of the block that this transaction was
|
||||
included in.
|
||||
|
||||
_property: receipt.confirmations => number
|
||||
The number of blocks that have been mined since this transaction,
|
||||
including the actual block it was mined in.
|
||||
|
||||
_property: receipt.cumulativeGasUsed => [[BigNumber]]
|
||||
For the block this transaction was included in, this is the sum of the
|
||||
gas used by each transaction in the ordered list of transactions
|
||||
up to (and including) this transaction.
|
||||
|
||||
This is generally of little interest to developers.
|
||||
|
||||
_property: receipt.byzantium => boolean
|
||||
This is true if the block is in a [post-Byzantium Hard Fork](link-eip-609)
|
||||
block.
|
||||
|
||||
_property: receipt.status => boolean
|
||||
The status of a transaction is 1 is successful or 0 if it was
|
||||
reverted. Only transactions included in blocks [post-Byzantium Hard Fork](link-eip-609)
|
||||
have this property.
|
||||
|
||||
_subsection: Access Lists
|
||||
|
||||
An Access List is optional an includes a list of addresses and storage
|
||||
slots for that address which should be //warmed// or pre-fetched for
|
||||
use within the execution of this transaction. A //warmed// value has an
|
||||
additional upfront cost to access, but is discounted throughout the code
|
||||
execution for reading and writing.
|
||||
|
||||
_heading: AccessListish @<providers-AccessListish>
|
||||
|
||||
A looser description of an [[providers-AccessList]], which will be
|
||||
converted internally using [accessListify](utils-accessListify).
|
||||
|
||||
|
||||
It may be any of:
|
||||
|
||||
- any [[providers-AccessList]]
|
||||
- an Array of 2-element Arrays, where the first element is the address
|
||||
and second array is an array of storage keys
|
||||
- an object, whose keys represent the addresses and each value is an
|
||||
array of storage keys
|
||||
|
||||
When using the object form (the last option), the addresses and storage
|
||||
slots will be sorted. If an explicit order for the access list is
|
||||
required, one of the other forms must be used. Most developers
|
||||
**do not** require explicit order.
|
||||
|
||||
_code: equivalent to the AccessList example below @lang<javascript>
|
||||
|
||||
// Option 1:
|
||||
// AccessList
|
||||
// see below
|
||||
|
||||
// Option 2:
|
||||
// Array< [ Address, Array<Bytes32> ] >
|
||||
//_hide: ;
|
||||
accessList = [
|
||||
[
|
||||
"0x0x00000000000C2E074eC69A0dFb2997BA6C7d2e1e",
|
||||
[
|
||||
"0x0000000000000000000000000000000000000000000000000000000000000004",
|
||||
"0x0bcad17ecf260d6506c6b97768bdc2acfb6694445d27ffd3f9c1cfbee4a9bd6d"
|
||||
]
|
||||
],
|
||||
[
|
||||
"0x5FfC014343cd971B7eb70732021E26C35B744cc4",
|
||||
[
|
||||
"0x0000000000000000000000000000000000000000000000000000000000000001"
|
||||
]
|
||||
]
|
||||
];
|
||||
|
||||
// Option 3:
|
||||
// Record<Address, Array<Bytes32>>
|
||||
accessList = {
|
||||
"0x00000000000C2E074eC69A0dFb2997BA6C7d2e1e": [
|
||||
"0x0000000000000000000000000000000000000000000000000000000000000004",
|
||||
"0x0bcad17ecf260d6506c6b97768bdc2acfb6694445d27ffd3f9c1cfbee4a9bd6d"
|
||||
],
|
||||
"0x5FfC014343cd971B7eb70732021E26C35B744cc4": [
|
||||
"0x0000000000000000000000000000000000000000000000000000000000000001"
|
||||
]
|
||||
};
|
||||
|
||||
|
||||
_heading: AccessList @<providers-AccessList>
|
||||
|
||||
An [[link-eip-2930]] transaction allows an optional **AccessList**
|
||||
which causes a transaction to //warm// (i.e. pre-cache) another
|
||||
addresses state and the specified storage keys.
|
||||
|
||||
This incurs an increased intrinsic cost for the transaction, but provides
|
||||
discounts for storage and state access throughout the execution of the
|
||||
transaction.
|
||||
|
||||
_code: example access list
|
||||
|
||||
// Array of objects with the form:
|
||||
// {
|
||||
// address: Address,
|
||||
// storageKey: Array< DataHexString< 32 > >
|
||||
// }
|
||||
|
||||
accessList = [
|
||||
{
|
||||
address: "0x00000000000C2E074eC69A0dFb2997BA6C7d2e1e",
|
||||
storageKeys: [
|
||||
"0x0000000000000000000000000000000000000000000000000000000000000004",
|
||||
"0x0bcad17ecf260d6506c6b97768bdc2acfb6694445d27ffd3f9c1cfbee4a9bd6d"
|
||||
]
|
||||
},
|
||||
{
|
||||
address: "0x5FfC014343cd971B7eb70732021E26C35B744cc4",
|
||||
storageKeys: [
|
||||
"0x0000000000000000000000000000000000000000000000000000000000000001"
|
||||
]
|
||||
}
|
||||
];
|
||||
430
docs.wrm/api/signer.wrm
Normal file
430
docs.wrm/api/signer.wrm
Normal file
@ -0,0 +1,430 @@
|
||||
|
||||
_section: Signers @<signers>
|
||||
|
||||
A **Signer** in //ethers// is an abstraction of an Ethereum Account,
|
||||
which can be used to sign messages and transactions and send
|
||||
signed transactions to the Ethereum Network to execute state
|
||||
changing operations.
|
||||
|
||||
The available operations depend largely on the sub-class used.
|
||||
|
||||
For example, a Signer from MetaMask can send transactions and sign
|
||||
messages but cannot sign a transaction (without broadcasting it).
|
||||
|
||||
The most common Signers you will encounter are:
|
||||
|
||||
- [[Wallet]], which is a class which knows its private key and can
|
||||
execute any operations with it
|
||||
- [[JsonRpcSigner]], which is connected to a [[JsonRpcProvider]] (or
|
||||
sub-class) and is acquired using [getSigner](JsonRpcProvider-getSigner)
|
||||
|
||||
_subsection: Signer @<Signer> @SRC<abstract-signer:class.Signer>
|
||||
|
||||
The **Signer** class is abstract and cannot be directly instantiated.
|
||||
|
||||
Instead use one of the concrete sub-classes, such as the [[Wallet]],
|
||||
[[VoidSigner]] or [[JsonRpcSigner]].
|
||||
|
||||
_property: signer.connect(provider) => [[Signer]] @<Signer-connect>
|
||||
|
||||
Sub-classes **must** implement this, however they may simply throw an error
|
||||
if changing providers is not supported.
|
||||
|
||||
_property: signer.getAddress() => Promise<string<[[address]]>> @<Signer-getaddress> @SRC<abstract-signer:Signer.connect>
|
||||
Returns a Promise that resolves to the account address.
|
||||
|
||||
This is a Promise so that a **Signer** can be designed around an
|
||||
asynchronous source, such as hardware wallets.
|
||||
|
||||
Sub-classes **must** implement this.
|
||||
|
||||
_property: Signer.isSigner(object) => boolean @<Signer-isSigner> @SRC<abstract-signer>
|
||||
Returns true if an only if //object// is a **Signer**.
|
||||
|
||||
_heading: Blockchain Methods @<Signer--blockchain-methods>
|
||||
|
||||
_property: signer.getBalance([ blockTag = "latest" ]) => Promise<[[BigNumber]]> @<Signer-getBalance> @SRC<abstract-signer>
|
||||
Returns the balance of this wallet at //blockTag//.
|
||||
|
||||
_property: signer.getChainId() => Promise<number> @<Signer-getChainId> @SRC<abstract-signer>
|
||||
Returns the chain ID this wallet is connected to.
|
||||
|
||||
_property: signer.getGasPrice() => Promise<[[BigNumber]]> @<Signer-getGasPrice> @SRC<abstract-signer>
|
||||
Returns the current gas price.
|
||||
|
||||
_property: signer.getTransactionCount([ blockTag = "latest" ]) => Promise<number> @<Signer-getTransactionCount> @SRC<abstract-signer>
|
||||
Returns the number of transactions this account has ever sent. This
|
||||
is the value required to be included in transactions as the ``nonce``.
|
||||
|
||||
_property: signer.call(transactionRequest) => Promise<string<[[DataHexString]]>> @<Signer-call> @SRC<abstract-signer>
|
||||
Returns the result of calling using the //transactionRequest//, with this
|
||||
account address being used as the ``from`` field.
|
||||
|
||||
_property: signer.estimateGas(transactionRequest) => Promise<[[BigNumber]]> @<Signer-estimateGas> @SRC<abstract-signer>
|
||||
Returns the result of estimating the cost to send the //transactionRequest//,
|
||||
with this account address being used as the ``from`` field.
|
||||
|
||||
_property: signer.resolveName(ensName) => Promise<string<[[address]]>> @<Signer-resolveName> @SRC<abstract-signer>
|
||||
Returns the address associated with the //ensName//.
|
||||
|
||||
|
||||
_heading: Signing @<Signer--signing-methods>
|
||||
|
||||
_property: signer.signMessage(message) => Promise<string<[RawSignature](signature-raw)>> @<Signer-signMessage>
|
||||
This returns a Promise which resolves to the [[signature-raw]]
|
||||
of //message//.
|
||||
|
||||
A signed message is prefixd with ``"\\x19Ethereum signed message:\\n"`` and
|
||||
the length of the message, using the [hashMessage](utils-hashMessage)
|
||||
method, so that it is [EIP-191](link-eip-191) compliant. If recovering
|
||||
the address in Solidity, this prefix will be required to create a matching
|
||||
hash.
|
||||
|
||||
Sub-classes **must** implement this, however they may throw if signing a
|
||||
message is not supported, such as in a Contract-based Wallet or
|
||||
Meta-Transaction-based Wallet.
|
||||
|
||||
_note: Note
|
||||
|
||||
If //message// is a string, it is **treated as a string** and
|
||||
converted to its representation in UTF8 bytes.
|
||||
|
||||
**If and only if** a message is a [[Bytes]] will it be treated as
|
||||
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<string<[[DataHexString]]>> @<Signer-signTransaction>
|
||||
Returns a Promise which resolves to the signed transaction of the
|
||||
//transactionRequest//. This method does not populate any missing fields.
|
||||
|
||||
Sub-classes **must** implement this, however they may throw if signing a
|
||||
transaction is not supported, which is common for security reasons in many
|
||||
clients.
|
||||
|
||||
_property: signer.sendTransaction(transactionRequest) => Promise<[[providers-TransactionResponse]]> @<Signer-sendTransaction>
|
||||
This method populates the transactionRequest with missing fields, using
|
||||
[populateTransaction](Signer-populateTransaction) and returns a Promise which resolves to the transaction.
|
||||
|
||||
Sub-classes **must** implement this, however they may throw if sending a
|
||||
transaction is not supported, such as the [[VoidSigner]] or if the
|
||||
Wallet is offline and not connected to a [[Provider]].
|
||||
|
||||
_property: signer._signTypedData(domain, types, value) => Promise<string<[RawSignature](signature-raw)>> @<Signer-signTypedData>
|
||||
|
||||
Signs the typed data //value// with //types// data structure for //domain// using
|
||||
the [[link-eip-712]] specification.
|
||||
|
||||
_warning: Experimental feature (this method name will change)
|
||||
|
||||
This is still an experimental feature. If using it, please specify the **exact**
|
||||
version of ethers you are using (e.g. spcify ``"5.0.18"``, **not** ``"^5.0.18"``) as
|
||||
the method name will be renamed from ``_signTypedData`` to ``signTypedData`` once
|
||||
it has been used in the field a bit.
|
||||
|
||||
_code: Typed Data Example @lang<javascript>
|
||||
|
||||
//_hide: signer = new Wallet("0x1234567890123456789012345678901234567890123456789012345678901234");
|
||||
|
||||
// All properties on a domain are optional
|
||||
const domain = {
|
||||
name: 'Ether Mail',
|
||||
version: '1',
|
||||
chainId: 1,
|
||||
verifyingContract: '0xCcCCccccCCCCcCCCCCCcCcCccCcCCCcCcccccccC'
|
||||
};
|
||||
|
||||
// The named list of all type definitions
|
||||
const types = {
|
||||
Person: [
|
||||
{ name: 'name', type: 'string' },
|
||||
{ name: 'wallet', type: 'address' }
|
||||
],
|
||||
Mail: [
|
||||
{ name: 'from', type: 'Person' },
|
||||
{ name: 'to', type: 'Person' },
|
||||
{ name: 'contents', type: 'string' }
|
||||
]
|
||||
};
|
||||
|
||||
// The data to sign
|
||||
const value = {
|
||||
from: {
|
||||
name: 'Cow',
|
||||
wallet: '0xCD2a3d9F938E13CD947Ec05AbC7FE734Df8DD826'
|
||||
},
|
||||
to: {
|
||||
name: 'Bob',
|
||||
wallet: '0xbBbBBBBbbBBBbbbBbbBbbbbBBbBbbbbBbBbbBBbB'
|
||||
},
|
||||
contents: 'Hello, Bob!'
|
||||
};
|
||||
|
||||
//_result:
|
||||
signature = await signer._signTypedData(domain, types, value);
|
||||
//_log:
|
||||
|
||||
|
||||
_heading: Sub-Classes @<Signer--subclassing>
|
||||
|
||||
It is very important that all important properties of a **Signer** are
|
||||
**immutable**. Since Ethereum is very asynchronous and deals with critical
|
||||
data (such as ether and other potentially valuable crypto assets), keeping
|
||||
properties such as the //provider// and //address// static throughout the
|
||||
life-cycle of the Signer helps prevent serious issues and many other classes
|
||||
and libraries make this assumption.
|
||||
|
||||
A sub-class **must** extend Signer and **must** call ``super()``.
|
||||
|
||||
_property: signer.checkTransaction(transactionRequest) => [[providers-TransactionRequest]] @<Signer-checkTransaction> @SRC<abstract-signer>
|
||||
This is generally not required to be overridden, but may be needed to provide
|
||||
custom behaviour in sub-classes.
|
||||
|
||||
This should return a **copy** of the //transactionRequest//, with any properties
|
||||
needed by ``call``, ``estimateGas`` and ``populateTransaction`` (which is used
|
||||
by sendTransaction). It should also throw an error if any unknown key is specified.
|
||||
|
||||
The default implementation checks only if valid [[providers-TransactionRequest]] properties
|
||||
exist and adds ``from`` to the transaction if it does not exist.
|
||||
|
||||
If there is a ``from`` field it **must** be verified to be equal to the Signer's address.
|
||||
|
||||
_property: signer.populateTransaction(transactionRequest) => Promise<[[providers-TransactionRequest]]> @<Signer-populateTransaction> @SRC<abstract-signer>
|
||||
This is generally not required to be overridden, but may be needed to provide
|
||||
custom behaviour in sub-classes.
|
||||
|
||||
This should return a **copy** of //transactionRequest//, follow the same procedure
|
||||
as ``checkTransaction`` and fill in any properties required for sending a transaction.
|
||||
The result should have all promises resolved; if needed the [resolveProperties](utils-resolveproperties)
|
||||
utility function can be used for this.
|
||||
|
||||
The default implementation calls ``checkTransaction`` and resolves to if it is an
|
||||
ENS name, adds ``gasPrice``, ``nonce``, ``gasLimit`` and ``chainId`` based on the
|
||||
related operations on Signer.
|
||||
|
||||
|
||||
_subsection: Wallet @<Wallet> @INHERIT<[[ExternallyOwnedAccount]] and [[Signer]]> @SRC<wallet:class.Wallet>
|
||||
|
||||
The Wallet class inherits [[Signer]] and can sign transactions and messages
|
||||
using a private key as a standard Externally Owned Account (EOA).
|
||||
|
||||
_property: new ethers.Wallet(privateKey [ , provider ]) @<Wallet-constructor> @SRC<wallet:constructor.Wallet>
|
||||
Create a new Wallet instance for //privateKey// and optionally
|
||||
connected to the //provider//.
|
||||
|
||||
_property: ethers.Wallet.createRandom( [ options = { } ]) => [[Wallet]] @<Wallet-createRandom> @SRC<wallet>
|
||||
Returns a new Wallet with a random private key, generated from
|
||||
cryptographically secure entropy sources. If the current environment
|
||||
does not have a secure entropy source, an error is thrown.
|
||||
|
||||
Wallets created using this method will have a mnemonic.
|
||||
|
||||
_property: ethers.Wallet.fromEncryptedJson(json, password [ , progress ]) => Promise<[[Wallet]]> @<Wallet-fromEncryptedJson> @SRC<wallet>
|
||||
Create an instance from an encrypted JSON wallet.
|
||||
|
||||
If //progress// is provided it will be called during decryption
|
||||
with a value between 0 and 1 indicating the progress towards
|
||||
completion.
|
||||
|
||||
_property: ethers.Wallet.fromEncryptedJsonSync(json, password) => [[Wallet]] @<Wallet-fromEncryptedJsonSync> @SRC<wallet>
|
||||
Create an instance from an encrypted JSON wallet.
|
||||
|
||||
This operation will operate synchronously which will lock up the user
|
||||
interface, possibly for a non-trivial duration. Most applications should
|
||||
use the asynchronous ``fromEncryptedJson`` instead.
|
||||
|
||||
_property: ethers.Wallet.fromMnemonic(mnemonic [ , path, [ wordlist ] ]) => [[Wallet]] @<Wallet.fromMnemonic>
|
||||
Create an instance from a mnemonic phrase.
|
||||
|
||||
If path is not specified, the Ethereum default path is used (i.e. ``m/44'/60'/0'/0/0``).
|
||||
|
||||
If wordlist is not specified, the English Wordlist is used.
|
||||
|
||||
_heading: Properties @<Wallet--properties>
|
||||
|
||||
_property: wallet.address => string<[[address]]>
|
||||
The address for the account this Wallet represents.
|
||||
|
||||
_property: wallet.provider => [[Provider]]
|
||||
The provider this wallet is connected to, which will be used for any [[Signer--blockchain-methods]]
|
||||
methods. This can be null.
|
||||
|
||||
_note: Note
|
||||
A **Wallet** instance is immutable, 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 @<Wallet--methods>
|
||||
|
||||
_property: wallet.encrypt(password, [ options = { }, [ progress ] ]) => Promise<string> @<Wallet-encrypt>
|
||||
|
||||
Encrypt the wallet using //password// returning a Promise which resolves
|
||||
to a JSON wallet.
|
||||
|
||||
If //progress// is provided it will be called during decryption
|
||||
with a value between 0 and 1 indicating the progress towards
|
||||
completion.
|
||||
|
||||
_code: Wallet Examples @lang<javascript>
|
||||
|
||||
// Create a wallet instance from a mnemonic...
|
||||
mnemonic = "announce room limb pattern dry unit scale effort smooth jazz weasel alcohol"
|
||||
walletMnemonic = Wallet.fromMnemonic(mnemonic)
|
||||
|
||||
// ...or from a private key
|
||||
walletPrivateKey = new Wallet(walletMnemonic.privateKey)
|
||||
|
||||
//_result:
|
||||
walletMnemonic.address === walletPrivateKey.address
|
||||
//_log:
|
||||
|
||||
// The address as a Promise per the Signer API
|
||||
//_result:
|
||||
await walletMnemonic.getAddress()
|
||||
//_log:
|
||||
|
||||
// A Wallet address is also available synchronously
|
||||
//_result:
|
||||
walletMnemonic.address
|
||||
//_log:
|
||||
|
||||
// The internal cryptographic components
|
||||
//_result:
|
||||
walletMnemonic.privateKey
|
||||
//_log:
|
||||
//_result:
|
||||
walletMnemonic.publicKey
|
||||
//_log:
|
||||
|
||||
// The wallet mnemonic
|
||||
//_result:
|
||||
walletMnemonic.mnemonic
|
||||
//_log:
|
||||
|
||||
// Note: A wallet created with a private key does not
|
||||
// have a mnemonic (the derivation prevents it)
|
||||
//_result:
|
||||
walletPrivateKey.mnemonic
|
||||
//_log:
|
||||
|
||||
// Signing a message
|
||||
//_result:
|
||||
await walletMnemonic.signMessage("Hello World")
|
||||
//_log:
|
||||
|
||||
tx = {
|
||||
to: "0x8ba1f109551bD432803012645Ac136ddd64DBA72",
|
||||
value: utils.parseEther("1.0")
|
||||
}
|
||||
|
||||
// Signing a transaction
|
||||
//_result:
|
||||
await walletMnemonic.signTransaction(tx)
|
||||
//_log:
|
||||
|
||||
// The connect method returns a new instance of the
|
||||
// Wallet connected to a provider
|
||||
//_result:
|
||||
wallet = walletMnemonic.connect(provider)
|
||||
//_null:
|
||||
|
||||
// Querying the network
|
||||
//_result:
|
||||
await wallet.getBalance();
|
||||
//_log:
|
||||
//_result:
|
||||
await wallet.getTransactionCount();
|
||||
//_log:
|
||||
|
||||
// Sending ether
|
||||
//_hide: wallet = localSigner; /* prevent insufficient funds error from blowing up the docs */
|
||||
//_result:
|
||||
await wallet.sendTransaction(tx)
|
||||
//_log:
|
||||
|
||||
|
||||
|
||||
_subsection: VoidSigner @<VoidSigner> @INHERIT<[[Signer]]> @SRC<abstract-signer:class.VoidSigner>
|
||||
|
||||
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 [ , provider ]) => [[VoidSigner]]
|
||||
Create a new instance of a **VoidSigner** for //address//.
|
||||
|
||||
_property: voidSigner.address => string<[[address]]>
|
||||
The address of this **VoidSigner**.
|
||||
|
||||
_code: VoidSigner Pre-flight Example @lang<javascript>
|
||||
|
||||
address = "0x8ba1f109551bD432803012645Ac136ddd64DBA72"
|
||||
signer = new ethers.VoidSigner(address, provider)
|
||||
|
||||
// The DAI token contract
|
||||
abi = [
|
||||
"function balanceOf(address) view returns (uint)",
|
||||
"function transfer(address, uint) returns (bool)"
|
||||
]
|
||||
contract = new ethers.Contract("dai.tokens.ethers.eth", abi, signer)
|
||||
|
||||
// Get the number of tokens for this account
|
||||
//_result:
|
||||
tokens = await contract.balanceOf(signer.getAddress())
|
||||
//_log:
|
||||
|
||||
//
|
||||
// Pre-flight (check for revert) on DAI from the signer
|
||||
//
|
||||
// Note: We do not have the private key at this point, this
|
||||
// simply allows us to check what would happen if we
|
||||
// did. This can be useful to check before prompting
|
||||
// a request in the UI
|
||||
//
|
||||
|
||||
// This will pass since the token balance is available
|
||||
//_result:
|
||||
await contract.callStatic.transfer("donations.ethers.eth", tokens)
|
||||
//_log:
|
||||
|
||||
// This will fail since it is greater than the token balance
|
||||
//_throws:
|
||||
await contract.callStatic.transfer("donations.ethers.eth", tokens.add(1))
|
||||
//_log:
|
||||
|
||||
|
||||
_subsection: ExternallyOwnedAccount @<ExternallyOwnedAccount>
|
||||
|
||||
This is an interface which contains a minimal set of properties
|
||||
required for Externally Owned Accounts which can have certain
|
||||
operations performed, such as encoding as a JSON wallet.
|
||||
|
||||
_property: eoa.address => string<[[address]]>
|
||||
|
||||
The [[address]] of this EOA.
|
||||
|
||||
_property: eoa.privateKey => string<[[DataHexString]]<32>>
|
||||
|
||||
The privateKey of this EOA
|
||||
|
||||
_property: eoa.mnemonic => [[Mnemonic]]
|
||||
|
||||
//Optional//. The account HD mnemonic, if it has one and can be
|
||||
determined. Some sources do not encode the mnemonic, such as
|
||||
HD extended keys.
|
||||
48
docs.wrm/api/utils/abi/coder.wrm
Normal file
48
docs.wrm/api/utils/abi/coder.wrm
Normal file
@ -0,0 +1,48 @@
|
||||
_section: AbiCoder @<AbiCoder> @SRC<abi:class.AbiCoder>
|
||||
|
||||
The **AbiCoder** is a collection of Coders which can be used to
|
||||
encode and decode the binary data formats used to interoperate
|
||||
between the EVM and higher level libraries.
|
||||
|
||||
Most developers will never need to use this class directly, since
|
||||
the [[Interface]] class greatly simplifies these operations.
|
||||
|
||||
|
||||
_subsection: Creating Instance @<AbiCoder--creating>
|
||||
|
||||
For the most part, there should never be a need to manually create
|
||||
an instance of an [[AbiCoder]], since one is created with the
|
||||
default coercion function when the library is loaded which can
|
||||
be used universally.
|
||||
|
||||
This is likely only needed by those with specific needs to override
|
||||
how values are coerced after they are decoded from their binary format.
|
||||
|
||||
_property: new ethers.utils.AbiCoder([coerceFunc]) @SRC<abi:constructor.AbiCoder>
|
||||
|
||||
Create a new AbiCoder instance, which will call the //coerceFunc// on every
|
||||
decode, where the result of the call will be used in the Result.
|
||||
|
||||
The function signature is `(type, value)`, where the //type// is the string
|
||||
describing the type and the //value// is the processed value from the underlying
|
||||
Coder.
|
||||
|
||||
If the callback throws, the Result will contain a property that when accessed will
|
||||
throw, allowing for higher level libraries to recover from data errors.
|
||||
|
||||
_property: ethers.utils.defaultAbiCoder => [[AbiCoder]]
|
||||
|
||||
An [[AbiCoder]] created when the library is imported which is used by
|
||||
the [[Interface]].
|
||||
|
||||
_subsection: Coding Methods @<AbiCoder--methods>
|
||||
|
||||
_property: abiCoder.encode(types, values) => string<[[DataHexString]]> @<AbiCoder-encode> @SRC<abi/abi-coder>
|
||||
|
||||
Encode the array //values// according to the array of //types//, each of which may be a
|
||||
string or a [[ParamType]].
|
||||
|
||||
_property: abiCoder.decode(types, data) => [[Result]] @<AbiCoder-decode> @SRC<abi/abi-coder>
|
||||
|
||||
Decode the //data// according to the array of //types//, each of which may be a
|
||||
string or [[ParamType]].
|
||||
289
docs.wrm/api/utils/abi/formats.wrm
Normal file
289
docs.wrm/api/utils/abi/formats.wrm
Normal file
@ -0,0 +1,289 @@
|
||||
_section: ABI Formats @<abi-formats>
|
||||
|
||||
There are several formats available to specify an ABI for
|
||||
a Smart Contract, which specifies to the under-lying library
|
||||
what methods, events and errors exist so that encoding and
|
||||
decoding the data from and to the network can be handled by
|
||||
the library.
|
||||
|
||||
The supports ABI types are:
|
||||
|
||||
- [Human-Readable ABI](abi-formats--human-readable-abi)
|
||||
- [Solidity JSON ABI](abi-formats--solidity)
|
||||
- [Solidity Object ABI](abi-formats--object)
|
||||
|
||||
_subsection: Human-Readable ABI @<abi-formats--human-readable-abi>
|
||||
|
||||
The **Human-Readable ABI** was [introduced early by ethers](link-ricmoo-humanreadableabi),
|
||||
which allows for a Solidity signatures to be used to describe each
|
||||
method, event and error.
|
||||
|
||||
It is important to note that a Solidity signature **fully describes**
|
||||
all the properties the ABI requires:
|
||||
|
||||
- name
|
||||
- type (constructor, event, function)
|
||||
- inputs (types, nested structures and optionally names)
|
||||
- outputs (types nested structures and optionally names)
|
||||
- state mutability (for constructors and methods)
|
||||
- payability (for constructors and methods)
|
||||
- whether inputs are indexed (for events)
|
||||
|
||||
This allows for a simple format which is both machine-readalbe (since
|
||||
the parser is a machine) and human-readable (at least **developer-readable**),
|
||||
as well as simple for humans to type and inline into code, which improves
|
||||
code readability. The Human-Readable ABI is also considerably smaller, which
|
||||
helps reduce code size.
|
||||
|
||||
A Huamn-Readable ABI is simple an array of strings, where each string is
|
||||
the Solidity signature.
|
||||
|
||||
Signatures may be minimally specified (i.e. names of inputs and outputs
|
||||
may be omitted) or fully specified (i.e. with all property names) and
|
||||
whitespace is ignored.
|
||||
|
||||
Several modifiers available in Solidity are dropped internally, as they
|
||||
are not required for the ABI and used old by Solidity's semantic checking
|
||||
system, such as input parameter data location like ``"calldata"``
|
||||
and ``"memory"``. As such, they can be safely dropped in the ABI as well.
|
||||
|
||||
_code: Human-Readable ABI Example @lang<javascript>
|
||||
|
||||
const humanReadableAbi = [
|
||||
|
||||
// Simple types
|
||||
"constructor(string symbol, string name)",
|
||||
"function transferFrom(address from, address to, uint value)",
|
||||
"function balanceOf(address owner) view returns (uint balance)",
|
||||
"event Transfer(address indexed from, address indexed to, address value)",
|
||||
"error InsufficientBalance(account owner, uint balance)",
|
||||
|
||||
// Some examples with the struct type, we use the tuple keyword:
|
||||
// (note: the tuple keyword is optional, simply using additional
|
||||
// parentheses accomplishes the same thing)
|
||||
// struct Person {
|
||||
// string name;
|
||||
// uint16 age;
|
||||
// }
|
||||
"function addPerson(tuple(string name, uint16 age) person)",
|
||||
"function addPeople(tuple(string name, uint16 age)[] person)",
|
||||
"function getPerson(uint id) view returns (tuple(string name, uint16 age))",
|
||||
|
||||
"event PersonAdded(uint indexed id, tuple(string name, uint16 age) person)"
|
||||
];
|
||||
|
||||
//_hide: _page.humanReadableAbi = humanReadableAbi;
|
||||
|
||||
|
||||
_subsection: Solidity JSON ABI @<abi-formats--solidity>
|
||||
|
||||
The **Solidity JSON ABI** is a standard format that many tools export,
|
||||
including the Solidity compiler. For the full specification, see
|
||||
the [Solidity compiler documentation](link-solc-output).
|
||||
|
||||
Various versions include slightly different keys and values. For example,
|
||||
early compilers included only a boolean ``"constant"`` to indicate mutability,
|
||||
while newer versions include a string ``"mutabilityState"``, which encompasses
|
||||
several older properties.
|
||||
|
||||
When creating an instance of a [Fragment](Fragment) using a JSON ABI, it will
|
||||
automatically infer all legacy properties for new-age ABIs and for legacy
|
||||
ABIs will infer the new-age properties. All properties will be populated, so
|
||||
it will match the equivalent created using a Human-Readable ABI fragment.
|
||||
|
||||
_code: The same ABI as JSON ABI @lang<javascript>
|
||||
|
||||
const jsonAbi = `[
|
||||
{
|
||||
"type": "constructor",
|
||||
"payable": false,
|
||||
"inputs": [
|
||||
{ "type": "string", "name": "symbol" },
|
||||
{ "type": "string", "name": "name" }
|
||||
]
|
||||
},
|
||||
{
|
||||
"type": "function",
|
||||
"name": "transferFrom",
|
||||
"constant": false,
|
||||
"payable": false,
|
||||
"inputs": [
|
||||
{ "type": "address", "name": "from" },
|
||||
{ "type": "address", "name": "to" },
|
||||
{ "type": "uint256", "name": "value" }
|
||||
],
|
||||
"outputs": [ ]
|
||||
},
|
||||
{
|
||||
"type": "function",
|
||||
"name": "balanceOf",
|
||||
"constant":true,
|
||||
"stateMutability": "view",
|
||||
"payable":false, "inputs": [
|
||||
{ "type": "address", "name": "owner"}
|
||||
],
|
||||
"outputs": [
|
||||
{ "type": "uint256"}
|
||||
]
|
||||
},
|
||||
{
|
||||
"type": "event",
|
||||
"anonymous": false,
|
||||
"name": "Transfer",
|
||||
"inputs": [
|
||||
{ "type": "address", "name": "from", "indexed":true},
|
||||
{ "type": "address", "name": "to", "indexed":true},
|
||||
{ "type": "address", "name": "value"}
|
||||
]
|
||||
},
|
||||
{
|
||||
"type": "error",
|
||||
"name": "InsufficientBalance",
|
||||
"inputs": [
|
||||
{ "type": "account", "name": "owner"},
|
||||
{ "type": "uint256", "name": "balance"}
|
||||
]
|
||||
},
|
||||
{
|
||||
"type": "function",
|
||||
"name": "addPerson",
|
||||
"constant": false,
|
||||
"payable": false,
|
||||
"inputs": [
|
||||
{
|
||||
"type": "tuple",
|
||||
"name": "person",
|
||||
"components": [
|
||||
{ "type": "string", "name": "name" },
|
||||
{ "type": "uint16", "name": "age" }
|
||||
]
|
||||
}
|
||||
],
|
||||
"outputs": []
|
||||
},
|
||||
{
|
||||
"type": "function",
|
||||
"name": "addPeople",
|
||||
"constant": false,
|
||||
"payable": false,
|
||||
"inputs": [
|
||||
{
|
||||
"type": "tuple[]",
|
||||
"name": "person",
|
||||
"components": [
|
||||
{ "type": "string", "name": "name" },
|
||||
{ "type": "uint16", "name": "age" }
|
||||
]
|
||||
}
|
||||
],
|
||||
"outputs": []
|
||||
},
|
||||
{
|
||||
"type": "function",
|
||||
"name": "getPerson",
|
||||
"constant": true,
|
||||
"stateMutability": "view",
|
||||
"payable": false,
|
||||
"inputs": [
|
||||
{ "type": "uint256", "name": "id" }
|
||||
],
|
||||
"outputs": [
|
||||
{
|
||||
"type": "tuple",
|
||||
"components": [
|
||||
{ "type": "string", "name": "name" },
|
||||
{ "type": "uint16", "name": "age" }
|
||||
]
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"type": "event",
|
||||
"anonymous": false,
|
||||
"name": "PersonAdded",
|
||||
"inputs": [
|
||||
{ "type": "uint256", "name": "id", "indexed": true },
|
||||
{
|
||||
"type": "tuple",
|
||||
"name": "person",
|
||||
"components": [
|
||||
{ "type": "string", "name": "name", "indexed": false },
|
||||
{ "type": "uint16", "name": "age", "indexed": false }
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
]`;
|
||||
|
||||
//_hide: _page.jsonAbi = jsonAbi;
|
||||
|
||||
_subsection: Solidity Object ABI @<abi-formats--object>
|
||||
|
||||
The output from parsing (using JSON.parse) a Solidity JSON ABI
|
||||
is also fully compatible with the [[Interface]] class and each
|
||||
method, event and error from that object are compatible with
|
||||
the [[Fragment]] class.
|
||||
|
||||
Some developers may prefer this as it allows access to the ABI
|
||||
properties as normal JavaScript objects, and closely matches the
|
||||
JSON ABI that those familiar with the Solidity ABI will recognize.
|
||||
|
||||
_subsection: Converting Between Formats
|
||||
|
||||
The [[Fragment]] object makes it simple to reformat a single
|
||||
method, event or error, however most developers will be interested
|
||||
in converting an entire ABI.
|
||||
|
||||
For production code it is recommended to inline the Human-Readable
|
||||
ABI as it makes it easy to see at a glance which methods, events
|
||||
and errors are available. It is also highly recommend to strip out
|
||||
unused parts of the ABI (such as admin methods) to further reduce
|
||||
code size.
|
||||
|
||||
_code: Converting to Full Human-Readable ABI @lang<javascript>
|
||||
|
||||
//_hide: const Interface = ethers.utils.Interface;
|
||||
//_hide: const FormatTypes = ethers.utils.FormatTypes;
|
||||
//_hide: jsonAbi = _page.jsonAbi;
|
||||
|
||||
// Using the "full" format will ensure the Result objects
|
||||
// have named properties, which improves code readability
|
||||
const iface = new Interface(jsonAbi);
|
||||
//_result:
|
||||
iface.format(FormatTypes.full);
|
||||
//_log:
|
||||
|
||||
_code: Converting to Minimal Human-Readable ABI @lang<javascript>
|
||||
|
||||
//_hide: const Interface = ethers.utils.Interface;
|
||||
//_hide: const FormatTypes = ethers.utils.FormatTypes;
|
||||
//_hide: jsonAbi = _page.jsonAbi;
|
||||
|
||||
// Using the "minimal" format will save a small amount of
|
||||
// space, but is generally not worth it as named properties
|
||||
// on Results will not be available
|
||||
const iface = new Interface(jsonAbi);
|
||||
//_result:
|
||||
iface.format(FormatTypes.minimal);
|
||||
//_log:
|
||||
|
||||
_code: Converting to JSON ABI @lang<javascript>
|
||||
|
||||
//_hide: const Interface = ethers.utils.Interface;
|
||||
//_hide: const FormatTypes = ethers.utils.FormatTypes;
|
||||
//_hide: humanReadableAbi = _page.humanReadableAbi;
|
||||
|
||||
// Sometimes you may need to export a Human-Readable ABI to
|
||||
// JSON for tools that do not have Human-Readable support
|
||||
|
||||
// For compactness, the JSON is kept with minimal white-space
|
||||
const iface = new Interface(humanReadableAbi);
|
||||
//_result:
|
||||
jsonAbi = iface.format(FormatTypes.json);
|
||||
//_log:
|
||||
|
||||
// However it is easy to use JSON.parse and JSON.stringify
|
||||
// with formatting parameters to assist with readability
|
||||
//_result:
|
||||
JSON.stringify(JSON.parse(jsonAbi), null, 2);
|
||||
//_log:
|
||||
249
docs.wrm/api/utils/abi/fragments.wrm
Normal file
249
docs.wrm/api/utils/abi/fragments.wrm
Normal file
@ -0,0 +1,249 @@
|
||||
_section: Fragments @<fragments>
|
||||
|
||||
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](link-solc-output).
|
||||
|
||||
A JSON serialized object is always a string, which represents an Array
|
||||
of Objects, where each Object has various properties describing the [[Fragment]] of the ABI.
|
||||
|
||||
The deserialized 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 @<human-readable-abi>
|
||||
The Human-Readable ABI was introduced by ethers in [this article](link-ricmoo-humanreadableabi)
|
||||
and has since gained wider adoption.
|
||||
|
||||
The ABI is described by using an array of strings, where each string is the
|
||||
Solidity signature of the **constructor**, **function**, **event** or **error**.
|
||||
|
||||
When parsing a fragment, all inferred properties will be injected (e.g. a //payable//
|
||||
method will have its ``constant`` proeprty set to false).
|
||||
|
||||
Tuples can be specified by using the ``tuple(...)`` syntax or with bare (additional)
|
||||
parenthesis, ``(...)``.
|
||||
|
||||
_code: Example Human-Readable ABI
|
||||
|
||||
const ABI = [
|
||||
// Constructor
|
||||
"constructor(address ens)",
|
||||
|
||||
// Constant functions (pure or view)
|
||||
"function balanceOf(address owner) view returns (uint)",
|
||||
|
||||
// State-mutating functions (payable or non-payable)
|
||||
"function mint(uint amount) payable",
|
||||
"function transfer(address to, uint amount) returns (bool)",
|
||||
|
||||
// Events
|
||||
"event Transfer(address indexed from, address indexed to, uint amount)",
|
||||
|
||||
// Errors
|
||||
"error InsufficientFunds(address from, uint balance)",
|
||||
]
|
||||
|
||||
|
||||
_heading: Output Formats @<fragments--output-formats> @SRC<abi/fragments:FormatTypes>
|
||||
Each [[Fragment]] and [[ParamType]] may be output using its ``format``
|
||||
method.
|
||||
|
||||
_property: ethers.utils.FormatTypes.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 readability.
|
||||
|
||||
_property: ethers.utils.FormatTypes.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](Fragment-from).
|
||||
|
||||
_property: ethers.utils.FormatTypes.json => string
|
||||
This returns a JavaScript Object which is safe to call ``JSON.stringify``
|
||||
on to create a JSON string.
|
||||
|
||||
_property: ethers.utils.FormatTypes.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 [[Fragment]],
|
||||
since it discards modifiers such as indexed, anonymous, stateMutability, etc.
|
||||
|
||||
It is only useful for computing the selector for a Fragment, and cannot
|
||||
be used to format an Interface.
|
||||
|
||||
|
||||
_subsection: Fragment @<Fragment> @SRC<abi/fragments:class.Fragment>
|
||||
An ABI is a collection of **Fragments**, where each fragment specifies:
|
||||
|
||||
- An [Error](ErrorFragment)
|
||||
- An [Event](EventFragment)
|
||||
- A [Function](FunctionFragment)
|
||||
- A [Constructor](ConstructorFragment)
|
||||
|
||||
_heading: Properties
|
||||
|
||||
_property: fragment.name => string
|
||||
This is the name of the Event or Function. This will be null for
|
||||
a [[ConstructorFragment]].
|
||||
|
||||
_property: fragment.type => string
|
||||
This is a string which indicates the type of the [[Fragment]]. This
|
||||
will be one of:
|
||||
|
||||
- ``constructor``
|
||||
- ``event``
|
||||
- ``function``
|
||||
|
||||
_property: fragment.inputs => Array<[[ParamType]]>
|
||||
This is an array of each [[ParamType]] for the input parameters to
|
||||
the Constructor, Event of Function.
|
||||
|
||||
_heading: Methods
|
||||
|
||||
_property: fragment.format([ format = sighash]) => string @<Fragment-format> @SRC<abi/fragments:Fragment.format>
|
||||
Creates a string representation of the Fragment using the available
|
||||
[output formats](fragments--output-formats).
|
||||
|
||||
_property: ethers.utils.Fragment.from(objectOrString) => [[Fragment]] @<Fragment-from> @SRC<abi/fragments:Fragment.from>
|
||||
Creates a new **Fragment** sub-class from any compatible //objectOrString//.
|
||||
|
||||
_property: ethers.utils.Fragment.isFragment(object) => boolean @<Fragment-isFragment> @SRC<abi/fragments:Fragment.isFragment>
|
||||
Returns true if //object// is a **Fragment**.
|
||||
|
||||
|
||||
_subsection: ConstructorFragment @<ConstructorFragment> @INHERIT<[[Fragment]]> @SRC<abi/fragments:class.ConstructorFragment>
|
||||
|
||||
_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: ethers.utils.ConstructorFragment.from(objectOrString) => [[ConstructorFragment]] @<ConstructorFragment-from> @SRC<abi/fragments:ConstructorFragment.from>
|
||||
Creates a new **ConstructorFragment** from any compatible //objectOrString//.
|
||||
|
||||
_property: ethers.utils.ConstructorFragment.isConstructorFragment(object) => boolean @<ConstructorFragment-isConstructorFragment> @SRC<abi/fragments:ConstructorFragment.isConstructorFragment>
|
||||
Returns true if //object// is a **ConstructorFragment**.
|
||||
|
||||
|
||||
_subsection: ErrorFragment @<ErrorFragment> @INHERIT<[[Fragment]]> @SRC<abi/fragments:class.ErrorFragment>
|
||||
|
||||
_heading: Methods
|
||||
|
||||
_property: ethers.utils.ErrorFragment.from(objectOrString) => [[ErrorFragment]] @<ErrorFragment-from> @SRC<abi/fragments:ErrorFragment.from>
|
||||
Creates a new **ErrorFragment** from any compatible //objectOrString//.
|
||||
|
||||
_property: ethers.utils.ErrorFragment.isErrorFragment(object) => boolean @<ErrorFragment-isErrorFragment> @SRC<abi/fragments:ErrorFragment.isErrorFragment>
|
||||
Returns true if //object// is an **ErrorFragment**.
|
||||
|
||||
|
||||
_subsection: EventFragment @<EventFragment> @INHERIT<[[Fragment]]> @SRC<abi/fragments:class.EventFragment>
|
||||
|
||||
_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: ethers.utils.EventFragment.from(objectOrString) => [[EventFragment]] @<EventFragment-from> @SRC<abi/fragments:EventFragment.from>
|
||||
Creates a new **EventFragment** from any compatible //objectOrString//.
|
||||
|
||||
_property: ethers.utils.EventFragment.isEventFragment(object) => boolean @<EventFragment-isEventFragment> @SRC<abi/fragments:EventFragment.isEventFragment>
|
||||
Returns true if //object// is an **EventFragment**.
|
||||
|
||||
|
||||
_subsection: FunctionFragment @<FunctionFragment> @INHERIT<[[ConstructorFragment]]> @SRC<abi/fragments:class.FunctionFragment>
|
||||
|
||||
_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<[[ParamType]]>
|
||||
A list of the Function output parameters.
|
||||
|
||||
_heading: Methods
|
||||
|
||||
_property: ethers.utils.FunctionFragment.from(objectOrString) => [[FunctionFragment]] @<FunctionFragment-from> @SRC<abi/fragments:ConstructorFragment.from>
|
||||
Creates a new **FunctionFragment** from any compatible //objectOrString//.
|
||||
|
||||
_property: ethers.utils.FunctionFragment.isFunctionFragment(object) => boolean @<FunctionFragment-isFunctionFragment> @SRC<abi/fragments:FunctionFragment.isFunctionFragment>
|
||||
Returns true if //object// is a **FunctionFragment**.
|
||||
|
||||
|
||||
_subsection: ParamType @<ParamType> @SRC<abi/fragments:class.ParamType>
|
||||
The following examples will represent the Solidity parameter:
|
||||
|
||||
``string foobar``
|
||||
|
||||
_heading: Properties
|
||||
|
||||
_property: paramType.name => string @<ParamType-name>
|
||||
The local parameter name. This may be null for unnamed parameters. For example,
|
||||
the parameter definition ``string foobar`` would be ``foobar``.
|
||||
|
||||
_property: paramType.type => string @<ParamType-type>
|
||||
The full type of the parameter, including tuple and array symbols. This may be null
|
||||
for unnamed parameters. For the above example, this would be ``foobar``.
|
||||
|
||||
_property: paramType.baseType => string @<ParamType-baseType>
|
||||
The base type of the parameter. For primitive types (e.g. ``address``, ``uint256``, etc)
|
||||
this is equal to [type](ParamType-type). For arrays, it will be the string ``array`` and for
|
||||
a tuple, it will be the string ``tuple``.
|
||||
|
||||
_property: paramType.indexed => boolean @<ParamType-indexed>
|
||||
Whether the parameter has been marked as indexed. This **only** applies
|
||||
to parameters which are part of an [[EventFragment]].
|
||||
|
||||
_property: paramType.arrayChildren => [[ParamType]] @<ParamType-arrayChildren>
|
||||
The type of children of the array. This is null for any parameter
|
||||
which is not an array.
|
||||
|
||||
_property: paramType.arrayLength => number @<ParamType-arrayLength>
|
||||
The length of the array, or ``-1`` for dynamic-length arrays. This is
|
||||
null for parameters which are not arrays.
|
||||
|
||||
_property: paramType.components => Array<[[ParamType]]> @<ParamType-components>
|
||||
The components of a tuple. This is null for non-tuple parameters.
|
||||
|
||||
|
||||
_heading: Methods
|
||||
|
||||
_property: paramType.format([ outputType = sighash ])
|
||||
Creates a string representation of the Fragment using the available
|
||||
[output formats](fragments--output-formats).
|
||||
|
||||
_property: ethers.utils.ParamType.from(objectOrString) => [[ParamType]] @<ParamType-from> @SRC<abi/fragments:ParamType.from>
|
||||
Creates a new **ParamType** from any compatible //objectOrString//.
|
||||
|
||||
_property: ethers.utils.ParamType.isParamType(object) => boolean @<ParamType-isParamType> @SRC<abi/fragments:ParamType.isParamType>
|
||||
Returns true if //object// is a **ParamType**.
|
||||
21
docs.wrm/api/utils/abi/index.wrm
Normal file
21
docs.wrm/api/utils/abi/index.wrm
Normal file
@ -0,0 +1,21 @@
|
||||
_section: Application Binary Interface @NAV<ABI>
|
||||
|
||||
An **Application Binary Interface** (ABI) is a collection of
|
||||
[Fragments](Fragment) which specify how to interact with
|
||||
various components of a Contract.
|
||||
|
||||
An [[Interface]] helps organize Fragments by type as well
|
||||
as provides the functionality required to encode, decode and
|
||||
work with each component.
|
||||
|
||||
Most developers will not require this low-level access to encoding
|
||||
and decoding the binary data on the network and will most likely
|
||||
use a [[Contract]] which provides a more convenient interface. Some
|
||||
framework, tool developers or developers using advanced techniques
|
||||
may find these classes and utilities useful.
|
||||
|
||||
_toc:
|
||||
coder
|
||||
formats
|
||||
fragments
|
||||
interface
|
||||
521
docs.wrm/api/utils/abi/interface.wrm
Normal file
521
docs.wrm/api/utils/abi/interface.wrm
Normal file
@ -0,0 +1,521 @@
|
||||
_section: Interface @<Interface> @SRC<abi/interface:class.Interface>
|
||||
|
||||
The **Interface** Class abstracts the encoding and decoding required
|
||||
to interact with contracts on the Ethereum network.
|
||||
|
||||
Many of the standards organically evolved along side the [[link-solidity]]
|
||||
language, which other languages have adopted to remain compatible with
|
||||
existing deployed contracts.
|
||||
|
||||
The EVM itself does not understand what the ABI is. It is simply an agreed
|
||||
upon set of formats to encode various types of data which each contract can
|
||||
expect so they can interoperate with each other.
|
||||
|
||||
|
||||
_subsection: Creating Instances @<Interface--creating>
|
||||
|
||||
_property: new ethers.utils.Interface(abi) @SRC<abi/interface:constructor.Interface>
|
||||
Create a new **Interface** from a JSON string or object representing
|
||||
//abi//.
|
||||
|
||||
The //abi// may be a JSON string or the parsed Object (using JSON.parse)
|
||||
which is emitted by the [Solidity compiler](link-solc-output) (or compatible languages).
|
||||
|
||||
The //abi// may also be a [Human-Readable Abi](link-ricmoo-humanreadableabi),
|
||||
which is a format the Ethers created to simplify manually typing the ABI
|
||||
into the source and so that a Contract ABI can also be referenced easily
|
||||
within the same source file.
|
||||
|
||||
_code: Creating an Interface instance @lang<javascript>
|
||||
|
||||
//_hide: const Interface = ethers.utils.Interface;
|
||||
|
||||
// This interface is used for the below examples
|
||||
|
||||
const iface = new Interface([
|
||||
// Constructor
|
||||
"constructor(string symbol, string name)",
|
||||
|
||||
// State mutating method
|
||||
"function transferFrom(address from, address to, uint amount)",
|
||||
|
||||
// State mutating method, which is payable
|
||||
"function mint(uint amount) payable",
|
||||
|
||||
// Constant method (i.e. "view" or "pure")
|
||||
"function balanceOf(address owner) view returns (uint)",
|
||||
|
||||
// An Event
|
||||
"event Transfer(address indexed from, address indexed to, uint256 amount)",
|
||||
|
||||
// A Custom Solidity Error
|
||||
"error AccountLocked(address owner, uint256 balance)",
|
||||
|
||||
// Examples with structured types
|
||||
"function addUser(tuple(string name, address addr) user) returns (uint id)",
|
||||
"function addUsers(tuple(string name, address addr)[] user) returns (uint[] id)",
|
||||
"function getUser(uint id) view returns (tuple(string name, address addr) user)"
|
||||
]);
|
||||
|
||||
//_hide: _page.iface = iface;
|
||||
|
||||
_subsection: Properties @<Interface--properties>
|
||||
|
||||
_property: interface.fragments => Array<[[Fragment]]>
|
||||
All the [Fragments](Fragment) in the interface.
|
||||
|
||||
_property: interface.errors => Array<[[ErrorFragment]]>
|
||||
All the [Error Fragments](ErrorFragment) in the interface.
|
||||
|
||||
_property: interface.events => Array<[[EventFragment]]>
|
||||
All the [Event Fragments](EventFragment) in the interface.
|
||||
|
||||
_property: interface.functions => Array<[[FunctionFragment]]>
|
||||
All the [Function Fragments](FunctionFragment) in the interface.
|
||||
|
||||
_property: interface.deploy => [[ConstructorFragment]]
|
||||
The [Constructor Fragments](ConstructorFragment) for the interface.
|
||||
|
||||
|
||||
_subsection: Formatting @<Interface--formatting>
|
||||
|
||||
_property: interface.format( [ format ]) => string | Array<string> @SRC<abi/interface>
|
||||
Return the formatted **Interface**. If the format type is ``json`` a
|
||||
single string is returned, otherwise an Array of the human-readable
|
||||
strings is returned.
|
||||
|
||||
_code: @lang<javascript>
|
||||
|
||||
//_hide: const iface = _page.iface;
|
||||
|
||||
const FormatTypes = ethers.utils.FormatTypes;
|
||||
|
||||
//_result:
|
||||
iface.format(FormatTypes.json)
|
||||
//_log:
|
||||
|
||||
//_result:
|
||||
iface.format(FormatTypes.full)
|
||||
//_log:
|
||||
|
||||
//_result:
|
||||
iface.format(FormatTypes.minimal)
|
||||
//_log:
|
||||
|
||||
_subsection: Fragment Access @<Interface--fragments>
|
||||
|
||||
_property: interface.getFunction(fragment) => [[FunctionFragment]] @SRC<abi/interface>
|
||||
Returns the [[FunctionFragment]] for //fragment// (see [[Interface--specifying-fragments]]).
|
||||
|
||||
_code: @lang<javascript>
|
||||
|
||||
//_hide: const iface = _page.iface;
|
||||
|
||||
// By method signature, which is normalized so whitespace
|
||||
// and superfluous attributes are ignored
|
||||
iface.getFunction("transferFrom(address, address, uint256)");
|
||||
|
||||
// By name; this ONLY works if the method is non-ambiguous
|
||||
iface.getFunction("transferFrom");
|
||||
|
||||
// By method selector
|
||||
iface.getFunction("0x23b872dd");
|
||||
|
||||
// Throws if the method does not exist
|
||||
//_throws:
|
||||
iface.getFunction("doesNotExist()");
|
||||
//_log:
|
||||
|
||||
_property: interface.getError(fragment) => [[ErrorFragment]] @SRC<abi/interface>
|
||||
Returns the [[ErrorFragment]] for //fragment// (see [[Interface--specifying-fragments]]).
|
||||
|
||||
_code: @lang<javascript>
|
||||
|
||||
//_hide: const iface = _page.iface;
|
||||
|
||||
// By error signature, which is normalized so whitespace
|
||||
// and superfluous attributes are ignored
|
||||
iface.getError("AccountLocked(address, uint256)");
|
||||
|
||||
// By name; this ONLY works if the error is non-ambiguous
|
||||
iface.getError("AccountLocked");
|
||||
|
||||
// By error selector
|
||||
iface.getError("0xf7c3865a");
|
||||
|
||||
// Throws if the error does not exist
|
||||
//_throws:
|
||||
iface.getError("DoesNotExist()");
|
||||
//_log:
|
||||
|
||||
_property: interface.getEvent(fragment) => [[EventFragment]] @SRC<abi/interface>
|
||||
Returns the [[EventFragment]] for //fragment// (see [[Interface--specifying-fragments]]).
|
||||
|
||||
_code: @lang<javascript>
|
||||
|
||||
//_hide: const iface = _page.iface;
|
||||
|
||||
// By event signature, which is normalized so whitespace
|
||||
// and superfluous attributes are ignored
|
||||
iface.getEvent("Transfer(address, address, uint256)");
|
||||
|
||||
// By name; this ONLY works if the event is non-ambiguous
|
||||
iface.getEvent("Transfer");
|
||||
|
||||
// By event topic hash
|
||||
iface.getEvent("0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef");
|
||||
|
||||
// Throws if the event does not exist
|
||||
//_throws:
|
||||
iface.getEvent("DoesNotExist()");
|
||||
//_log:
|
||||
|
||||
_subsection: Signature and Topic Hashes @<Interface--selectors>
|
||||
|
||||
_property: interface.getSighash(fragment) => string<[[DataHexString]]<4>> @SRC<abi/interface:method.Interface.getSighash>
|
||||
Return the sighash (or Function Selector) for //fragment// (see [[Interface--specifying-fragments]]).
|
||||
|
||||
_code: @lang<javascript>
|
||||
|
||||
//_hide: const iface = _page.iface;
|
||||
|
||||
//_result:
|
||||
iface.getSighash("balanceOf");
|
||||
//_log:
|
||||
|
||||
//_result:
|
||||
iface.getSighash("balanceOf(address)");
|
||||
//_log:
|
||||
|
||||
const fragment = iface.getFunction("balanceOf")
|
||||
//_result:
|
||||
iface.getSighash(fragment);
|
||||
//_log:
|
||||
|
||||
_property: interface.getEventTopic(fragment) => string<[[DataHexString]]<32>> @SRC<abi/interface:method.Interface.getEventTopic>
|
||||
Return the topic hash for //fragment// (see [[Interface--specifying-fragments]]).
|
||||
|
||||
_code: @lang<javascript>
|
||||
|
||||
//_hide: const iface = _page.iface;
|
||||
|
||||
//_result:
|
||||
iface.getEventTopic("Transfer");
|
||||
//_log:
|
||||
|
||||
//_result:
|
||||
iface.getEventTopic("Transfer(address, address, uint)");
|
||||
//_log:
|
||||
|
||||
const fragment = iface.getEvent("Transfer")
|
||||
//_result:
|
||||
iface.getEventTopic(fragment);
|
||||
//_log:
|
||||
|
||||
_subsection: Encoding Data @<Interface--encoding>
|
||||
|
||||
_property: interface.encodeDeploy([ values ]) => string<[[DataHexString]]> @SRC<abi/interface>
|
||||
Return the encoded deployment data, which can be concatenated to the
|
||||
deployment bytecode of a contract to pass //values// into the contract
|
||||
constructor.
|
||||
|
||||
_code: @lang<javascript>
|
||||
|
||||
//_hide: const iface = _page.iface;
|
||||
//_hide: const parseEther = ethers.utils.parseEther;
|
||||
|
||||
// The data that should be appended to the bytecode to pass
|
||||
// parameters to the constructor during deployment
|
||||
//_result:
|
||||
iface.encodeDeploy([ "SYM", "Some Name" ])
|
||||
//_log:
|
||||
|
||||
_property: interface.encodeFilterTopics(fragment, values) => Array<topic | Array<topic>> @SRC<abi/interface>
|
||||
Returns the encoded topic filter, which can be passed to getLogs for //fragment//
|
||||
(see [[Interface--specifying-fragments]]) for the given //values//.
|
||||
|
||||
Each //topic// is a 32 byte (64 nibble) [[DataHexString]].
|
||||
|
||||
_code: @lang<javascript>
|
||||
|
||||
//_hide: const iface = _page.iface;
|
||||
//_hide: const parseEther = ethers.utils.parseEther;
|
||||
|
||||
// Filter that matches all Transfer events
|
||||
//_result:
|
||||
iface.encodeFilterTopics("Transfer", [])
|
||||
//_log:
|
||||
|
||||
// Filter that matches the sender
|
||||
//_result:
|
||||
iface.encodeFilterTopics("Transfer", [
|
||||
"0x8ba1f109551bD432803012645Ac136ddd64DBA72"
|
||||
])
|
||||
//_log:
|
||||
|
||||
// Filter that matches the receiver
|
||||
//_result:
|
||||
iface.encodeFilterTopics("Transfer", [
|
||||
null,
|
||||
"0x8ba1f109551bD432803012645Ac136ddd64DBA72"
|
||||
])
|
||||
//_log:
|
||||
|
||||
_property: interface.encodeFunctionData(fragment [ , values ]) => string<[[DataHexString]]> @SRC<abi/interface>
|
||||
Returns the encoded data, which can be used as the data for a transaction for
|
||||
//fragment// (see [[Interface--specifying-fragments]]) for the given //values//.
|
||||
|
||||
_code: @lang<javascript>
|
||||
|
||||
//_hide: const iface = _page.iface;
|
||||
//_hide: const parseEther = ethers.utils.parseEther;
|
||||
|
||||
// Encoding data for the tx.data of a call or transaction
|
||||
//_result:
|
||||
iface.encodeFunctionData("transferFrom", [
|
||||
"0x8ba1f109551bD432803012645Ac136ddd64DBA72",
|
||||
"0xaB7C8803962c0f2F5BBBe3FA8bf41cd82AA1923C",
|
||||
parseEther("1.0")
|
||||
])
|
||||
//_log:
|
||||
|
||||
// Encoding structured data (using positional Array)
|
||||
user = [
|
||||
"Richard Moore",
|
||||
"0x8ba1f109551bD432803012645Ac136ddd64DBA72"
|
||||
];
|
||||
//_result:
|
||||
iface.encodeFunctionData("addUser", [ user ]);
|
||||
//_log:
|
||||
|
||||
// Encoding structured data, using objects. Only available
|
||||
// if paramters are named.
|
||||
user = {
|
||||
name: "Richard Moore",
|
||||
addr: "0x8ba1f109551bD432803012645Ac136ddd64DBA72"
|
||||
};
|
||||
//_result:
|
||||
iface.encodeFunctionData("addUser", [ user ]);
|
||||
//_log:
|
||||
|
||||
_property: interface.encodeFunctionResult(fragment [ , values ]) => string<[[DataHexString]]> @SRC<abi/interface>
|
||||
Returns the encoded result, which would normally be the response from a call for
|
||||
//fragment// (see [[Interface--specifying-fragments]]) for the given //values//.
|
||||
|
||||
Most developers will not need this method, but may be useful for authors of a mock blockchain.
|
||||
|
||||
_code: @lang<javascript>
|
||||
|
||||
//_hide: const iface = _page.iface;
|
||||
//_hide: const parseEther = ethers.utils.parseEther;
|
||||
|
||||
// Encoding result data (like is returned by eth_call)
|
||||
//_result:
|
||||
iface.encodeFunctionResult("balanceOf", [
|
||||
"0x8ba1f109551bD432803012645Ac136ddd64DBA72"
|
||||
])
|
||||
//_log:
|
||||
|
||||
|
||||
_subsection: Decoding Data @<Interface--decoding>
|
||||
|
||||
_property: interface.decodeEventLog(fragment, data [ , topics ]) => [[Result]] @SRC<abi/interface>
|
||||
Returns the decoded event values from an event log for
|
||||
//fragment// (see [[Interface--specifying-fragments]]) for the given //data//
|
||||
with the optional //topics//.
|
||||
|
||||
If //topics// is not specified, placeholders will be inserted into the result.
|
||||
|
||||
Most develoeprs will find the [parsing methods](Interface--parsing) more
|
||||
convenient for decoding event data, as they will automatically detect the
|
||||
matching event.
|
||||
|
||||
_code: @lang<javascript>
|
||||
|
||||
//_hide: const iface = _page.iface;
|
||||
|
||||
// Decoding log data and topics (the entries in a receipt)
|
||||
const data = "0x0000000000000000000000000000000000000000000000000de0b6b3a7640000";
|
||||
const topics = [
|
||||
"0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
|
||||
"0x0000000000000000000000008ba1f109551bd432803012645ac136ddd64dba72",
|
||||
"0x000000000000000000000000ab7c8803962c0f2f5bbbe3fa8bf41cd82aa1923c"
|
||||
];
|
||||
|
||||
//_result:
|
||||
iface.decodeEventLog("Transfer", data, topics);
|
||||
//_log:
|
||||
|
||||
_property: interface.decodeFunctionData(fragment, data) => [[Result]] @SRC<abi/interface>
|
||||
Returns the decoded values from transaction data for
|
||||
//fragment// (see [[Interface--specifying-fragments]]) for the given //data//.
|
||||
|
||||
Most developers will not need this method, but may be useful for debugging
|
||||
or inspecting transactions.
|
||||
|
||||
Most develoeprs will also find the [parsing methods](Interface--parsing) more
|
||||
convenient for decoding transation data, as they will automatically detect the
|
||||
matching function.
|
||||
|
||||
_code: @lang<javascript>
|
||||
|
||||
//_hide: const iface = _page.iface;
|
||||
|
||||
// Decoding function data (the value of tx.data)
|
||||
const txData = "0x23b872dd0000000000000000000000008ba1f109551bd432803012645ac136ddd64dba72000000000000000000000000ab7c8803962c0f2f5bbbe3fa8bf41cd82aa1923c0000000000000000000000000000000000000000000000000de0b6b3a7640000";
|
||||
//_result:
|
||||
iface.decodeFunctionData("transferFrom", txData);
|
||||
//_log:
|
||||
|
||||
_property: interface.decodeFunctionResult(fragment, data) => [[Result]] @SRC<abi/interface>
|
||||
Returns the decoded values from the result of a call for
|
||||
//fragment// (see [[Interface--specifying-fragments]]) for the given //data//.
|
||||
|
||||
|
||||
_code: @lang<javascript>
|
||||
|
||||
//_hide: const iface = _page.iface;
|
||||
|
||||
// Decoding result data (e.g. from an eth_call)
|
||||
resultData = "0x0000000000000000000000000000000000000000000000000de0b6b3a7640000";
|
||||
//_result:
|
||||
iface.decodeFunctionResult("balanceOf", resultData)
|
||||
//_log:
|
||||
|
||||
// Decoding result data which was caused by a revert
|
||||
// Throws a CALL_EXCEPTION, with extra details
|
||||
errorData = "0xf7c3865a0000000000000000000000008ba1f109551bd432803012645ac136ddd64dba720000000000000000000000000000000000000000000000000de0b6b3a7640000";
|
||||
//_throws:
|
||||
iface.decodeFunctionResult("balanceOf", errorData)
|
||||
//_log:
|
||||
|
||||
// Decoding structured data returns a Result object, which
|
||||
// will include all values positionally and if the ABI
|
||||
// included names, values will additionally be available
|
||||
// by their name.
|
||||
resultData = "0x000000000000000000000000000000000000000000000000000000000000002000000000000000000000000000000000000000000000000000000000000000400000000000000000000000008ba1f109551bd432803012645ac136ddd64dba72000000000000000000000000000000000000000000000000000000000000000d52696368617264204d6f6f726500000000000000000000000000000000000000";
|
||||
//_result:
|
||||
result = iface.decodeFunctionResult("getUser", resultData);
|
||||
//_log:
|
||||
|
||||
// Access positionally:
|
||||
// The 0th output parameter, the 0th proerty of the structure
|
||||
//_result:
|
||||
result[0][0];
|
||||
//_log:
|
||||
|
||||
// Access by name: (only avilable because parameters were named)
|
||||
//_result:
|
||||
result.user.name
|
||||
//_log:
|
||||
|
||||
_subsection: Parsing @<Interface--parsing>
|
||||
|
||||
The functions are generally the most useful for most developers. They will
|
||||
automatically search the ABI for a matching Event or Function and decode
|
||||
the components as a fully specified description.
|
||||
|
||||
_property: interface.parseLog(log) => [[LogDescription]] @SRC<abi/interface>
|
||||
Search the event that matches the //log// topic hash and parse the values
|
||||
the log represents.
|
||||
|
||||
_code: @lang<javascript>
|
||||
|
||||
//_hide: const iface = _page.iface;
|
||||
|
||||
const data = "0x0000000000000000000000000000000000000000000000000de0b6b3a7640000";
|
||||
const topics = [
|
||||
"0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
|
||||
"0x0000000000000000000000008ba1f109551bd432803012645ac136ddd64dba72",
|
||||
"0x000000000000000000000000ab7c8803962c0f2f5bbbe3fa8bf41cd82aa1923c"
|
||||
];
|
||||
|
||||
//_result:
|
||||
iface.parseLog({ data, topics });
|
||||
//_hide: _.eventFragment = createClass("EventFragment");
|
||||
//_log:
|
||||
|
||||
_property: interface.parseTransaction(transaction) => [[TransactionDescription]] @SRC<abi/interface>
|
||||
Search for the function that matches the //transaction// data sighash
|
||||
and parse the transaction properties.
|
||||
|
||||
_code: @lang<javascript>
|
||||
|
||||
//_hide: const iface = _page.iface;
|
||||
//_hide: const parseEther = ethers.utils.parseEther;
|
||||
|
||||
const data = "0x23b872dd0000000000000000000000008ba1f109551bd432803012645ac136ddd64dba72000000000000000000000000ab7c8803962c0f2f5bbbe3fa8bf41cd82aa1923c0000000000000000000000000000000000000000000000000de0b6b3a7640000";
|
||||
const value = parseEther("1.0");
|
||||
|
||||
//_result:
|
||||
iface.parseTransaction({ data, value });
|
||||
//_hide: _.functionFragment = createClass("FunctionFragment");
|
||||
//_log:
|
||||
|
||||
_subsection: Types @<Interface--types>
|
||||
|
||||
_heading: Result @<Result> @INHERIT<Array\<any\>>
|
||||
|
||||
A **Result** is an array, so each value can be accessed as a positional
|
||||
argument.
|
||||
|
||||
Additionally, if values are named, the identical object as its positional
|
||||
value can be accessed by its name.
|
||||
|
||||
The name ``length`` is however reserved as it is part of the Array, so
|
||||
any named value for this key is renamed to ``_length``. If there is a
|
||||
name collision, only the first is available by its key.
|
||||
|
||||
|
||||
_heading: LogDescription @<LogDescription>
|
||||
|
||||
_property: logDescription.args => [[Result]]
|
||||
The values of the input parameters of the event.
|
||||
|
||||
_property: logDescription.eventFragment => [[EventFragment]]
|
||||
The [[EventFragment]] which matches the topic in the Log.
|
||||
|
||||
_property: logDescription.name => string
|
||||
The event name. (e.g. ``Transfer``)
|
||||
|
||||
_property: logDescription.signature => string
|
||||
The event signature. (e.g. ``Transfer(address,address,uint256)``)
|
||||
|
||||
_property: logDescription.topic => string
|
||||
The topic hash.
|
||||
|
||||
|
||||
_heading: TransactionDescription @<TransactionDescription>
|
||||
|
||||
_property: transactionDescription.args => [[Result]]
|
||||
The decoded values from the transaction data which were passed
|
||||
as the input parameters.
|
||||
|
||||
_property: transactionDescription.functionFragment => [[FunctionFragment]]
|
||||
The [[FunctionFragment]] which matches the sighash in the transaction data.
|
||||
|
||||
_property: transactionDescription.name => string
|
||||
The name of the function. (e.g. ``transfer``)
|
||||
|
||||
_property: transactionDescription.sighash => string
|
||||
The sighash (or function selector) that matched the transaction data.
|
||||
|
||||
_property: transactionDescription.signature => string
|
||||
The signature of the function. (e.g. ``transfer(address,uint256)``)
|
||||
|
||||
_property: transactionDescription.value => [[BigNumber]]
|
||||
The value from the transaction.
|
||||
|
||||
|
||||
_subsection: Specifying Fragments @<Interface--specifying-fragments>
|
||||
|
||||
When specifying a fragment to any of the functions in an **Interface**,
|
||||
any of the following may be used:
|
||||
|
||||
- The **name** of the event or function, if it is unique and non-ambiguous
|
||||
within the ABI (e.g. ``transfer``)
|
||||
- The **signature** of the event or function. The signature is normalized,
|
||||
so, for example, ``uint`` and ``uint256`` are equivalent (e.g. ``transfer(address, uint)``)
|
||||
- The **sighash** or **topichash** of the function. The sighash is often referred
|
||||
to the function selector in Solidity (e.g. ``0xa9059cbb``)
|
||||
- A [[Fragment]]
|
||||
204
docs.wrm/api/utils/address.wrm
Normal file
204
docs.wrm/api/utils/address.wrm
Normal file
@ -0,0 +1,204 @@
|
||||
_section: Addresses @<addresses>
|
||||
|
||||
Explain addresses,formats and checksumming here.
|
||||
|
||||
Also see: [constants.AddressZero](constants)
|
||||
|
||||
_subsection: Address Formats @<address-formats>
|
||||
|
||||
|
||||
_heading: Address @<address>
|
||||
|
||||
An **Address** is a [[DataHexString]] of 20 bytes (40 nibbles), with optional
|
||||
mixed case.
|
||||
|
||||
If the case is mixed, it is a **Checksum Address**, which uses a specific pattern
|
||||
of uppercase and lowercase letters within a given address to reduce the risk
|
||||
of errors introduced from typing an address or cut and paste issues.
|
||||
|
||||
All functions that return an Address will return a Checksum Address.
|
||||
|
||||
_heading: ICAP Address @<address-icap>
|
||||
|
||||
The **ICAP Address Format** was an early attempt to introduce a checksum
|
||||
into Ethereum addresses using the popular banking industry's
|
||||
[IBAN](link-wiki-iban)
|
||||
format with the country code specified as **XE**.
|
||||
|
||||
Due to the way IBAN encodes address, only addresses that fit into 30 base-36
|
||||
characters are actually compatible, so the format was adapted to support 31
|
||||
base-36 characters which is large enough for a full Ethereum address, however
|
||||
the preferred method was to select a private key whose address has a ``0`` as
|
||||
the first byte, which allows the address to be formatted as a fully compatibly
|
||||
standard IBAN address with 30 base-36 characters.
|
||||
|
||||
In general this format is no longer widely supported anymore, however any function that
|
||||
accepts an address can receive an ICAP address, and it will be converted internally.
|
||||
|
||||
To convert an address into the ICAP format, see [getIcapAddress](utils-getIcapAddress).
|
||||
|
||||
|
||||
_subsection: Converting and Verifying @<utils--address>
|
||||
|
||||
_property: ethers.utils.getAddress(address) => string<[[address]]> @<utils-getAddress> @SRC<address>
|
||||
Returns //address// as a Checksum Address.
|
||||
|
||||
If //address// is an invalid 40-nibble [[HexString]] or if it contains mixed case and
|
||||
the checksum is invalid, an [INVALID_ARGUMENT](errors--invalid-argument) Error is thrown.
|
||||
|
||||
The value of //address// may be any supported address format.
|
||||
|
||||
_code: @lang<javascript>
|
||||
|
||||
//_hide: const getAddress = ethers.utils.getAddress;
|
||||
|
||||
// Injects the checksum (via upper-casing specific letters)
|
||||
//_result:
|
||||
getAddress("0x8ba1f109551bd432803012645ac136ddd64dba72");
|
||||
//_log:
|
||||
|
||||
// Converts and injects the checksum
|
||||
//_result:
|
||||
getAddress("XE65GB6LDNXYOFTX0NSV3FUWKOWIXAMJK36");
|
||||
//_log:
|
||||
|
||||
// Throws if a checksummed address is provided, but a
|
||||
// letter is the wrong case
|
||||
// ------------v (should be lower-case)
|
||||
//_throws:
|
||||
getAddress("0x8Ba1f109551bD432803012645Ac136ddd64DBA72")
|
||||
//_log:
|
||||
|
||||
// Throws if the ICAP/IBAN checksum fails
|
||||
//_throws:
|
||||
getIcapAddress("XE65GB6LDNXYOFTX0NSV3FUWKOWIXAMJK37");
|
||||
//_log:
|
||||
|
||||
// Throws if the address is invalid, in general
|
||||
//_throws:
|
||||
getIcapAddress("I like turtles!");
|
||||
//_log:
|
||||
|
||||
|
||||
_property: ethers.utils.getIcapAddress(address) => string<[IcapAddress](address-icap)> @<utils-getIcapAddress> @SRC<address>
|
||||
Returns //address// as an [ICAP address](link-icap).
|
||||
Supports the same restrictions as [getAddress](utils-getAddress).
|
||||
|
||||
_code: @lang<javascript>
|
||||
|
||||
//_hide: const getIcapAddress = ethers.utils.getIcapAddress;
|
||||
|
||||
//_result:
|
||||
getIcapAddress("0x8ba1f109551bd432803012645ac136ddd64dba72");
|
||||
//_log:
|
||||
|
||||
//_result:
|
||||
getIcapAddress("XE65GB6LDNXYOFTX0NSV3FUWKOWIXAMJK36");
|
||||
//_log:
|
||||
|
||||
_property: ethers.utils.isAddress(address) => boolean @<utils-isAddress> @SRC<address>
|
||||
Returns true if //address// is valid (in any supported format).
|
||||
|
||||
_code: @lang<javascript>
|
||||
|
||||
//_hide: const isAddress = ethers.utils.isAddress;
|
||||
|
||||
//_result:
|
||||
isAddress("0x8ba1f109551bd432803012645ac136ddd64dba72");
|
||||
//_log:
|
||||
|
||||
//_result:
|
||||
isAddress("XE65GB6LDNXYOFTX0NSV3FUWKOWIXAMJK36");
|
||||
//_log:
|
||||
|
||||
//_result:
|
||||
isAddress("I like turtles.");
|
||||
//_log:
|
||||
|
||||
_subsection: Derivation @<utils--address-derivation>
|
||||
|
||||
_property: ethers.utils.computeAddress(publicOrPrivateKey) => string<[[address]]> @<utils-computeAddress> @SRC<transactions>
|
||||
Returns the address for //publicOrPrivateKey//. A public key may be
|
||||
compressed or uncompressed, and a private key will be converted
|
||||
automatically to a public key for the derivation.
|
||||
|
||||
_code: @lang<javascript>
|
||||
|
||||
//_hide: const computeAddress = ethers.utils.computeAddress;
|
||||
|
||||
// Private Key
|
||||
//_result:
|
||||
computeAddress("0xb976778317b23a1385ec2d483eda6904d9319135b89f1d8eee9f6d2593e2665d");
|
||||
//_log:
|
||||
|
||||
// Public Key (compressed)
|
||||
//_result:
|
||||
computeAddress("0x0376698beebe8ee5c74d8cc50ab84ac301ee8f10af6f28d0ffd6adf4d6d3b9b762");
|
||||
//_log:
|
||||
|
||||
// Public Key (uncompressed)
|
||||
//_result:
|
||||
computeAddress("0x0476698beebe8ee5c74d8cc50ab84ac301ee8f10af6f28d0ffd6adf4d6d3b9b762d46ca56d3dad2ce13213a6f42278dabbb53259f2d92681ea6a0b98197a719be3");
|
||||
//_log:
|
||||
|
||||
_property: ethers.utils.recoverAddress(digest, signature) => string<[[address]]> @<utils-recoverAddress> @SRC<transactions>
|
||||
Use [[link-wiki-ecrecover]] to determine the address that signed //digest// to
|
||||
which generated //signature//.
|
||||
|
||||
_code: @lang<javascript>
|
||||
|
||||
//_hide: const recoverAddress = ethers.utils.recoverAddress;
|
||||
|
||||
const digest = "0x7c5ea36004851c764c44143b1dcb59679b11c9a68e5f41497f6cf3d480715331";
|
||||
|
||||
// Using an expanded Signature
|
||||
//_result:
|
||||
recoverAddress(digest, {
|
||||
r: "0x528459e4aec8934dc2ee94c4f3265cf6ce00d47cf42bb106afda3642c72e25eb",
|
||||
s: "0x42544137118256121502784e5a6425e6183ca964421ecd577db6c66ba9bccdcf",
|
||||
v: 27
|
||||
});
|
||||
//_log:
|
||||
|
||||
// Using a flat Signature
|
||||
const signature = "0x528459e4aec8934dc2ee94c4f3265cf6ce00d47cf42bb106afda3642c72e25eb42544137118256121502784e5a6425e6183ca964421ecd577db6c66ba9bccdcf1b";
|
||||
//_result:
|
||||
recoverAddress(digest, signature);
|
||||
//_log:
|
||||
|
||||
_subsection: Contracts Addresses @<utils--contract-addresses>
|
||||
|
||||
_property: ethers.utils.getContractAddress(transaction) => string<[[address]]> @<utils-getContractAddress> @SRC<address>
|
||||
Returns the contract address that would result if //transaction// was
|
||||
used to deploy a contract.
|
||||
|
||||
_code: @lang<javascript>
|
||||
|
||||
//_hide: const getContractAddress = ethers.utils.getContractAddress;
|
||||
|
||||
const from = "0x8ba1f109551bD432803012645Ac136ddd64DBA72";
|
||||
const nonce = 5;
|
||||
|
||||
//_result:
|
||||
getContractAddress({ from, nonce });
|
||||
//_log:
|
||||
|
||||
_property: ethers.utils.getCreate2Address(from, salt, initCodeHash) => string<[[address]]> @<utils-getCreate2Address> @SRC<address>
|
||||
Returns the contract address that would result from the given
|
||||
[CREATE2](link-eip-1014) call.
|
||||
|
||||
_code: @lang<javascript>
|
||||
|
||||
//_hide: const getCreate2Address = ethers.utils.getCreate2Address;
|
||||
//_hide: const keccak256 = ethers.utils.keccak256;
|
||||
|
||||
const from = "0x8ba1f109551bD432803012645Ac136ddd64DBA72";
|
||||
const salt = "0x7c5ea36004851c764c44143b1dcb59679b11c9a68e5f41497f6cf3d480715331";
|
||||
const initCode = "0x6394198df16000526103ff60206004601c335afa6040516060f3";
|
||||
const initCodeHash = keccak256(initCode);
|
||||
|
||||
//_result:
|
||||
getCreate2Address(from, salt, initCodeHash);
|
||||
//_log:
|
||||
|
||||
|
||||
298
docs.wrm/api/utils/bignumber.wrm
Normal file
298
docs.wrm/api/utils/bignumber.wrm
Normal file
@ -0,0 +1,298 @@
|
||||
_section: BigNumber @<BigNumber>
|
||||
|
||||
Many operations in Ethereum operate on numbers which are
|
||||
[outside the range of safe values](BigNumber--notes-safenumbers) to use
|
||||
in JavaScript.
|
||||
|
||||
A **BigNumber** is an object which safely allows mathematical operations
|
||||
on numbers of any magnitude.
|
||||
|
||||
Most operations which need to return a value will return a **BigNumber**
|
||||
and parameters which accept values will generally accept them.
|
||||
|
||||
|
||||
_subsection: Types @<BigNumber--types>
|
||||
|
||||
_heading: BigNumberish @<BigNumberish>
|
||||
|
||||
Many functions and methods in this library take in values which
|
||||
can be non-ambiguously and safely converted to a BigNumber. These
|
||||
values can be specified as:
|
||||
|
||||
_definition: **//string//**
|
||||
A [[HexString]] or a decimal string, either of which may
|
||||
be negative.
|
||||
|
||||
_definition: **//BytesLike//**
|
||||
A [[BytesLike]] Object, such as an Array or Uint8Array.
|
||||
|
||||
_definition: **//BigNumber//**
|
||||
An existing [[BigNumber]] instance.
|
||||
|
||||
_definition: **//number//**
|
||||
A number that is within the [safe range](link-js-maxsafe) for JavaScript numbers.
|
||||
|
||||
_definition: **//BigInt//**
|
||||
A JavaScript [BigInt](link-js-bigint)
|
||||
object, on environments that support BigInt.
|
||||
|
||||
|
||||
_subsection: Creating Instances @<BigNumber--creating>
|
||||
|
||||
The constructor of BigNumber cannot be called directly. Instead, Use the static ``BigNumber.from``.
|
||||
|
||||
_property: ethers.BigNumber.from(aBigNumberish) => [[BigNumber]]
|
||||
Returns an instance of a **BigNumber** for //aBigNumberish//.
|
||||
|
||||
_heading: Examples: @<>
|
||||
|
||||
_code: @lang<javascript>
|
||||
|
||||
// From a decimal string...
|
||||
//_result:
|
||||
BigNumber.from("42")
|
||||
//_log:
|
||||
|
||||
// From a HexString...
|
||||
//_result:
|
||||
BigNumber.from("0x2a")
|
||||
//_log:
|
||||
|
||||
// From a negative HexString...
|
||||
//_result:
|
||||
BigNumber.from("-0x2a")
|
||||
//_log:
|
||||
|
||||
// From an Array (or Uint8Array)...
|
||||
//_result:
|
||||
BigNumber.from([ 42 ])
|
||||
//_log:
|
||||
|
||||
// From an existing BigNumber...
|
||||
let one1 = constants.One;
|
||||
let one2 = BigNumber.from(one1)
|
||||
|
||||
//_result:
|
||||
one2
|
||||
//_log:
|
||||
|
||||
// ...which returns the same instance
|
||||
//_result:
|
||||
one1 === one2
|
||||
//_log:
|
||||
|
||||
// From a (safe) number...
|
||||
//_result:
|
||||
BigNumber.from(42)
|
||||
//_log:
|
||||
|
||||
// From a ES2015 BigInt... (only on platforms with BigInt support)
|
||||
//_result:
|
||||
BigNumber.from(42n)
|
||||
//_log:
|
||||
|
||||
// Numbers outside the safe range fail:
|
||||
//_throws:
|
||||
BigNumber.from(Number.MAX_SAFE_INTEGER);
|
||||
//_log:
|
||||
|
||||
|
||||
_subsection: Methods @<BigNumber--methods>
|
||||
|
||||
The BigNumber class is immutable, so no operations can change the value
|
||||
it represents.
|
||||
|
||||
|
||||
_heading: Math Operations
|
||||
|
||||
_property: BigNumber.add(otherValue) => [[BigNumber]] @SRC<bignumber>
|
||||
Returns a BigNumber with the value of //BigNumber// **+** //otherValue//.
|
||||
|
||||
_property: BigNumber.sub(otherValue) => [[BigNumber]] @SRC<bignumber>
|
||||
Returns a BigNumber with the value of //BigNumber// **-** //otherValue//.
|
||||
|
||||
_property: BigNumber.mul(otherValue) => [[BigNumber]] @SRC<bignumber>
|
||||
Returns a BigNumber with the value of //BigNumber// **×** //otherValue//.
|
||||
|
||||
_property: BigNumber.div(divisor) => [[BigNumber]] @SRC<bignumber>
|
||||
Returns a BigNumber with the value of //BigNumber// **÷** //divisor//.
|
||||
|
||||
_property: BigNumber.mod(divisor) => [[BigNumber]] @SRC<bignumber>
|
||||
Returns a BigNumber with the value of the **remainder** of //BigNumber// ÷ //divisor//.
|
||||
|
||||
_property: BigNumber.pow(exponent) => [[BigNumber]] @SRC<bignumber>
|
||||
Returns a BigNumber with the value of //BigNumber// to the power of //exponent//.
|
||||
|
||||
_property: BigNumber.abs() => [[BigNumber]] @SRC<bignumber>
|
||||
Returns a BigNumber with the absolute value of //BigNumber//.
|
||||
|
||||
_property: BigNumber.mask(bitcount) => [[BigNumber]] @SRC<bignumber>
|
||||
Returns a BigNumber with the value of //BigNumber// with bits beyond
|
||||
the //bitcount// least significant bits set to zero.
|
||||
|
||||
|
||||
_heading: Two's Complement
|
||||
|
||||
[Two's Complement](link-wiki-twoscomplement)
|
||||
is an elegant method used to encode and decode fixed-width signed values
|
||||
while efficiently preserving mathematical operations.
|
||||
Most users will not need to interact with these.
|
||||
|
||||
_property: BigNumber.fromTwos(bitwidth) => [[BigNumber]] @SRC<bignumber>
|
||||
Returns a BigNumber with the value of //BigNumber// converted from twos-complement with //bitwidth//.
|
||||
|
||||
_property: BigNumber.toTwos(bitwidth) => [[BigNumber]] @SRC<bignumber>
|
||||
Returns a BigNumber with the value of //BigNumber// converted to twos-complement with //bitwidth//.
|
||||
|
||||
|
||||
_heading: Comparison and Equivalence
|
||||
|
||||
_property: BigNumber.eq(otherValue) => boolean @SRC<bignumber>
|
||||
Returns true if and only if the value of //BigNumber// is equal to //otherValue//.
|
||||
|
||||
_property: BigNumber.lt(otherValue) => boolean @SRC<bignumber>
|
||||
Returns true if and only if the value of //BigNumber// **<** //otherValue//.
|
||||
|
||||
_property: BigNumber.lte(otherValue) => boolean @SRC<bignumber>
|
||||
Returns true if and only if the value of //BigNumber// **≤** //otherValue//.
|
||||
|
||||
_property: BigNumber.gt(otherValue) => boolean @SRC<bignumber>
|
||||
Returns true if and only if the value of //BigNumber// **>** //otherValue//.
|
||||
|
||||
_property: BigNumber.gte(otherValue) => boolean @SRC<bignumber>
|
||||
Returns true if and only if the value of //BigNumber// **≥** //otherValue//.
|
||||
|
||||
_property: BigNumber.isZero() => boolean @SRC<bignumber:BigNumber.isZero>
|
||||
Returns true if and only if the value of //BigNumber// is zero.
|
||||
|
||||
|
||||
_heading: Conversion
|
||||
|
||||
_property: BigNumber.toNumber() => number @SRC<bignumber>
|
||||
Returns the value of //BigNumber// as a JavaScript value.
|
||||
|
||||
This will **throw an error**
|
||||
if the value is greater than or equal to //Number.MAX_SAFE_INTEGER// or less than or
|
||||
equal to //Number.MIN_SAFE_INTEGER//.
|
||||
|
||||
_property: BigNumber.toString() => string @SRC<bignumber:BigNumber.toString>
|
||||
Returns the value of //BigNumber// as a base-10 string.
|
||||
|
||||
_property: BigNumber.toHexString() => string<[[DataHexString]]> @SRC<bignumber:BigNumber.toHexString>
|
||||
Returns the value of //BigNumber// as a base-16, ``0x``-prefixed [[DataHexString]].
|
||||
|
||||
|
||||
_heading: Inspection
|
||||
|
||||
_property: ethers.BigNumber.isBigNumber(object) => boolean @SRC<bignumber>
|
||||
Returns true if and only if the //object// is a BigNumber object.
|
||||
|
||||
|
||||
_heading: Examples
|
||||
|
||||
_code: @lang<javascript>
|
||||
|
||||
let a = BigNumber.from(42);
|
||||
let b = BigNumber.from("91");
|
||||
|
||||
//_result:
|
||||
a.mul(b);
|
||||
//_log:
|
||||
|
||||
|
||||
_subsection: Notes @<BigNumber--notes>
|
||||
|
||||
This section is a for a couple of questions that come up frequently.
|
||||
|
||||
|
||||
_heading: Why can't I just use numbers? @<BigNumber--notes-safenumbers>
|
||||
|
||||
The first problem many encounter when dealing with Ethereum is
|
||||
the concept of numbers. Most common currencies are broken down
|
||||
with very little granularity. For example, there are only 100
|
||||
cents in a single dollar. However, there are 10^^18^^ **wei** in a
|
||||
single **ether**.
|
||||
|
||||
JavaScript uses [IEEE 754 double-precision binary floating point](link-wiki-ieee754)
|
||||
numbers to represent numeric values. As a result, there are //holes//
|
||||
in the integer set after 9,007,199,254,740,991; which is
|
||||
problematic for //Ethereum// because that is only around 0.009
|
||||
ether (in wei), which means any value over that will begin to
|
||||
experience rounding errors.
|
||||
|
||||
To demonstrate how this may be an issue in your code, consider:
|
||||
|
||||
_code: @lang<javascript>
|
||||
|
||||
//_result:
|
||||
(Number.MAX_SAFE_INTEGER + 2 - 2) == (Number.MAX_SAFE_INTEGER)
|
||||
//_log:
|
||||
|
||||
_null:
|
||||
|
||||
To remedy this, all numbers (which can be large) are stored
|
||||
and manipulated as [Big Numbers](BigNumber).
|
||||
|
||||
The functions [parseEther( etherString )](utils-parseEther) and
|
||||
[formatEther( wei )](utils-formatEther) can be used to convert
|
||||
between string representations, which are displayed to or entered
|
||||
by the user and Big Number representations which can have
|
||||
mathematical operations handled safely.
|
||||
|
||||
|
||||
_heading: Why not BigNumber.js, BN.js, BigDecimal, etc?
|
||||
|
||||
Everyone has their own favourite Big Number library, and once someone
|
||||
has chosen one, it becomes part of their identity, like their editor,
|
||||
vi vs emacs. There are over 100 Big Number libraries on [npm](link-npm-query-bignumber).
|
||||
|
||||
One of the biggest differences between the Ethers [[BigNumber]] object and
|
||||
other libraries is that it is immutable, which is very important when
|
||||
dealing with the asynchronous nature of the blockchain.
|
||||
|
||||
Capturing the value is not safe in async functions, so immutability
|
||||
protects us from easy to make mistakes, which is not possible on the
|
||||
low-level library's objects which supports myriad in-place operations.
|
||||
|
||||
Second, the Ethers [[BigNumber]] provides all the functionality required
|
||||
internally and should generally be sufficient for most developers while
|
||||
not exposing some of the more advanced and rare functionality. So it will
|
||||
be easier to swap out the underlying library without impacting consumers.
|
||||
|
||||
For example, if [[link-npm-bnjs]] was exposed, someone may use the
|
||||
greatest-common-denominator functions, which would then be functionality
|
||||
the replacing library should also provide to ensure anyone depending on
|
||||
that functionality is not broken.
|
||||
|
||||
|
||||
_heading: Why BN.js??
|
||||
|
||||
The reason why [[link-npm-bnjs]] is used internally as the big
|
||||
number is because that is the library used by [[link-npm-elliptic]].
|
||||
|
||||
Therefore it **must** be included regardless, so we leverage that
|
||||
library rather than adding another Big Number library, which would
|
||||
mean two different libraries offering the same functionality.
|
||||
|
||||
This has saved about 85kb (80% of this library size) of library size
|
||||
over other libraries which include separate Big Number libraries for
|
||||
various purposes.
|
||||
|
||||
|
||||
_heading: Allow us to set a global Big Number library?
|
||||
|
||||
Another comment that comes up frequently is the desire to specify a
|
||||
global user-defined Big Number library, which all functions would
|
||||
return.
|
||||
|
||||
This becomes problematic since your code may live along side other
|
||||
libraries or code that use Ethers. In fact, even Ethers uses a lot
|
||||
of the public functions internally.
|
||||
|
||||
If you, for example, used a library that used ``a.plus(b)`` instead
|
||||
of ``a.add(b)``, this would break Ethers when it tries to compute
|
||||
fees internally, and other libraries likely have similar logic.
|
||||
|
||||
But, the [[BigNumber]] prototype is exposed, so you can always add a
|
||||
``toMyCustomBigNumber()`` method to all [[BigNumber]]'s globally
|
||||
which is safe.
|
||||
193
docs.wrm/api/utils/bytes.wrm
Normal file
193
docs.wrm/api/utils/bytes.wrm
Normal file
@ -0,0 +1,193 @@
|
||||
_section: Byte Manipulation
|
||||
|
||||
While there are many high-level APIs for interacting with
|
||||
Ethereum, such as [Contracts](Contract) and [Providers](Provider),
|
||||
a lot of the low level access requires byte manipulation
|
||||
operations.
|
||||
|
||||
Many of these operations are used internally, but can also be
|
||||
used to help normalize binary data representations from the
|
||||
output of various functions and methods.
|
||||
|
||||
_subsection: Types
|
||||
|
||||
_heading: Bytes @<Bytes>
|
||||
|
||||
A **Bytes** is any object which is an
|
||||
[Array](link-js-array) or [TypedArray](link-js-typedarray) with
|
||||
each value in the valid byte range (i.e. between 0 and 255 inclusive),
|
||||
or is an Object with a ``length`` property where each indexed property
|
||||
is in the valid byte range.
|
||||
|
||||
_heading: BytesLike @<BytesLike>
|
||||
|
||||
A **BytesLike** can be either a [[Bytes]] or a [[DataHexString]].
|
||||
|
||||
_heading: DataHexString @<DataHexString>
|
||||
|
||||
A **DataHexstring** is identical to a [[HexString]] except that it has
|
||||
an even number of nibbles, and therefore is a valid representation of
|
||||
binary data as a string.
|
||||
|
||||
_heading: HexString @<HexString>
|
||||
|
||||
A **Hexstring** is a string which has a ``0x`` prefix followed by any
|
||||
number of nibbles (i.e. case-insensitive hexadecimal characters, ``0-9`` and ``a-f``).
|
||||
|
||||
_heading: Signature @<Signature>
|
||||
|
||||
- **r** and **s** --- The x co-ordinate of **r** and the **s** value of the signature
|
||||
- **v** --- The parity of the y co-ordinate of **r**
|
||||
- **_vs** --- The [compact representation](link-eip-2098) of the **s** and **v**
|
||||
- **recoveryParam** --- The normalized (i.e. 0 or 1) value of **v**
|
||||
|
||||
_heading: Raw Signature @<signature-raw> @inherit<string\<[[DataHexString]]\<65\>\>>
|
||||
|
||||
A **Raw Signature** is a common Signature format where the r, s and v are
|
||||
concatenated into a 65 byte (130 nibble) [[DataHexString]].
|
||||
|
||||
|
||||
_heading: SignatureLike @<SignatureLike>
|
||||
|
||||
A **SignatureLike** is similar to a [[Signature]], except redundant properties
|
||||
may be omitted or it may be a [[signature-raw]].
|
||||
|
||||
For example, if **_vs** is specified, **s** and **v** may be omitted. Likewise,
|
||||
if **recoveryParam** is provided, **v** may be omitted (as in these cases the
|
||||
missing values can be computed).
|
||||
|
||||
|
||||
_subsection: Inspection
|
||||
|
||||
_property: ethers.utils.isBytes(object) => boolean @<utils-isBytes> @SRC<bytes>
|
||||
Returns true if and only if //object// is a valid [[Bytes]].
|
||||
|
||||
_property: ethers.utils.isBytesLike(object) => boolean @<utils-isBytesLike> @SRC<bytes>
|
||||
Returns true if and only if //object// is a [[Bytes]] or [[DataHexString]].
|
||||
|
||||
_property: ethers.utils.isHexString(object, [ length ] ) => boolean @<utils-isHexString> @SRC<bytes>
|
||||
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.
|
||||
|
||||
|
||||
_subsection: Converting between Arrays and Hexstrings
|
||||
|
||||
_property: ethers.utils.arrayify(DataHexStringOrArrayish [ , options ]) => Uint8Array @<utils-arrayify> @SRC<bytes>
|
||||
Converts //DataHexStringOrArrayish// to a Uint8Array.
|
||||
|
||||
_property: ethers.utils.hexlify(hexstringOrArrayish) => string<[[DataHexString]]> @<utils-hexlify> @SRC<bytes>
|
||||
Converts //hexstringOrArrayish// to a [[DataHexString]].
|
||||
|
||||
_property: ethers.utils.hexValue(aBigNumberish) => string<[[HexString]]> @<utils-hexValue> @SRC<bytes>
|
||||
Converts //aBigNumberish// to a [[HexString]], with no __unnecessary__ leading
|
||||
zeros.
|
||||
|
||||
_code: Examples @lang<javascript>
|
||||
|
||||
// Convert a hexstring to a Uint8Array
|
||||
//_result:
|
||||
arrayify("0x1234")
|
||||
//_log:
|
||||
|
||||
// Convert an Array to a hexstring
|
||||
//_result:
|
||||
hexlify([1, 2, 3, 4])
|
||||
//_log:
|
||||
|
||||
// Convert an Object to a hexstring
|
||||
//_result:
|
||||
hexlify({ length: 2, "0": 1, "1": 2 })
|
||||
//_log:
|
||||
|
||||
// Convert an Array to a hexstring
|
||||
//_result:
|
||||
hexlify([ 1 ])
|
||||
//_log:
|
||||
|
||||
// Convert a number to a stripped hex value
|
||||
//_result:
|
||||
hexValue(1)
|
||||
//_log:
|
||||
|
||||
// Convert an Array to a stripped hex value
|
||||
//_result:
|
||||
hexValue([ 1, 2 ])
|
||||
//_log:
|
||||
|
||||
|
||||
_subsection: Array Manipulation
|
||||
|
||||
_property: ethers.utils.concat(arrayOfBytesLike) => Uint8Array @<utils-concat> @SRC<bytes>
|
||||
Concatenates all the [[BytesLike]] in //arrayOfBytesLike// into a single Uint8Array.
|
||||
|
||||
_property: ethers.utils.stripZeros(aBytesLike) => Uint8Array @<utils-stripZeros> @SRC<bytes>
|
||||
Returns a Uint8Array with all leading ``0`` bytes of //aBtyesLike// removed.
|
||||
|
||||
_property: ethers.utils.zeroPad(aBytesLike, length) => Uint8Array @<utils-zeroPad> @SRC<bytes>
|
||||
Returns a Uint8Array of the data in //aBytesLike// with ``0`` bytes prepended to
|
||||
//length// bytes long.
|
||||
|
||||
If //aBytesLike// is already longer than //length// bytes long, an InvalidArgument
|
||||
error will be thrown.
|
||||
|
||||
|
||||
_subsection: Hexstring Manipulation
|
||||
|
||||
_property: ethers.utils.hexConcat(arrayOfBytesLike) => string<[[DataHexString]]> @<utils-hexConcat> @SRC<bytes>
|
||||
Concatenates all the [[BytesLike]] in //arrayOfBytesLike// into a single [[DataHexString]]
|
||||
|
||||
_property: ethers.utils.hexDataLength(aBytesLike) => string<[[DataHexString]]> @<utils-hexDataLength> @SRC<bytes>
|
||||
Returns the length (in bytes) of //aBytesLike//.
|
||||
|
||||
_property: ethers.utils.hexDataSlice(aBytesLike, offset [ , endOffset ] ) => string<[[DataHexString]]> @<utils-hexDataSlice> @SRC<bytes>
|
||||
Returns a [[DataHexString]] representation of a slice of //aBytesLike//, from
|
||||
//offset// (in bytes) to //endOffset// (in bytes). If //endOffset// is
|
||||
omitted, the length of //aBytesLike// is used.
|
||||
|
||||
_property: ethers.utils.hexStripZeros(aBytesLike) => string<[[HexString]]> @<utils-hexStripZeros> @SRC<bytes>
|
||||
Returns a [[HexString]] representation of //aBytesLike// with all
|
||||
leading zeros removed.
|
||||
|
||||
_property: ethers.utils.hexZeroPad(aBytesLike, length) => string<[[DataHexString]]> @<utils-hexZeroPad> @SRC<bytes>
|
||||
Returns a [[DataHexString]] representation of //aBytesLike// padded to //length// bytes.
|
||||
|
||||
If //aBytesLike// is already longer than //length// bytes long, an InvalidArgument
|
||||
error will be thrown.
|
||||
|
||||
|
||||
_subsection: Signature Conversion
|
||||
|
||||
_property: ethers.utils.joinSignature(aSignatureLike) => string<[RawSignature](signature-raw)> @<utils-joinSignature> @SRC<bytes>
|
||||
Return the raw-format of //aSignaturelike//, which is 65 bytes (130 nibbles)
|
||||
long, concatenating the **r**, **s** and (normalized) **v** of a Signature.
|
||||
|
||||
_property: ethers.utils.splitSignature(aSignatureLikeOrBytesLike) => [[Signature]] @<utils-splitSignature> @SRC<bytes>
|
||||
Return the full expanded-format of //aSignaturelike// or a raw-format [[DataHexString]].
|
||||
Any missing properties will be computed.
|
||||
|
||||
_subsection: Random Bytes
|
||||
|
||||
_property: ethers.utils.randomBytes(length) => Uint8Array @<utils-randomBytes> @SRC<random/random>
|
||||
Return a new Uint8Array of //length// random bytes.
|
||||
|
||||
_property: ethers.utils.shuffled(array) => Array<any> @<utils-shuffled> @SRC<random>
|
||||
Return a copy of //array// shuffled using [[link-wiki-shuffle]].
|
||||
|
||||
_code: Examples @lang<javascript>
|
||||
|
||||
//_result:
|
||||
utils.randomBytes(8)
|
||||
//_log:
|
||||
|
||||
const data = [ 1, 2, 3, 4, 5, 6, 7 ];
|
||||
|
||||
// Returns a new Array
|
||||
//_result:
|
||||
utils.shuffled(data);
|
||||
//_log:
|
||||
|
||||
// The Original is unscathed...
|
||||
//_result:
|
||||
data
|
||||
//_log:
|
||||
43
docs.wrm/api/utils/constants.wrm
Normal file
43
docs.wrm/api/utils/constants.wrm
Normal file
@ -0,0 +1,43 @@
|
||||
_section: Constants @<constants>
|
||||
|
||||
The **ethers.contants** Object contains commonly used values.
|
||||
|
||||
|
||||
_subsection: Bytes
|
||||
|
||||
_property: ethers.constants.AddressZero => string<[Address](address)> @<constants-AddressZero> @SRC<constants>
|
||||
The Address Zero, which is 20 bytes (40 nibbles) of zero.
|
||||
|
||||
_property: ethers.constants.HashZero => string<[[DataHexString]]<32>> @<constants-HashZero> @SRC<constants>
|
||||
The Hash Zero, which is 32 bytes (64 nibbles) of zero.
|
||||
|
||||
|
||||
_subsection: Strings
|
||||
|
||||
_property: ethers.constants.EtherSymbol => string @<constants-EtherSymbol> @SRC<constants>
|
||||
The Ether symbol, **Ξ**.
|
||||
|
||||
|
||||
_subsection: BigNumber
|
||||
|
||||
_property: ethers.constants.NegativeOne => [[BigNumber]] @<constants-NegativeOne> @SRC<constants>
|
||||
The BigNumber value representing ``"-1"``.
|
||||
|
||||
_property: ethers.constants.Zero => [[BigNumber]] @<constants-Zero> @SRC<constants>
|
||||
The BigNumber value representing ``"0"``.
|
||||
|
||||
_property: ethers.constants.One => [[BigNumber]] @<constants-One> @SRC<constants>
|
||||
The BigNumber value representing ``"1"``.
|
||||
|
||||
_property: ethers.constants.Two => [[BigNumber]] @<constants-Two> @SRC<constants>
|
||||
The BigNumber value representing ``"2"``.
|
||||
|
||||
_property: ethers.constants.WeiPerEther => [[BigNumber]] @<constants-WeiPerEther> @SRC<constants>
|
||||
The BigNumber value representing ``"1000000000000000000"``, which is the
|
||||
number of Wei per Ether.
|
||||
|
||||
_property: ethers.constants.MaxUint256 => [[BigNumber]] @<constants-MaxUint256> @SRC<constants>
|
||||
The BigNumber value representing the maximum ``uint256`` value.
|
||||
|
||||
|
||||
|
||||
154
docs.wrm/api/utils/display-logic.wrm
Normal file
154
docs.wrm/api/utils/display-logic.wrm
Normal file
@ -0,0 +1,154 @@
|
||||
_section: Display Logic and Input @<display-logic>
|
||||
|
||||
When creating an Application, it is useful to convert between
|
||||
user-friendly strings (usually displaying **ether**) and the
|
||||
machine-readable values that contracts and maths depend on
|
||||
(usually in **wei**).
|
||||
|
||||
For example, a Wallet may specify the balance in ether, and
|
||||
gas prices in gwei for the User Interface, but when sending
|
||||
a transaction, both must be specified in wei.
|
||||
|
||||
The [parseUnits](unit-conversion) will parse a string representing
|
||||
ether, such as ``1.1`` into a [BigNumber](BigNumber) in wei, and is
|
||||
useful when a user types in a value, such as sending 1.1 ether.
|
||||
|
||||
The [formatUnits](unit-conversion) will format a [BigNumberish](BigNumberish)
|
||||
into a string, which is useful when displaying a balance.
|
||||
|
||||
|
||||
_subsection: Units @<display-logic--units>
|
||||
|
||||
_heading: Decimal Count
|
||||
|
||||
A **Unit** can be specified as a number, which indicates the
|
||||
number of decimal places that should be used.
|
||||
|
||||
**Examples:**
|
||||
|
||||
- 1 ether in wei, has **18** decimal places (i.e. 1 ether represents 10^^18^^ wei)
|
||||
- 1 bitcoin in Satoshi, has **8** decimal places (i.e. 1 bitcoin represents 10^^8^^ satoshi)
|
||||
|
||||
_heading: Named Units @<display-logic--named-units>
|
||||
|
||||
There are also several common **Named Units**, in which case their name (as
|
||||
a string) may be used.
|
||||
|
||||
_table: @STYLE<compact>
|
||||
|
||||
| **Name** | **Decimals** |
|
||||
| //wei// | 0 |
|
||||
| //kwei// | 3 |
|
||||
| //mwei// | 6 |
|
||||
| //gwei// | 9 |
|
||||
| //szabo// | 12 |
|
||||
| //finney// | 15 |
|
||||
| //ether// | 18 |
|
||||
|
||||
|
||||
_subsection: Functions @<display-logic--functions>
|
||||
|
||||
_heading: Formatting @<display-logic--formatting>
|
||||
|
||||
_property: ethers.utils.commify(value) => string @<utils-commify> @SRC<units>
|
||||
Returns a string with value grouped by 3 digits, separated by ``,``.
|
||||
|
||||
_code: @lang<javascript>
|
||||
|
||||
//_hide: const commify = ethers.utils.commify;
|
||||
|
||||
//_result:
|
||||
commify("-1000.3000");
|
||||
//_log:
|
||||
|
||||
_heading: Conversion @<unit-conversion>
|
||||
|
||||
_property: ethers.utils.formatUnits(value [ , unit = "ether" ] ) => string @<utils-formatUnits> @SRC<units>
|
||||
Returns a string representation of //value// formatted with //unit//
|
||||
digits (if it is a number) or to the unit specified (if a string).
|
||||
|
||||
_code: @lang<javascript>
|
||||
|
||||
//_hide: const formatUnits = ethers.utils.formatUnits;
|
||||
//_hide: const BigNumber = ethers.BigNumber;
|
||||
|
||||
const oneGwei = BigNumber.from("1000000000");
|
||||
const oneEther = BigNumber.from("1000000000000000000");
|
||||
|
||||
//_result:
|
||||
formatUnits(oneGwei, 0);
|
||||
//_log:
|
||||
|
||||
//_result:
|
||||
formatUnits(oneGwei, "gwei");
|
||||
//_log:
|
||||
|
||||
//_result:
|
||||
formatUnits(oneGwei, 9);
|
||||
//_log:
|
||||
|
||||
//_result:
|
||||
formatUnits(oneEther);
|
||||
//_log:
|
||||
|
||||
//_result:
|
||||
formatUnits(oneEther, 18);
|
||||
//_log:
|
||||
|
||||
_property: ethers.utils.formatEther(value) => string @<utils-formatEther> @SRC<units>
|
||||
The equivalent to calling ``formatUnits(value, "ether")``.
|
||||
|
||||
_code: @lang<javascript>
|
||||
|
||||
//_hide: const formatEther = ethers.utils.formatEther;
|
||||
//_hide: const BigNumber = ethers.BigNumber;
|
||||
|
||||
const value = BigNumber.from("1000000000000000000");
|
||||
|
||||
//_result:
|
||||
formatEther(value);
|
||||
//_log:
|
||||
|
||||
_property: ethers.utils.parseUnits(value [ , unit = "ether" ] ) => [BigNumber](BigNumber) @<utils-parseUnits> @SRC<units>
|
||||
Returns a [BigNumber](BigNumber) representation of //value//, parsed with
|
||||
//unit// digits (if it is a number) or from the unit specified (if
|
||||
a string).
|
||||
|
||||
_code: @lang<javascript>
|
||||
|
||||
//_hide: const parseUnits = ethers.utils.parseUnits;
|
||||
|
||||
//_result:
|
||||
parseUnits("1.0");
|
||||
//_log:
|
||||
|
||||
//_result:
|
||||
parseUnits("1.0", "ether");
|
||||
//_log:
|
||||
|
||||
//_result:
|
||||
parseUnits("1.0", 18);
|
||||
//_log:
|
||||
|
||||
//_result:
|
||||
parseUnits("121.0", "gwei");
|
||||
//_log:
|
||||
|
||||
//_result:
|
||||
parseUnits("121.0", 9);
|
||||
//_log:
|
||||
|
||||
_property: ethers.utils.parseEther(value) => [BigNumber](BigNumber) @<utils-parseEther> @SRC<units>
|
||||
The equivalent to calling ``parseUnits(value, "ether")``.
|
||||
|
||||
_code: @lang<javascript>
|
||||
|
||||
//_hide: const parseEther = ethers.utils.parseEther;
|
||||
|
||||
//_result:
|
||||
parseEther("1.0");
|
||||
//_log:
|
||||
|
||||
//_result:
|
||||
parseEther("-0.5");
|
||||
//_log:
|
||||
127
docs.wrm/api/utils/encoding.wrm
Normal file
127
docs.wrm/api/utils/encoding.wrm
Normal file
@ -0,0 +1,127 @@
|
||||
_section: Encoding Utilities @<encoding>
|
||||
|
||||
_subsection: Base58 @<Bse58> @SRC<basex:Base58>
|
||||
|
||||
_property: ethers.utils.base58.decode(textData) => Uint8Array
|
||||
Return a typed Uint8Array representation of //textData// decoded using
|
||||
base-58 encoding.
|
||||
|
||||
_code: @lang<javascript>
|
||||
|
||||
//_hide: const base58 = ethers.utils.base58;
|
||||
|
||||
//_result:
|
||||
base58.decode("TzMhH");
|
||||
//_log:
|
||||
|
||||
_property: ethers.utils.base58.encode(aBytesLike) => string
|
||||
Return //aBytesLike// encoded as a string using the base-58 encoding.
|
||||
|
||||
_code: @lang<javascript>
|
||||
|
||||
//_hide: const base58 = ethers.utils.base58;
|
||||
|
||||
//_result:
|
||||
base58.encode("0x12345678");
|
||||
//_log:
|
||||
|
||||
//_result:
|
||||
base58.encode([ 0x12, 0x34, 0x56, 0x78 ]);
|
||||
//_log:
|
||||
|
||||
|
||||
_subsection: Base64 @<Base64>
|
||||
|
||||
_property: ethers.utils.base64.decode(textData) => Uint8Array @SRC<base64>
|
||||
Return a typed Uint8Array representation of //textData// decoded using
|
||||
base-64 encoding.
|
||||
|
||||
_code: @lang<javascript>
|
||||
|
||||
//_hide: const base64 = ethers.utils.base64;
|
||||
|
||||
//_result:
|
||||
base64.decode("EjQ=");
|
||||
//_log:
|
||||
|
||||
_property: ethers.utils.base64.encode(aBytesLike) => string @SRC<base64>
|
||||
Return //aBytesLike// encoded as a string using the base-64 encoding.
|
||||
|
||||
_code: @lang<javascript>
|
||||
|
||||
//_hide: const base64 = ethers.utils.base64;
|
||||
|
||||
//_result:
|
||||
base64.encode("0x1234");
|
||||
//_log:
|
||||
|
||||
//_result:
|
||||
base64.encode([ 0x12, 0x34 ]);
|
||||
//_log:
|
||||
|
||||
|
||||
_subsection: Recursive-Length Prefix @<rlp--methods>
|
||||
|
||||
The [[link-rlp]] encoding is used throughout Ethereum to serialize nested
|
||||
structures of Arrays and data.
|
||||
|
||||
_property: ethers.utils.RLP.encode(dataObject) => string<[[DataHexString]]> @<utils-rlpEncode> @SRC<rlp>
|
||||
Encode a structured [Data Object](rlp--dataobject) into its RLP-encoded representation.
|
||||
|
||||
_code: @lang<javascript>
|
||||
|
||||
//_hide: const RLP = ethers.utils.RLP;
|
||||
|
||||
//_result:
|
||||
RLP.encode("0x12345678");
|
||||
//_log:
|
||||
|
||||
//_result:
|
||||
RLP.encode([ "0x12345678" ]);
|
||||
//_log:
|
||||
|
||||
//_result:
|
||||
RLP.encode([ new Uint8Array([ 0x12, 0x34, 0x56, 0x78 ]) ]);
|
||||
//_log:
|
||||
|
||||
//_result:
|
||||
RLP.encode([ [ "0x42", [ "0x43" ] ], "0x12345678", [ ] ]);
|
||||
//_log:
|
||||
|
||||
//_result:
|
||||
RLP.encode([ ]);
|
||||
//_log:
|
||||
|
||||
_property: ethers.utils.RLP.decode(aBytesLike) => [DataObject](rlp--dataobject) @<utils.rlpDecode> @SRC<rlp>
|
||||
Decode an RLP-encoded //aBytesLike// into its structured [Data Object](rlp--dataobject).
|
||||
|
||||
All Data components will be returned as a [[DataHexString]].
|
||||
|
||||
_code: @lang<javascript>
|
||||
|
||||
//_hide: const RLP = ethers.utils.RLP;
|
||||
|
||||
//_result:
|
||||
RLP.decode("0x8412345678");
|
||||
//_log:
|
||||
|
||||
//_result:
|
||||
RLP.decode("0xcac342c1438412345678c0");
|
||||
//_log:
|
||||
|
||||
//_result:
|
||||
RLP.decode("0xc0");
|
||||
//_log:
|
||||
|
||||
_heading: Data Object @<rlp--dataobject>
|
||||
|
||||
A **Data Object** is a recursive structure which is used to serialize many
|
||||
internal structures in Ethereum. Each **Data Object** can either be:
|
||||
|
||||
- Binary Data
|
||||
- An Array of **Data Objects** (i.e. this recursively includes Nesting)
|
||||
|
||||
_definition: **Examples**
|
||||
|
||||
- ``"0x1234"``
|
||||
- ``[ "0x1234", [ "0xdead", "0xbeef" ], [ ] ]``
|
||||
132
docs.wrm/api/utils/fixednumber.wrm
Normal file
132
docs.wrm/api/utils/fixednumber.wrm
Normal file
@ -0,0 +1,132 @@
|
||||
_section: FixedNumber @<FixedNumber>
|
||||
|
||||
A **FixedNumber** is a fixed-width (in bits) number with an internal
|
||||
base-10 divisor, which allows it to represent a decimal fractional
|
||||
component.
|
||||
|
||||
_subsection: Creating Instances
|
||||
|
||||
The FixedNumber constructor cannot be called directly. There are several
|
||||
static methods for creating a FixedNumber.
|
||||
|
||||
_property: FixedNumber.from(value [ , format = "fixed" ] ) => [[FixedNumber]] @SRC<bignumber:FixedNumber.from>
|
||||
Returns an instance of a **FixedNumber** for //value// as a //format//.
|
||||
|
||||
_property: FixedNumber.fromBytes(aBytesLike [ , format = "fixed" ] ) => [[FixedNumber]] @SRC<bignumber>
|
||||
Returns an instance of a **FixedNumber** for //value// as a //format//.
|
||||
|
||||
_property: FixedNumber.fromString(value [ , format = "fixed" ] ) => [[FixedNumber]] @SRC<bignumber:FixedNumber.fromString>
|
||||
Returns an instance of a **FixedNumber** for //value// as a //format//. The //value// must
|
||||
not contain more decimals than the //format// permits.
|
||||
|
||||
_property: FixedNumber.fromValue(value [ , decimals = 0 [ , format = "fixed" ] ] ) => [[FixedNumber]] @SRC<bignumber:FixedNumber.fromValue>
|
||||
Returns an instance of a **FixedNumber** for //value// with //decimals// as a //format//.
|
||||
|
||||
|
||||
_subsection: Properties
|
||||
|
||||
_property: fixednumber.format
|
||||
The [FixedFormat](FixedFormat) of //fixednumber//.
|
||||
|
||||
|
||||
_subsection: Methods
|
||||
|
||||
_heading: Math Operations
|
||||
|
||||
_property: fixednumber.addUnsafe(otherValue) => [[FixedNumber]] @SRC<bignumber/fixednumber>
|
||||
Returns a new FixedNumber with the value of //fixedvalue// **+** //otherValue//.
|
||||
|
||||
_property: fixednumber.subUnsafe(otherValue) => [[FixedNumber]] @SRC<bignumber/fixednumber>
|
||||
Returns a new FixedNumber with the value of //fixedvalue// **-** //otherValue//.
|
||||
|
||||
_property: fixednumber.mulUnsafe(otherValue) => [[FixedNumber]] @SRC<bignumber/fixednumber>
|
||||
Returns a new FixedNumber with the value of //fixedvalue// **×** //otherValue//.
|
||||
|
||||
_property: fixednumber.divUnsafe(otherValue) => [[FixedNumber]] @SRC<bignumber/fixednumber>
|
||||
Returns a new FixedNumber with the value of //fixedvalue// **÷** //otherValue//.
|
||||
|
||||
_property: fixednumber.round([ decimals = 0 ]) => [[FixedNumber]] @SRC<bignumber/fixednumber>
|
||||
Returns a new FixedNumber with the value of //fixedvalue// rounded to //decimals//.
|
||||
|
||||
|
||||
_heading: Comparison and Equivalence
|
||||
|
||||
_property: FixedNumber.isZero() => boolean @SRC<bignumber/fixednumber:FixedNumber.isZero>
|
||||
Returns true if and only if the value of //FixedNumber// is zero.
|
||||
|
||||
|
||||
_heading: Conversion
|
||||
|
||||
_property: fixednumber.toFormat(format) => [[FixedNumber]] @SRC<bignumber/fixednumber>
|
||||
Returns a new FixedNumber with the value of //fixedvalue// with //format//.
|
||||
|
||||
_property: fixednumber.toHexString() => string @SRC<bignumber/fixednumber>
|
||||
Returns a [[HexString]] representation of //fixednumber//.
|
||||
|
||||
_property: fixednumber.toString() => string @SRC<bignumber/fixednumber>
|
||||
Returns a string representation of //fixednumber//.
|
||||
|
||||
_property: fixednumber.toUnsafeFloat() => float @SRC<bignumber/fixednumber>
|
||||
Returns a floating-point JavaScript number value of //fixednumber//.
|
||||
Due to rounding in JavaScript numbers, the value is only approximate.
|
||||
|
||||
|
||||
_heading: Inspection
|
||||
|
||||
_property: FixedNumber.isFixedNumber(value) => boolean @SRC<bignumber/fixednumber>
|
||||
Returns true if and only if //value// is a **FixedNumber**.
|
||||
|
||||
|
||||
_subsection: FixedFormat @<FixedFormat>
|
||||
|
||||
A **FixedFormat** is a simple object which represents a decimal
|
||||
(base-10) Fixed-Point data representation. Usually using this
|
||||
class directly is unnecessary, as passing in a [[FixedFormat--strings]]
|
||||
directly into the [[FixedNumber]] will automatically create this.
|
||||
|
||||
_heading: Format Strings @<FixedFormat--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 congruent 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]] @<FixedNumber-from> @SRC<bignumber/fixednumber:FixedFormat.from>
|
||||
|
||||
Returns a new instance of a **FixedFormat** defined by //value//. Any valid [[FixedFormat--strings]]
|
||||
may be passed in as well as any object which has any of ``signed``, ``width`` and ``decimals``
|
||||
defined, including a [[FixedFormat]] object.
|
||||
|
||||
_heading: Properties
|
||||
|
||||
_property: fixedFormat.signed => boolean
|
||||
The signed-ness of //fixedFormat//, true if negative values are supported.
|
||||
|
||||
_property: fixedFormat.width => number
|
||||
The width (in bits) of //fixedFormat//.
|
||||
|
||||
_property: fixedFormat.decimals => number
|
||||
The number of decimal points of //fixedFormat//.
|
||||
|
||||
_property: fixedFormat.name => string
|
||||
The name of the //fixedFormat//, which can be used to recreate the format
|
||||
and is the string that the Solidity language uses to represent this format.
|
||||
|
||||
_definition: **//"fixed"//**
|
||||
A shorthand for ``fixed128x80``.
|
||||
|
||||
383
docs.wrm/api/utils/hashing.wrm
Normal file
383
docs.wrm/api/utils/hashing.wrm
Normal file
@ -0,0 +1,383 @@
|
||||
_section: Hashing Algorithms @<hashing-algorithms>
|
||||
|
||||
There are many hashing algorithms used throughout the blockchain
|
||||
space as well as some more complex usages which require utilities
|
||||
to facilitate these common operations.
|
||||
|
||||
|
||||
_subsection: Cryptographic Hash Functions @<cryptographic-hash-functions>
|
||||
|
||||
The [Cryptographic Hash Functions](link-wiki-cryptographichash)
|
||||
are a specific family of hash functions.
|
||||
|
||||
_property: ethers.utils.id(text) => string<[[DataHexString]]<32>> @<utils-id> @SRC<hash>
|
||||
The Ethereum Identity function computes the [KECCAK256](link-wiki-sha3) hash of the //text// bytes.
|
||||
|
||||
_property: ethers.utils.keccak256(aBytesLike) => string<[[DataHexString]]<32>> @<utils-keccak256> @SRC<keccak256>
|
||||
Returns the [KECCAK256](link-wiki-sha3) digest //aBytesLike//.
|
||||
|
||||
_property: ethers.utils.ripemd160(aBytesLike) => string<[[DataHexString]]<20>> @<utils-ripemd160> @SRC<sha2>
|
||||
Returns the [RIPEMD-160](link-wiki-ripemd) digest of //aBytesLike//.
|
||||
|
||||
_property: ethers.utils.sha256(aBytesLike) => string<[[DataHexString]]<32>> @<utils-sha256> @SRC<sha2:function.sha256>
|
||||
Returns the [SHA2-256](link-wiki-sha2) digest of //aBytesLike//.
|
||||
|
||||
_property: ethers.utils.sha512(aBytesLike) => string<[[DataHexString]]<64>> @<utils-sha512> @SRC<sha2:function.sha512>
|
||||
Returns the [SHA2-512](link-wiki-sha2) digest of //aBytesLike//.
|
||||
|
||||
_code: KECCAK256 @lang<javascript>
|
||||
|
||||
//_result:
|
||||
utils.keccak256([ 0x12, 0x34 ])
|
||||
//_log:
|
||||
|
||||
//_result:
|
||||
utils.keccak256("0x")
|
||||
//_log:
|
||||
|
||||
//_result:
|
||||
utils.keccak256("0x1234")
|
||||
//_log:
|
||||
|
||||
// The value MUST be data, such as:
|
||||
// - an Array of numbers
|
||||
// - a data hex string (e.g. "0x1234")
|
||||
// - a Uint8Array
|
||||
|
||||
// Do NOT use UTF-8 strings that are not a DataHexstring
|
||||
//_throws:
|
||||
utils.keccak256("hello world")
|
||||
//_log:
|
||||
|
||||
// If needed, convert strings to bytes first:
|
||||
//_result:
|
||||
utils.keccak256(utils.toUtf8Bytes("hello world"))
|
||||
//_log:
|
||||
|
||||
// Or equivalently use the identity function:
|
||||
//_result:
|
||||
utils.id("hello world")
|
||||
//_log:
|
||||
|
||||
// Keep in mind that the string "0x1234" represents TWO
|
||||
// bytes (i.e. [ 0x12, 0x34 ]. If you wish to compute the
|
||||
// hash of the 6 characters "0x1234", convert it to UTF-8
|
||||
// bytes first using utils.toUtf8Bytes.
|
||||
|
||||
// Consider the following examples:
|
||||
|
||||
// Hash of TWO (2) bytes:
|
||||
//_result:
|
||||
utils.keccak256("0x1234")
|
||||
//_log:
|
||||
|
||||
// Hash of TWO (2) bytes: (same result)
|
||||
//_result:
|
||||
utils.keccak256([ 0x12, 0x34 ])
|
||||
//_log:
|
||||
|
||||
//_result:
|
||||
bytes = utils.toUtf8Bytes("0x1234")
|
||||
//_log:
|
||||
|
||||
// Hash of SIX (6) characters (different than above)
|
||||
//_result:
|
||||
utils.keccak256(bytes)
|
||||
//_log:
|
||||
|
||||
// Hash of SIX (6) characters (same result)
|
||||
//_result:
|
||||
utils.id("0x1234")
|
||||
//_log:
|
||||
|
||||
_code: RIPEMD160 @lang<javascript>
|
||||
|
||||
//_result:
|
||||
utils.ripemd160("0x")
|
||||
//_log:
|
||||
|
||||
//_result:
|
||||
utils.ripemd160("0x1234")
|
||||
//_log:
|
||||
|
||||
_code: SHA-2 @lang<javascript>
|
||||
|
||||
//_result:
|
||||
utils.sha256("0x")
|
||||
//_log:
|
||||
|
||||
//_result:
|
||||
utils.sha256("0x1234")
|
||||
//_log:
|
||||
|
||||
//_result:
|
||||
utils.sha512("0x")
|
||||
//_log:
|
||||
|
||||
//_result:
|
||||
utils.sha512("0x1234")
|
||||
//_log:
|
||||
|
||||
|
||||
_subsection: HMAC @<utils--hmac>
|
||||
|
||||
_property: ethers.utils.computeHmac(algorithm, key, data) => string<[[DataHexString]]> @<utils-computeHmac> @SRC<sha2>
|
||||
Returns the [HMAC](link-wiki-hmac) of //data// with //key//
|
||||
using the [Algorithm](utils--hmac-supported-algorithm) //algorithm//.
|
||||
|
||||
_heading: **HMAC Supported Algorithms** @<utils--hmac-supported-algorithm> @SRC<sha2:enum.SupportedAlgorithm>
|
||||
|
||||
_property: ethers.utils.SupportedAlgorithm.sha256 => string
|
||||
Use the [SHA2-256](link-wiki-sha2) hash algorithm.
|
||||
|
||||
_property: ethers.utils.SupportedAlgorithm.sha512 => string
|
||||
Use the [SHA2-512](link-wiki-sha2) hash algorithm.
|
||||
|
||||
_code: HMAC @lang<javascript>
|
||||
|
||||
const key = "0x0102"
|
||||
const data = "0x1234"
|
||||
//_result:
|
||||
utils.computeHmac("sha256", key, data)
|
||||
//_log:
|
||||
|
||||
|
||||
_subsection: Hashing Helpers @<utils--hashing-helpers>
|
||||
|
||||
_property: ethers.utils.hashMessage(message) => string<[[DataHexString]]<32>> @<utils-hashMessage> @SRC<hash>
|
||||
Computes the [[link-eip-191]] personal message digest of //message//. Personal messages are
|
||||
converted to UTF-8 bytes and prefixed with ``\\x19Ethereum Signed Message:``
|
||||
and the length of //message//.
|
||||
|
||||
_code: Hashing Messages @lang<javascript>
|
||||
|
||||
// Hashing a string message
|
||||
//_result:
|
||||
utils.hashMessage("Hello World")
|
||||
//_log:
|
||||
|
||||
// Hashing binary data (also "Hello World", but as bytes)
|
||||
//_result:
|
||||
utils.hashMessage( [ 72, 101, 108, 108, 111, 32, 87, 111, 114, 108, 100 ])
|
||||
//_log:
|
||||
|
||||
// NOTE: It is important to understand how strings and binary
|
||||
// data is handled differently. A string is ALWAYS processed
|
||||
// as the bytes of the string, so a hexstring MUST be
|
||||
// converted to an ArrayLike object first.
|
||||
|
||||
// Hashing a hex string is the same as hashing a STRING
|
||||
// Note: this is the hash of the 4 characters [ '0', 'x', '4', '2' ]
|
||||
//_result:
|
||||
utils.hashMessage("0x42")
|
||||
//_log:
|
||||
|
||||
// Hashing the binary data
|
||||
// Note: this is the hash of the 1 byte [ 0x42 ]
|
||||
//_result:
|
||||
utils.hashMessage([ 0x42 ])
|
||||
//_log:
|
||||
|
||||
// Hashing the binary data
|
||||
// Note: similarly, this is the hash of the 1 byte [ 0x42 ]
|
||||
//_result:
|
||||
utils.hashMessage(utils.arrayify("0x42"))
|
||||
//_log:
|
||||
|
||||
|
||||
_property: ethers.utils.namehash(name) => string<[[DataHexString]]<32>> @<utils-namehash> @SRC<hash>
|
||||
Returns the [ENS Namehash](link-namehash) of //name//.
|
||||
|
||||
_code: Namehash @lang<javascript>
|
||||
|
||||
//_result:
|
||||
utils.namehash("")
|
||||
//_log:
|
||||
|
||||
//_result:
|
||||
utils.namehash("eth")
|
||||
//_log:
|
||||
|
||||
//_result:
|
||||
utils.namehash("ricmoo.firefly.eth")
|
||||
//_log:
|
||||
|
||||
//_result:
|
||||
utils.namehash("ricmoo.xyz")
|
||||
//_log:
|
||||
|
||||
_heading: Typed Data Encoder @<TypedDataEncoder> @SRC<hash:class.TypedDataEncoder>
|
||||
|
||||
The **TypedDataEncoder** is used to compute the various encoded data required
|
||||
for [[link-eip-712]] signed data.
|
||||
|
||||
Signed data requires a domain, list of structures and their members and the data
|
||||
itself.
|
||||
|
||||
The **domain** is an object with values for any of the standard domain
|
||||
properties.
|
||||
|
||||
The **types** is an object with each property being the name of a structure, mapping
|
||||
to an array of field descriptions. It should **not** include the ``EIP712Domain``
|
||||
property unless it is required as a child structure of another.
|
||||
|
||||
_note: Experimental Feature (this exported class name will change)
|
||||
This is still an experimental feature. If using it, please specify the **exact**
|
||||
version of ethers you are using (e.g. spcify ``"5.0.18"``, **not** ``"^5.0.18"``) as
|
||||
the exported class name will be renamed from ``_TypedDataEncoder`` to ``TypedDataEncoder`` once
|
||||
it has been used in the field a bit.
|
||||
|
||||
_property: ethers.utils._TypedDataEncoder.from(types) => [TypedDataEncoder] @<TypedDataEncoder-from> @SRC<hash:TypedDataEncoder.from>
|
||||
|
||||
Creates a new **TypedDataEncoder** for //types//. This object is a fairly
|
||||
low-level object that most developers should not require using instances
|
||||
directly.
|
||||
|
||||
Most developers will find the static class methods below the most useful.
|
||||
|
||||
_property: TypedDataEncoder.encode(domain, types, values) => string @<TypedDataEncoder-encode> @SRC<hash:staticmethod.TypedDataEncoder.encode>
|
||||
|
||||
Encodes the Returns the hashed [[link-eip-712]] domain.
|
||||
|
||||
_property: TypedDataEncoder.getPayload(domain, types, value) => any @<TypedDataEncoder-getPayload> @SRC<hash:TypedDataEncoder.getPayload>
|
||||
|
||||
Returns the standard payload used by various JSON-RPC ``eth_signTypedData*``
|
||||
calls.
|
||||
|
||||
All domain values and entries in value are normalized and the types are
|
||||
verified.
|
||||
|
||||
_property: TypedDataEncoder.getPrimaryType(types) => string @<TypedDataEncoder-getPrimaryType> @SRC<hash:TypedDataEncoder.getPrimaryType>
|
||||
|
||||
Constructs a directed acyclic graph of the types and returns the
|
||||
root type, which can be used as the **primaryType** for [[link-eip-712]]
|
||||
payloads.
|
||||
|
||||
_property: TypedDataEncoder.hash(domain, types, values) => string<[[DataHexString]]<32>> @<TypedDataEncoder-hash> @SRC<hash:staticmethod.TypedDataEncoder.hash>
|
||||
|
||||
Returns the computed [[link-eip-712]] hash.
|
||||
|
||||
_property: TypedDataEncoder.hashDomain(domain) => string<[[DataHexString]]<32>> @<TypedDataEncoder-hashDomain> @SRC<hash:TypedDataEncoder.hashDomain>
|
||||
|
||||
Returns the hashed [[link-eip-712]] domain.
|
||||
|
||||
_property: TypedDataEncoder.resolveNames(domain, types, value, resolveName) => Promise<any> @<TypedDataEncoder-resolveNames> @SRC<hash:TypedDataEncoder.resolveNames>
|
||||
|
||||
Returns a copy of value, where any leaf value with a type of ``address`` will have
|
||||
been recursively replacedwith the value of calling //resolveName// with that value.
|
||||
|
||||
_code: Typed Data Example @lang<javascript>
|
||||
|
||||
//_hide: TypedDataEncoder = ethers.utils._TypedDataEncoder
|
||||
|
||||
domain = {
|
||||
name: 'Ether Mail',
|
||||
version: '1',
|
||||
chainId: 1,
|
||||
verifyingContract: '0xCcCCccccCCCCcCCCCCCcCcCccCcCCCcCcccccccC'
|
||||
};
|
||||
|
||||
// The named list of all type definitions
|
||||
types = {
|
||||
Person: [
|
||||
{ name: 'name', type: 'string' },
|
||||
{ name: 'wallet', type: 'address' }
|
||||
],
|
||||
Mail: [
|
||||
{ name: 'from', type: 'Person' },
|
||||
{ name: 'to', type: 'Person' },
|
||||
{ name: 'contents', type: 'string' }
|
||||
]
|
||||
};
|
||||
|
||||
// The data to sign
|
||||
value = {
|
||||
from: {
|
||||
name: 'Cow',
|
||||
wallet: '0xCD2a3d9F938E13CD947Ec05AbC7FE734Df8DD826'
|
||||
},
|
||||
to: {
|
||||
name: 'Bob',
|
||||
wallet: '0xbBbBBBBbbBBBbbbBbbBbbbbBBbBbbbbBbBbbBBbB'
|
||||
},
|
||||
contents: 'Hello, Bob!'
|
||||
};
|
||||
|
||||
//_result:
|
||||
TypedDataEncoder.encode(domain, types, value)
|
||||
//_log:
|
||||
|
||||
//_result:
|
||||
TypedDataEncoder.getPayload(domain, types, value)
|
||||
//_log:
|
||||
|
||||
//_result:
|
||||
TypedDataEncoder.getPrimaryType(types)
|
||||
//_log:
|
||||
|
||||
//_result:
|
||||
TypedDataEncoder.hash(domain, types, value)
|
||||
//_log:
|
||||
|
||||
//_result:
|
||||
TypedDataEncoder.hashDomain(domain)
|
||||
//_log:
|
||||
|
||||
|
||||
_subsection: Solidity Hashing Algorithms @<utils--solidity-hashing>
|
||||
|
||||
When using the Solidity ``abi.packEncoded(...)`` function, a non-standard
|
||||
//tightly packed// version of encoding is used. These functions implement
|
||||
the tightly packing algorithm.
|
||||
|
||||
_property: ethers.utils.solidityPack(types, values) => string<[[DataHexString]]> @<utils-solidityPack> @SRC<solidity:pack>
|
||||
Returns the non-standard encoded //values// packed according to
|
||||
their respective type in //types//.
|
||||
|
||||
_property: ethers.utils.solidityKeccak256(types, values) => string<[[DataHexString]]<32>> @<utils-solidityKeccak256> @SRC<solidity:keccak256>
|
||||
Returns the [KECCAK256](link-wiki-sha3) of the non-standard encoded //values// packed
|
||||
according to their respective type in //types//.
|
||||
|
||||
_property: ethers.utils.soliditySha256(types, values) => string<[[DataHexString]]<32>> @<utils-soliditySha256> @SRC<solidity:sha256>
|
||||
Returns the [SHA2-256](link-wiki-sha2) of the non-standard encoded //values// packed
|
||||
according to their respective type in //types//.
|
||||
|
||||
_code: Solidity Hashing @lang<javascript>
|
||||
|
||||
//_result:
|
||||
utils.solidityPack([ "int16", "uint48" ], [ -1, 12 ])
|
||||
//_log:
|
||||
|
||||
//_result:
|
||||
utils.solidityPack([ "string", "uint8" ], [ "Hello", 3 ])
|
||||
//_log:
|
||||
|
||||
//_result:
|
||||
utils.solidityKeccak256([ "int16", "uint48" ], [ -1, 12 ])
|
||||
//_log:
|
||||
|
||||
//_result:
|
||||
utils.soliditySha256([ "int16", "uint48" ], [ -1, 12 ])
|
||||
//_log:
|
||||
|
||||
// As a short example of the non-distinguished nature of
|
||||
// Solidity tight-packing (which is why it is inappropriate
|
||||
// for many things from a security point of view), consider
|
||||
// the following examples are all equal, despite representing
|
||||
// very different values and layouts.
|
||||
|
||||
//_result:
|
||||
utils.solidityPack([ "string", "string" ], [ "hello", "world01" ])
|
||||
//_log:
|
||||
|
||||
//_result:
|
||||
utils.solidityPack([ "string", "string" ], [ "helloworld", "01" ])
|
||||
//_log:
|
||||
|
||||
//_result:
|
||||
utils.solidityPack([ "string", "string", "uint16" ], [ "hell", "oworld", 0x3031 ])
|
||||
//_log:
|
||||
|
||||
//_result:
|
||||
utils.solidityPack([ "uint96" ], [ "32309054545061485574011236401" ])
|
||||
//_log:
|
||||
135
docs.wrm/api/utils/hdnode.wrm
Normal file
135
docs.wrm/api/utils/hdnode.wrm
Normal file
@ -0,0 +1,135 @@
|
||||
_section: HD Wallet @<hdnodes>
|
||||
|
||||
The Hierarchal Desterministic (HD) Wallet was a standard
|
||||
created for Bitcoin, but lends itself well to a wide variety of
|
||||
Blockchains which rely on secp256k1 private keys.
|
||||
|
||||
For a more detailed technical understanding:
|
||||
|
||||
- [BIP-32](link-bip-32) - the hierarchal deterministic description
|
||||
- [BIP-39](link-bip-39) - the method used to derive the BIP-32 seed
|
||||
from human-readable sequences of words (i.e. a mnemonic)
|
||||
- [BIP-44](link-bip-44) - a standard defined to make BIP-32 easy
|
||||
to adapt to any future compatible blockchain
|
||||
|
||||
_subsection: Types
|
||||
|
||||
_heading: Constants @<hdnodes--defaultpath> @SRC<hdnode:defaultPath>
|
||||
|
||||
_property: ethers.utils.defaultPath => "m/44'/60'/0'/0/0"
|
||||
The default path for Ethereum in an HD Wallet
|
||||
|
||||
|
||||
_heading: Mnemonic @<Mnemonic>
|
||||
|
||||
_property: mnemonic.phrase => string
|
||||
The mnemonic phrase for this mnemonic. It is 12, 15, 18, 21 or 24 words long
|
||||
and separated by the whitespace specified by the ``locale``.
|
||||
|
||||
_property: mnemonic.path => string
|
||||
The HD path for this mnemonic.
|
||||
|
||||
_property: mnemonic.locale => string
|
||||
The language of the wordlist this mnemonic is using.
|
||||
|
||||
|
||||
_subsection: HDNode @<HDNode> @SRC<hdnode:class.HDNode>
|
||||
|
||||
_heading: Creating Instances @<HDNode--creating>
|
||||
|
||||
_property: ethers.HDNode.fromMnemonic(phrase [, password [, wordlist ] ]) => [[HDNode]] @<HDNode-fromMnemonic> @SRC<hdnode>
|
||||
Return the [[HDNode]] for //phrase// with the optional //password//
|
||||
and //wordlist//.
|
||||
|
||||
_property: ethers.HDNode.fromSeed(aBytesLike) => [[HDNode]] @<HDNode-fromSeed> @SRC<hdnode>
|
||||
Return the [[HDNode]] for the seed //aBytesLike//.
|
||||
|
||||
_property: ethers.HDNode.fromExtendedKey(extendedKey) => [[HDNode]] @<HDNode-fromExtendedKey> @SRC<hdnode>
|
||||
Return the [[HDNode]] for the //extendedKey//. If //extendedKey// was
|
||||
neutered, the **HDNode** will only be able to compute addresses and not
|
||||
private keys.
|
||||
|
||||
|
||||
_heading: Properties @<HDNode--properties>
|
||||
|
||||
_property: hdNode.privateKey => string<[[DataHexString]]<32>>
|
||||
The private key for this HDNode.
|
||||
|
||||
_property: hdNode.publicKey => string<[[DataHexString]]<33>>
|
||||
The (compresses) public key for this HDNode.
|
||||
|
||||
_property: hdNode.fingerprint => string<[[DataHexString]]<4>>
|
||||
The fingerprint is meant as an index to quickly match parent and
|
||||
children nodes together, however collisions may occur and software
|
||||
should verify matching nodes.
|
||||
|
||||
Most developers will not need to use this.
|
||||
|
||||
_property: hdNode.parentFingerprint => string<[[DataHexString]]<4>>
|
||||
The fingerprint of the parent node. See //fingerprint// for more
|
||||
details.
|
||||
|
||||
Most developers will not need to use this.
|
||||
|
||||
_property: hdNode.address => string<[[address]]>
|
||||
The address of this HDNode.
|
||||
|
||||
_property: hdNode.mnemonic => [[Mnemonic]]
|
||||
The mnemonic of this HDNode, if known.
|
||||
|
||||
_property: hdNode.path => string
|
||||
The path of this HDNode, if known. If the //mnemonic// is also known,
|
||||
this will match ``mnemonic.path``.
|
||||
|
||||
_property: hdNode.chainCode => string<[[DataHexString]]<32>>
|
||||
The chain code is used as a non-secret private key which is then used
|
||||
with EC-multiply to provide the ability to derive addresses without
|
||||
the private key of child non-hardened nodes.
|
||||
|
||||
Most developers will not need to use this.
|
||||
|
||||
_property: hdNode.index => number
|
||||
The index of this HDNode. This will match the last component of
|
||||
the //path//.
|
||||
|
||||
Most developers will not need to use this.
|
||||
|
||||
_property: hdNode.depth => number
|
||||
The depth of this HDNode. This will match the number of components
|
||||
(less one, the ``m/``) of the //path//.
|
||||
|
||||
Most developers will not need to use this.
|
||||
|
||||
_property: hdNode.extendedKey => string
|
||||
A serialized string representation of this HDNode. Not all properties
|
||||
are included in the serialization, such as the mnemonic and path, so
|
||||
serializing and deserializing (using the ``fromExtendedKey`` class
|
||||
method) will result in reduced information.
|
||||
|
||||
|
||||
_heading: Methods @<HDNode--methods>
|
||||
|
||||
_property: hdNode.neuter() => [[HDNode]] @<HDNode-neuter> @SRC<hdnode>
|
||||
Return a new instance of //hdNode// with its private key removed
|
||||
but all other properties preserved. This ensures that the key
|
||||
can not leak the private key of itself or any derived children,
|
||||
but may still be used to compute the addresses of itself and
|
||||
any non-hardened children.
|
||||
|
||||
_property: hdNode.derivePath(path) => [[HDNode]] @<HDNode-derivePath> @SRC<hdnode>
|
||||
Return a new [[HDNode]] which is the child of //hdNode// found
|
||||
by deriving //path//.
|
||||
|
||||
|
||||
|
||||
_subsection: Other Functions @<HDNode--utilities>
|
||||
|
||||
_property: ethers.utils.mnemonicToSeed(phrase [ , password]) => string<[[DataHexString]]<64>> @<utils-mnemonicToSeed> @SRC<hdnode>
|
||||
Convert a mnemonic phrase to a seed, according to [BIP-39](link-bip-39).
|
||||
|
||||
_property: ethers.utils.mnemonicToEntropy(phrase [ , wordlist ]) => string<[[DataHexString]]> @<utils-mnemonicToEntropy> @SRC<hdnode>
|
||||
Convert a mnemonic phrase to its entropy, according to [BIP-39](link-bip-39).
|
||||
|
||||
_property: ethers.utils.isValidMnemonic(phrase [ , wordlist ]) => boolean @<utils-isValidMnemonic> @SRC<hdnode>
|
||||
Returns true if //phrase// is a valid mnemonic phrase, by
|
||||
testing the checksum.
|
||||
23
docs.wrm/api/utils/index.wrm
Normal file
23
docs.wrm/api/utils/index.wrm
Normal file
@ -0,0 +1,23 @@
|
||||
_section: Utilities
|
||||
|
||||
These utilities are used extensively within the library, but
|
||||
are also quite useful for application developers.
|
||||
|
||||
_toc:
|
||||
abi
|
||||
address
|
||||
bignumber
|
||||
bytes
|
||||
constants
|
||||
display-logic
|
||||
encoding
|
||||
fixednumber
|
||||
hashing
|
||||
hdnode
|
||||
logger
|
||||
properties
|
||||
signing-key
|
||||
strings
|
||||
transactions
|
||||
web
|
||||
wordlists
|
||||
263
docs.wrm/api/utils/logger.wrm
Normal file
263
docs.wrm/api/utils/logger.wrm
Normal file
@ -0,0 +1,263 @@
|
||||
_section: Logging @<logging>
|
||||
|
||||
These are just a few simple logging utilities provided to simplify
|
||||
and standardize the error facilities across the Ethers library.
|
||||
|
||||
The [[Logger]] library has zero dependencies and is intentionally
|
||||
very light so it can be easily included in each library.
|
||||
|
||||
The [Censorship](Logger--censorship) functionality relies on one instance
|
||||
of the Ethers library being included. In large bundled packages or when
|
||||
``npm link`` is used, this may not be the case. If you require this
|
||||
functionality, ensure that your bundling is configured properly.
|
||||
|
||||
|
||||
_subsection: Logger @<Logger> @SRC<logger:class.Logger>
|
||||
|
||||
_property: new ethers.utils.Logger(version) @SRC<logger:constructor.Logger>
|
||||
Create a new logger which will include //version// in all errors thrown.
|
||||
|
||||
_property: Logger.globalLogger() => [[Logger]] @SRC<logger>
|
||||
Returns the singleton global logger.
|
||||
|
||||
|
||||
_heading: Logging Output
|
||||
|
||||
_property: logger.debug(...args) => void @SRC<logger>
|
||||
Log debugging information.
|
||||
|
||||
_property: logger.info(...args) => void @SRC<logger>
|
||||
Log generic information.
|
||||
|
||||
_property: logger.warn(...args) => void @SRC<logger>
|
||||
Log warnings.
|
||||
|
||||
|
||||
_heading: Errors
|
||||
|
||||
These functions honor the current [Censorship](Logger--censorship) and help create
|
||||
a standard error model for detecting and processing errors within Ethers.
|
||||
|
||||
_property: logger.makeError(message [ , code = UNKNOWN_ERROR [ , params ] ]) => Error @SRC<logger>
|
||||
Create an Error object with //message// and an optional //code// and
|
||||
additional //params// set. This is useful when an error is needed to be
|
||||
rejected instead of thrown.
|
||||
|
||||
_property: logger.throwError(message [ , code = UNKNOWN_ERROR [ , params ] ]) => never @SRC<logger>
|
||||
Throw an Error with //message// and an optional //code// and
|
||||
additional //params// set.
|
||||
|
||||
_property: logger.throwArgumentError(message, name, value) => never @SRC<logger>
|
||||
Throw an [INVALID_ARGUMENT](errors--invalid-argument) Error with //name// and //value//.
|
||||
|
||||
_heading: Usage Validation
|
||||
|
||||
There can be used to ensure various properties and actions are safe.
|
||||
|
||||
_property: logger.checkAbstract(target, kind) => void @<Logger-checkAbstract> @SRC<logger>
|
||||
If //target// is //kind//, throws a [UNSUPPORTED_OPERATION](errors--unsupported-operation) error
|
||||
otherwise performs the same operations as [checkNew](Logger-checkNew).
|
||||
|
||||
This is useful for ensuring abstract classes are not being instantiated.
|
||||
|
||||
_property: logger.checkArgumentCount(count, expectedCount [ , message) => void @<Logger-checkArgumentCount> @SRC<logger>
|
||||
If //count// is not equal to //expectedCount//, throws a [MISSING_ARGUMENT](errors--missing-argument)
|
||||
or [UNEXPECTED_ARGUMENT](errors--unexpected-argument) error.
|
||||
|
||||
_property: logger.checkNew(target, kind) => void @<Logger-checkNew> @SRC<logger>
|
||||
If //target// is not a valid ``this`` or ``target`` value, throw a
|
||||
[MISSING_NEW](errors--missing-new) error. This is useful to ensure
|
||||
callers of a Class are using ``new``.
|
||||
|
||||
_property: logger.checkNormalize(message) => void @<Logger-checkNoralize> @SRC<logger>
|
||||
Check that the environment has a correctly functioning [[link-js-normalize]]. If not, a
|
||||
[UNSUPPORTED_OPERATION](errors--unsupported-operation) error is thrown.
|
||||
|
||||
_property: logger.checkSafeUint53(value [, message ]) => void @<Logger-checkSafeUint53> @SRC<logger>
|
||||
If //value// is not safe as a [JavaScript number](link-wiki-ieee754), throws a
|
||||
[NUMERIC_FAULT](errors--numeric-fault) error.
|
||||
|
||||
_heading: Censorship @<Logger--censorship>
|
||||
|
||||
_property: Logger.setCensorship(censor [ , permanent = false ]) => void @<Logger-setCensorship> @SRC<logger>
|
||||
Set error censorship, optionally preventing errors from being uncensored.
|
||||
|
||||
In production applications, this prevents any error from leaking information
|
||||
by masking the message and values of errors.
|
||||
|
||||
This can impact debugging, making it substantially more difficult.
|
||||
|
||||
_property: Logger.setLogLevel(logLevel) => void @<Logger-setLogLevel> @SRC<logger>
|
||||
Set the log level, to suppress logging output below a [particular log level](Logger-levels).
|
||||
|
||||
|
||||
_subsection: Errors @<errors>
|
||||
|
||||
Every error in Ethers has a ``code`` value, which is a string that will
|
||||
match one of the following error codes.
|
||||
|
||||
|
||||
_heading: Generic Error Codes @<errors-generic>
|
||||
|
||||
_property: Logger.errors.NOT_IMPLEMENTED @<errors--not-implemented>
|
||||
The operation is not implemented. This may occur when calling a method
|
||||
on a sub-class that has not fully implemented its abstract superclass.
|
||||
|
||||
_property: Logger.errors.SERVER_ERROR @<errors--server-error>
|
||||
There was an error communicating with a server.
|
||||
|
||||
This may occur for a number of reasons, for example:
|
||||
|
||||
- a [CORS](link-cors) issue; this is quite often the problem and also the
|
||||
hardest to diagnose and fix, so it is very beneficial to familiarize
|
||||
yourself with CORS; some backends allow you configure your CORS, such as
|
||||
the geth command-line or conifguration files or the INFURA and Alchemy
|
||||
dashboards by specifing allowed Origins, methods, etc.
|
||||
- an SSL issue; for example, if you are trying to connect to a local node via
|
||||
HTTP but are serving the content from a secure HTTPS website
|
||||
- a link issue; a firewall is preventing the traffic from reaching the server
|
||||
- a server issue; the server is down, or is returning 500 error codes
|
||||
- a backend DDoS mitigation proxy; for example, Etherscan operates behind a
|
||||
Cloudflare proxy, which will block traffic if the request is sent via
|
||||
specific User Agents or the client fingerprint is detected as a bot in some
|
||||
cases
|
||||
|
||||
_property: Logger.errors.TIMEOUT @<errors--timeout>
|
||||
A timeout occurred.
|
||||
|
||||
_property: Logger.errors.UNKNOWN_ERROR @<errors--unknown-error>
|
||||
A generic unknown error.
|
||||
|
||||
_property: Logger.errors.UNSUPPORTED_OPERATION @<errors--unsupported-operation>
|
||||
The operation is not supported.
|
||||
|
||||
This can happen for a variety reasons, for example:
|
||||
|
||||
- Some backends do not support certain operations; such as passing a blockTag
|
||||
to an [[EtherscanProvider]] for [call](Provider-call)
|
||||
- A [[Contract]] object connected to [[Provider]] (instead of a [[Signer]]) cannot
|
||||
[sign](Signer-signTransaction) or [send](Signer-sendTransaction) transactions
|
||||
- a [[Contract]] connected to a [[Signer]] without a [[Provider]] is write-only
|
||||
and cannot estimate gas or execute static calls
|
||||
|
||||
|
||||
_heading: Safety Error Codes @<errors-safety>
|
||||
|
||||
_property: Logger.errors.BUFFER_OVERRUN @<errors--buffer-overrun>
|
||||
The amount of data needed is more than the amount of data required,
|
||||
which would cause the data buffer to read past its end.
|
||||
|
||||
This can occur if a contract erroneously returns invalid ABI-encoded
|
||||
data or RLP data is malformed.
|
||||
|
||||
_property: Logger.errors.NUMERIC_FAULT @<errors--numeric-fault>
|
||||
There was an invalid operation done on numeric values.
|
||||
|
||||
Common cases of this occur when there is [[link-wiki-overflow]],
|
||||
[[link-wiki-underflow]] in fixed numeric types or division by zero.
|
||||
|
||||
|
||||
_heading: Usage Error Codes @<errors-usage>
|
||||
|
||||
_property: Logger.errors.INVALID_ARGUMENT @<errors--invalid-argument>
|
||||
The type or value of an argument is invalid. This will generally also
|
||||
include the ``name`` and ``value`` of the argument. Any function which
|
||||
accepts sensitive data (such as a private key) will include the string
|
||||
``"[\[REDACTED]\]"`` instead of the value passed in.
|
||||
|
||||
_property: Logger.errors.MISSING_ARGUMENT @<errors--missing-argument>
|
||||
An expected parameter was not specified.
|
||||
|
||||
_property: Logger.errors.MISSING_NEW @<errors--missing-new>
|
||||
An object is a Class, but is not being called with ``new``.
|
||||
|
||||
_property: Logger.errors.UNEXPECTED_ARGUMENT @<errors--unexpected-argument>
|
||||
Too many parameters we passed into a function.
|
||||
|
||||
|
||||
_heading: Ethereum Error Codes @<errors-ethereum>
|
||||
|
||||
_property: Logger.errors.CALL_EXCEPTION @<errors--call-exception>
|
||||
An attempt to call a blockchain contract (getter) resulted in a
|
||||
revert or other error, such as insufficient gas (out-of-gas) or an
|
||||
invalid opcode. This can also occur during gas estimation or if
|
||||
waiting for a [[providers-TransactionReceipt]] which failed during execution.
|
||||
|
||||
Consult the contract to determine the cause, such as a failed condition
|
||||
in a ``require`` statement. The ``reason`` property may provide more
|
||||
context for the cause of this error.
|
||||
|
||||
_property: Logger.errors.INSUFFICIENT_FUNDS @<errors--insufficient-funds>
|
||||
The account is attempting to make a transaction which costs more than is
|
||||
available.
|
||||
|
||||
A sending account must have enough ether to pay for the value, the gas limit
|
||||
(at the gas price) as well as the intrinsic cost of data. The intrinsic cost
|
||||
of data is 4 gas for each zero byte and 68 gas for each non-zero byte, as well
|
||||
as 35000 gas if a transaction contains no ``to`` property and is therefore
|
||||
expected to create a new account.
|
||||
|
||||
_property: Logger.errors.NETWORK_ERROR @<errors--network>
|
||||
An Ethereum network validation error, such as an invalid chain ID.
|
||||
|
||||
_property: Logger.errors.NONCE_EXPIRED @<errors--nonce-expired>
|
||||
The nonce being specified has already been used in a mined transaction.
|
||||
|
||||
_property: Logger.errors.REPLACEMENT_UNDERPRICED @<errors--replacement-underpriced>
|
||||
When replacing a transaction, by using a nonce which has already been sent to
|
||||
the network, but which has not been mined yet the new transaction must specify
|
||||
a higher gas price.
|
||||
|
||||
This error occurs when the gas price is insufficient to //bribe// the transaction
|
||||
pool to prefer the new transaction over the old one. Generally, the new gas price
|
||||
should be about 50% + 1 wei more, so if a gas price of 10 gwei was used, the
|
||||
replacement should be 15.000000001 gwei. This is not enforced by the protocol, as
|
||||
it deals with unmined transactions, and can be configured by each node, however
|
||||
to ensure a transaction is propagated to a miner it is best practice to follow
|
||||
the defaults most nodes have enabled.
|
||||
|
||||
_property: Logger.errors.TRANSACTION_REPLACED @<errors--transaction-replaced>
|
||||
When a transaction has been replaced by the user, by broadcasting a new transaction
|
||||
with the same nonce as an existing in-flight (unmined) transaction in the mempool,
|
||||
this error will occur while waiting if the transaction being waited for has become
|
||||
invalidated by that other transaction.
|
||||
|
||||
This can happen for several reasons, but most commonly because the user has increased
|
||||
the gas price (which changes the transaction hash) to "speed up" a transaction or if
|
||||
a user has "cancelled" the transaction in their client. In either case this is
|
||||
usually accomplished by bribing the miners with a higher gas priced transaction.
|
||||
|
||||
This error will have the additional properties, ``cancelled``, ``hash``, ``reason``,
|
||||
``receipt`` and ``replacement``.
|
||||
|
||||
See the [[providers-TransactionResponse]] for the ``wait`` method for more details.
|
||||
|
||||
_property: Logger.errors.UNPREDICTABLE_GAS_LIMIT @<errors--unpredicatable-gas-limit>
|
||||
When estimating the required amount of gas for a transaction, a node is queried for
|
||||
its best guess.
|
||||
|
||||
If a node is unable (or unwilling) to predict the cost, this error occurs.
|
||||
|
||||
The best remedy for this situation is to specify a gas limit in the transaction
|
||||
manually.
|
||||
|
||||
This error can also indicate that the transaction is expected to fail regardless,
|
||||
if for example an account with no tokens is attempting to send a token.
|
||||
|
||||
|
||||
_subsection: Log Levels @<Logger-levels>
|
||||
|
||||
_property: Logger.levels.DEBUG
|
||||
Log all output, including debugging information.
|
||||
|
||||
_property: Logger.levels.INFO
|
||||
Only log output for informational, warnings and errors.
|
||||
|
||||
_property: Logger.levels.WARNING
|
||||
Only log output for warnings and errors.
|
||||
|
||||
_property: Logger.levels.ERROR
|
||||
Only log output for errors.
|
||||
|
||||
_property: Logger.levels.OFF
|
||||
Do not output any logs.
|
||||
40
docs.wrm/api/utils/properties.wrm
Normal file
40
docs.wrm/api/utils/properties.wrm
Normal file
@ -0,0 +1,40 @@
|
||||
_section: Property Utilities
|
||||
|
||||
This is a collection of utility functions used for handling
|
||||
properties in a platform-safe way.
|
||||
|
||||
The next major version of ethers will no longer be compatible
|
||||
with ES3, so many of these will be removed in favor of the
|
||||
built-in options available in ES2015 and above.
|
||||
|
||||
_property: ethers.utils.checkProperties(object, check) => void
|
||||
|
||||
Checks that //object// only contains properties included
|
||||
in //check//, and throws [INVALID_ARGUMENT](errors--invalid-argument) if not.
|
||||
|
||||
_property: ethers.utils.deepCopy(anObject) => any
|
||||
|
||||
Creates a recursive copy of //anObject//. Frozen (i.e. and other known
|
||||
immutable) objects are copied by reference.
|
||||
|
||||
_property: ethers.utils.defineReadOnly(anObject, name, value) => void
|
||||
|
||||
Uses the ``Object.defineProperty`` method to set a read-only property
|
||||
on an object.
|
||||
|
||||
_property: ethers.utils.getStatic(aConstructor, key) => any
|
||||
|
||||
Recursively check for a static method //key// on an inheritance chain
|
||||
from //aConstructor// to all ancestors.
|
||||
|
||||
This is used to mimic behaviour in other languages where ``this`` in
|
||||
a static method will also search ancestors.
|
||||
|
||||
_property: ethers.utils.resolveProperties(anObject) => Promise<any> @<utils-resolveproperties> @SRC<properties>
|
||||
|
||||
Retruns a Promise which resolves all child values on //anObject//.
|
||||
|
||||
_property: ethers.utils.shallowCopy(anObject) => any
|
||||
|
||||
Returns a shallow copy of //anObject//. This is the same as
|
||||
using ``Object.assign({ }, anObject)``.
|
||||
53
docs.wrm/api/utils/signing-key.wrm
Normal file
53
docs.wrm/api/utils/signing-key.wrm
Normal file
@ -0,0 +1,53 @@
|
||||
_section: Signing Key @<SigningKey>
|
||||
|
||||
_property: new ethers.utils.SigningKey(privateKey) @<SigningKey-constructor> @src<signing-key:constructor.SigningKey>
|
||||
Create a new SigningKey for //privateKey//.
|
||||
|
||||
_property: signingKey.privateKey => string<[[DataHexString]]<32>>
|
||||
The private key for this Signing Key.
|
||||
|
||||
_property: signingKey.publicKey => string<[[DataHexString]]<65>>
|
||||
The uncompressed public key for this Signing Key. It will always be
|
||||
65 bytes (130 nibbles) and begins with ``0x04``.
|
||||
|
||||
_property: signingKey.compressedPublicKey => string<[[DataHexString]]<33>>
|
||||
The compressed public key for this Signing Key. It will always be
|
||||
33 bytes (66 nibbles) and begins with either ``0x02`` or ``0x03``.
|
||||
|
||||
_property: signingKey.signDigest(digest) => [[Signature]]
|
||||
Sign the //digest// and return the signature.
|
||||
|
||||
_property: signingKey.computeSharedSecret(otherKey) => string<[[DataHexString]]<32>> @SRC<signing-key>
|
||||
Compute the ECDH shared secret with //otherKey//. The //otherKey// may be
|
||||
either a public key or a private key, but generally will be a public key from
|
||||
another party.
|
||||
|
||||
It is best practice that each party computes the hash of this before using it
|
||||
as a symmetric key.
|
||||
|
||||
_property: SigningKey.isSigningKey(anObject) => boolean @SRC<signing-key>
|
||||
Returns true if //anObject// is a SigningKey.
|
||||
|
||||
|
||||
_subsection: Other Functions
|
||||
|
||||
_property: ethers.utils.verifyMessage(message, signature) => string<[[address]]> @<utils-verifyMessage> @SRC<wallet>
|
||||
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](link-eip-155))
|
||||
to be used since the v parameter is still completely non-ambiguous.
|
||||
|
||||
_property: ethers.utils.verifyTypedData(domain, types, value, signature) => string<[[address]]> @<utils-verifyTypedData> @SRC<wallet>
|
||||
Returns the address that signed the [[link-eip-712]] //value// for the //domain//
|
||||
and //types// to produce the signature.
|
||||
|
||||
_property: ethers.utils.recoverPublicKey(digest, signature) => string<[[DataHexString]]<65>> @<utils-recoverPublicKey>
|
||||
Returns the uncompressed public key (i.e. the first byte will be ``0x04``)
|
||||
of the private key that was used to sign //digest// which gave the //signature//.
|
||||
|
||||
_property: ethers.utils.computePublicKey(key [, compressed = false ]) => string<[[DataHexString]]> @<utils-computePublicKey>
|
||||
Computes the public key of //key//, optionally compressing it. The //key//
|
||||
can be any form of public key (compressed or uncompressed) or a private
|
||||
key.
|
||||
188
docs.wrm/api/utils/strings.wrm
Normal file
188
docs.wrm/api/utils/strings.wrm
Normal file
@ -0,0 +1,188 @@
|
||||
_section: Strings @<strings>
|
||||
|
||||
A **String** is a representation of a human-readable input of output,
|
||||
which are often taken for granted.
|
||||
|
||||
When dealing with blockchains, properly handling human-readable and
|
||||
human-provided data is important to prevent loss of funds, assets,
|
||||
incorrect permissions, etc.
|
||||
|
||||
_subsection: Bytes32String @<Bytes32String>
|
||||
|
||||
A string in Solidity is length prefixed with its 256-bit (32 byte)
|
||||
length, which means that even short strings require 2 words (64 bytes)
|
||||
of storage.
|
||||
|
||||
In many cases, we deal with short strings, so instead of prefixing
|
||||
the string with its length, we can null-terminate it and fit it in a
|
||||
single word (32 bytes). Since we need only a single byte for the
|
||||
null termination, we can store strings up to 31 bytes long in a
|
||||
word.
|
||||
|
||||
_note: Note
|
||||
Strings that are 31 __//bytes//__ long may contain fewer than 31 __//characters//__,
|
||||
since UTF-8 requires multiple bytes to encode international characters.
|
||||
|
||||
_property: ethers.utils.parseBytes32String(aBytesLike) => string @<utils-parseBytes32> @SRC<strings>
|
||||
Returns the decoded string represented by the ``Bytes32`` encoded data.
|
||||
|
||||
_property: ethers.utils.formatBytes32String(text) => string<[[DataHexString]]<32>> @<utils-formatBytes32> @SRC<strings>
|
||||
Returns a ``bytes32`` string representation of //text//. If the
|
||||
length of //text// exceeds 31 bytes, it will throw an error.
|
||||
|
||||
|
||||
_subsection: UTF-8 Strings @<strings-utf8>
|
||||
|
||||
_property: ethers.utils.toUtf8Bytes(text [ , form = current ] ) => Uint8Array @<utils-toUtf8Bytes> @SRC<strings>
|
||||
Returns the UTF-8 bytes of //text//, optionally normalizing it using the
|
||||
[[strings--unicode-normalization-form]] //form//.
|
||||
|
||||
_property: ethers.utils.toUtf8CodePoints(text [ , form = current ] ) => Array<number> @<utils-toUtf8CodePoints> @SRC<strings>
|
||||
Returns the Array of codepoints of //text//, optionally normalized using the
|
||||
[[strings--unicode-normalization-form]] //form//.
|
||||
|
||||
_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, splitting between each UTF-16
|
||||
codeunit instead.
|
||||
|
||||
_property: ethers.utils.toUtf8String(aBytesLike [ , onError = error ] ) => string @<utils-toUtf8String> @SRC<strings>
|
||||
Returns the string represented by the UTF-8 bytes of //aBytesLike//.
|
||||
|
||||
The //onError// is a [Custom UTF-8 Error function](strings--error-handling) and if not specified
|
||||
it defaults to the [error](strings--Utf8Error) function, which throws an error
|
||||
on **any** UTF-8 error.
|
||||
|
||||
_subsection: UnicodeNormalizationForm @<strings--unicode-normalization-form> @SRC<strings/utf8:enum.UnicodeNormalizationForm>
|
||||
|
||||
There are several [commonly used forms](link-wiki-unicode-equivalence)
|
||||
when normalizing UTF-8 data, which allow strings to be compared or hashed in a stable
|
||||
way.
|
||||
|
||||
_property: ethers.utils.UnicodeNormalizationForm.current
|
||||
Maintain the current normalization form.
|
||||
|
||||
_property: ethers.utils.UnicodeNormalizationForm.NFC
|
||||
The Composed Normalization Form. This form uses single codepoints
|
||||
which represent the fully composed character.
|
||||
|
||||
For example, the **é** is a single codepoint, ``0x00e9``.
|
||||
|
||||
_property: ethers.utils.UnicodeNormalizationForm.NFD
|
||||
The Decomposed Normalization Form. This form uses multiple codepoints
|
||||
(when necessary) to compose a character.
|
||||
|
||||
For example, the **é**
|
||||
is made up of two codepoints, ``"0x0065"`` (which is the letter ``"e"``)
|
||||
and ``"0x0301"`` which is a special diacritic UTF-8 codepoint which
|
||||
indicates the previous character should have an acute accent.
|
||||
|
||||
_property: ethers.utils.UnicodeNormalizationForm.NFKC
|
||||
The Composed Normalization Form with Canonical Equivalence. The Canonical
|
||||
representation folds characters which have the same syntactic representation
|
||||
but different semantic meaning.
|
||||
|
||||
For example, the Roman Numeral **I**, which has a UTF-8
|
||||
codepoint ``"0x2160"``, is folded into the capital letter I, ``"0x0049"``.
|
||||
|
||||
_property: ethers.utils.UnicodeNormalizationForm.NFKD
|
||||
The Decomposed Normalization Form with Canonical Equivalence.
|
||||
See NFKC for more an example.
|
||||
|
||||
_note: Note
|
||||
Only certain specified characters are folded in Canonical Equivalence, and thus
|
||||
it should **not** be considered a method to achieve //any// level of security from
|
||||
[homoglyph attacks](link-wiki-homoglyph).
|
||||
|
||||
|
||||
_subsection: Custom UTF-8 Error Handling @<strings--error-handling>
|
||||
|
||||
When converting a string to its codepoints, there is the possibility
|
||||
of invalid byte sequences. Since certain situations may need specific
|
||||
ways to handle UTF-8 errors, a custom error handling function can be used,
|
||||
which has the signature:
|
||||
|
||||
_property: errorFunction(reason, offset, bytes, output [ , badCodepoint ]) => number
|
||||
The //reason// is one of the [UTF-8 Error Reasons](strings--error-reasons), //offset// is the index
|
||||
into //bytes// where the error was first encountered, output is the list
|
||||
of codepoints already processed (and may be modified) and in certain Error
|
||||
Reasons, the //badCodepoint// indicates the currently computed codepoint,
|
||||
but which would be rejected because its value is invalid.
|
||||
|
||||
This function should return the number of bytes to skip past keeping in
|
||||
mind the value at //offset// will already be consumed.
|
||||
|
||||
|
||||
_heading: UTF-8 Error Reasons @<strings--error-reasons> @SRC<strings/utf8:Utf8ErrorReason>
|
||||
|
||||
_property: ethers.utils.Utf8ErrorReason.BAD_PREFIX
|
||||
A byte was encountered which is invalid to begin a UTF-8 byte
|
||||
sequence with.
|
||||
|
||||
_property: ethers.utils.Utf8ErrorReason.MISSING_CONTINUE
|
||||
A UTF-8 sequence was begun, but did not have enough continuation
|
||||
bytes for the sequence. For this error the //ofset// is the index
|
||||
at which a continuation byte was expected.
|
||||
|
||||
_property: ethers.utils.Utf8ErrorReason.OUT_OF_RANGE
|
||||
The computed codepoint is outside the range for valid UTF-8
|
||||
codepoints (i.e. the codepoint is greater than 0x10ffff).
|
||||
This reason will pass the computed //badCountpoint// into
|
||||
the custom error function.
|
||||
|
||||
_property: ethers.utils.Utf8ErrorReason.OVERLONG
|
||||
Due to the way UTF-8 allows variable length byte sequences
|
||||
to be used, it is possible to have multiple representations
|
||||
of the same character, which means
|
||||
[overlong sequences](link-wiki-utf8-overlong)
|
||||
allow for a non-distinguished string to be formed, which can
|
||||
impact security as multiple strings that are otherwise
|
||||
equal can have different hashes.
|
||||
|
||||
Generally, overlong sequences are an attempt to circumvent
|
||||
some part of security, but in rare cases may be produced by
|
||||
lazy libraries or used to encode the null terminating
|
||||
character in a way that is safe to include in a ``char*``.
|
||||
|
||||
This reason will pass the computed //badCountpoint// into the
|
||||
custom error function, which is actually a valid codepoint, just
|
||||
one that was arrived at through unsafe methods.
|
||||
|
||||
_property: ethers.utils.Utf8ErrorReason.OVERRUN
|
||||
The string does not have enough characters remaining for the
|
||||
length of this sequence.
|
||||
|
||||
_property: ethers.utils.Utf8ErrorReason.UNEXPECTED_CONTINUE
|
||||
This error is similar to BAD_PREFIX, since a continuation byte
|
||||
cannot begin a valid sequence, but many may wish to process this
|
||||
differently. However, most developers would want to trap this
|
||||
and perform the same operation as a BAD_PREFIX.
|
||||
|
||||
_property: ethers.utils.Utf8ErrorReason.UTF16_SURROGATE
|
||||
The computed codepoint represents a value reserved for
|
||||
UTF-16 surrogate pairs.
|
||||
This reason will pass the computed surrogate half
|
||||
//badCountpoint// into the custom error function.
|
||||
|
||||
|
||||
|
||||
_heading: Provided UTF-8 Error Handling Functions
|
||||
|
||||
There are already several functions available for the most common
|
||||
situations.
|
||||
|
||||
_property: ethers.utils.Utf8ErrorFuncs.error @<strings--Utf8Error> @SRC<strings/utf8:errorFunc>
|
||||
The will throw an error on **any** error with a UTF-8 sequence, including
|
||||
invalid prefix bytes, overlong sequences, UTF-16 surrogate pairs.
|
||||
|
||||
_property: ethers.utils.Utf8ErrorFuncs.ignore @<strings--Utf8Ignore> @SRC<strings/utf8:ignoreFunc>
|
||||
This will drop all invalid sequences (by consuming invalid prefix bytes and
|
||||
any following continuation bytes) from the final string as well as permit
|
||||
overlong sequences to be converted to their equivalent string.
|
||||
|
||||
_property: ethers.utils.Utf8ErrorFuncs.replace @<strings--Utf8Replace> @SRC<strings/utf8:replaceFunc>
|
||||
This will replace all invalid sequences (by consuming invalid prefix bytes and
|
||||
any following continuation bytes) with the
|
||||
[UTF-8 Replacement Character](link-wiki-utf8-replacement),
|
||||
(i.e. U+FFFD).
|
||||
127
docs.wrm/api/utils/transactions.wrm
Normal file
127
docs.wrm/api/utils/transactions.wrm
Normal file
@ -0,0 +1,127 @@
|
||||
_section: Transactions @<transactions>
|
||||
|
||||
_subsection: Types @<transactions--types>
|
||||
|
||||
_heading: UnsignedTransaction @<UnsignedTransaction>
|
||||
An unsigned transaction represents a transaction that has not been
|
||||
signed and its values are flexible as long as they are not ambiguous.
|
||||
|
||||
_property: unsignedTransaction.to => string<[Address](address)>
|
||||
The address this transaction is to.
|
||||
|
||||
_property: unsignedTransaction.nonce => number
|
||||
The nonce of this transaction.
|
||||
|
||||
_property: unsignedTransaction.gasLimit => [[BigNumberish]]
|
||||
The gas limit for this transaction.
|
||||
|
||||
_property: unsignedTransaction.gasPrice => [[BigNumberish]]
|
||||
The gas price for this transaction.
|
||||
|
||||
_property: unsignedTransaction.data => [[BytesLike]]
|
||||
The data for this transaction.
|
||||
|
||||
_property: unsignedTransaction.value => [[BigNumberish]]
|
||||
The value (in wei) for this transaction.
|
||||
|
||||
_property: unsignedTransaction.chainId => number
|
||||
The chain ID for this transaction. If the chain ID is 0 or null,
|
||||
then [[link-eip-155]] is disabled and legacy signing is
|
||||
used, unless overridden in a signature.
|
||||
|
||||
|
||||
_heading: Transaction @<Transaction>
|
||||
A generic object to represent a transaction.
|
||||
|
||||
_property: transaction.hash => string<[[DataHexString]]<32>>
|
||||
The transaction hash, which can be used as an identifier for
|
||||
//transaction//. This is the keccak256 of the serialized RLP encoded
|
||||
representation of //transaction//.
|
||||
|
||||
_property: unsignedTransaction.to => string<[Address](address)>
|
||||
The address //transaction// is to.
|
||||
|
||||
_property: transaction.from => string<[Address](address)>
|
||||
The address //transaction// is from.
|
||||
|
||||
_property: transaction.nonce => number
|
||||
The nonce for //transaction//. Each transaction sent to the network
|
||||
from an account includes this, which ensures the order and
|
||||
non-replayability of a transaction. This must be equal to the current
|
||||
number of transactions ever sent to the network by the **from** address.
|
||||
|
||||
_property: transaction.gasLimit => [[BigNumber]]
|
||||
The gas limit for //transaction//. An account must have enough ether to
|
||||
cover the gas (at the specified **gasPrice**). Any unused gas is
|
||||
refunded at the end of the transaction, and if there is insufficient gas
|
||||
to complete execution, the effects of the transaction are reverted, but
|
||||
the gas is **fully consumed** and an out-of-gas error occurs.
|
||||
|
||||
_property: transaction.gasPrice => [[BigNumber]]
|
||||
The price (in wei) per unit of gas for //transaction//.
|
||||
|
||||
_property: transaction.data => [[BytesLike]]
|
||||
The data for //transaction//. In a contract this is the call data.
|
||||
|
||||
_property: transaction.value => [[BigNumber]]
|
||||
The value (in wei) for //transaction//.
|
||||
|
||||
_property: transaction.chainId => number
|
||||
The chain ID for //transaction//. This is used as part of
|
||||
[[link-eip-155]] to prevent replay attacks on different
|
||||
networks.
|
||||
|
||||
For example, if a transaction was made on ropsten with an account
|
||||
also used on homestead, it would be possible for a transaction
|
||||
signed on ropsten to be executed on homestead, which is likely
|
||||
unintended.
|
||||
|
||||
There are situations where replay may be desired, however these
|
||||
are very rare and it is almost always recommended to specify the
|
||||
chain ID.
|
||||
|
||||
_property: transaction.r => string<[[DataHexString]]<32>>
|
||||
The r portion of the elliptic curve signatures for //transaction//.
|
||||
This is more accurately, the x coordinate of the point r (from
|
||||
which the y can be computed, along with v).
|
||||
|
||||
_property: transaction.s => string<[[DataHexString]]<32>>
|
||||
The s portion of the elliptic curve signatures for //transaction//.
|
||||
|
||||
_property: transaction.v => number
|
||||
The v portion of the elliptic curve signatures for //transaction//.
|
||||
This is used to refine which of the two possible points a given
|
||||
x-coordinate can have, and in [[link-eip-155]] is additionally
|
||||
used to encode the chain ID into the serialized transaction.
|
||||
|
||||
|
||||
_subsection: Functions @<transactions--functions>
|
||||
|
||||
_property: ethers.utils.accessListify(anAcceslistish) => [[providers-AccessList]] @<utils-accessListify> @SRC<transactions:accessListify>
|
||||
Normalizes the [[providers-AccessListish]] //anAccessListish// into
|
||||
an [[providers-AccessList]].
|
||||
|
||||
This is useful for other utility functions which wish to remain
|
||||
flexible as to the input parameter for access lists, such as
|
||||
when creating a [[Signer]] which needs to manipulate a possibly
|
||||
typed transaction envelope.
|
||||
|
||||
_property: ethers.utils.parseTransaction(aBytesLike) => [[Transaction]] @<utils-parseTransaction> @SRC<transactions:parse>
|
||||
Parses the transaction properties from a serialized transaction.
|
||||
|
||||
_property: ethers.utils.serializeTransaction(tx [ , signature ]) => string<[[DataHexString]]> @<utils-serializeTransaction> @SRC<transactions:serialize>
|
||||
Computes the serialized //transaction//, optionally serialized with
|
||||
the a //signature//. If //signature// is not present, the unsigned
|
||||
serialized transaction is returned, which can be used to compute the
|
||||
hash necessary to sign.
|
||||
|
||||
This function uses [[link-eip-155]] if a chainId is provided,
|
||||
otherwise legacy serialization is used. It is **highly** recommended
|
||||
to always specify a //chainId//.
|
||||
|
||||
If //signature// includes a chain ID (explicitly or implicitly by using an
|
||||
[[link-eip-155]] ``v`` or ``_vs``) it will be used to compute the
|
||||
chain ID.
|
||||
|
||||
If there is a mismatch between the chain ID of //transaction// and //signature//
|
||||
an error is thrown.
|
||||
69
docs.wrm/api/utils/web.wrm
Normal file
69
docs.wrm/api/utils/web.wrm
Normal file
@ -0,0 +1,69 @@
|
||||
_section: Web Utilities @<web>
|
||||
|
||||
|
||||
_property: ethers.utils.fetchJson(urlOrConnectionInfo [, json [ , processFunc ] ]) => Promise<any> @<utils-fetchJson>
|
||||
Fetch and parse the JSON content from //urlOrConnectionInfo//, with the
|
||||
optional body //json// and optionally processing the result with //processFun//
|
||||
before returning it.
|
||||
|
||||
_property: ethers.utils.poll(pollFunc [, options ]) => Promise<any> @<utils-poll>
|
||||
Repeatedly call pollFunc using the [[PollOptions]] until it returns a
|
||||
value other than undefined.
|
||||
|
||||
|
||||
_heading: ConnectionInfo @<ConnectionInfo>
|
||||
|
||||
_property: connection.url => string
|
||||
The URL to connect to.
|
||||
|
||||
_property: connection.user => string
|
||||
The username to use for [[link-wiki-basicauth]].
|
||||
The default is null (i.e. do not use basic authentication)
|
||||
|
||||
_property: connection.password => string
|
||||
The password to use for [[link-wiki-basicauth]].
|
||||
The default is null (i.e. do not use basic authentication)
|
||||
|
||||
_property: connection.allowInsecureAuthentication => boolean
|
||||
Allow [[link-wiki-basicauth]] over non-secure HTTP. The default is false.
|
||||
|
||||
_property: connection.timeout => number
|
||||
How long to wait before rejecting with a //timeout// error.
|
||||
|
||||
_property: connection.headers => { [ key: string]: string }
|
||||
Additional headers to include in the connection.
|
||||
|
||||
|
||||
_heading: PollOptions @<PollOptions>
|
||||
|
||||
_property: options.timeout => number
|
||||
The amount of time allowed to elapse before triggering a timeout
|
||||
error.
|
||||
|
||||
_property: options.floor => number
|
||||
The minimum time limit to allow for [[link-wiki-backoff]].
|
||||
|
||||
The default is 0s.
|
||||
|
||||
_property: options.ceiling => number
|
||||
The maximum time limit to allow for [[link-wiki-backoff]].
|
||||
|
||||
The default is 10s.
|
||||
|
||||
_property: options.interval => number
|
||||
The interval used during [[link-wiki-backoff]] calculation.
|
||||
|
||||
The default is 250ms.
|
||||
|
||||
_property: options.retryLimit => number
|
||||
The number of times to retry in the event of an error or //undefined// is
|
||||
returned.
|
||||
|
||||
_property: options.onceBlock => [[Provider]]
|
||||
If this is specified, the polling will wait on new blocks from
|
||||
//provider// before attempting the //pollFunc// again.
|
||||
|
||||
_property: options.oncePoll => [[Provider]]
|
||||
If this is specified, the polling will occur on each poll
|
||||
cycle of //provider// before attempting the //pollFunc//
|
||||
again.
|
||||
63
docs.wrm/api/utils/wordlists.wrm
Normal file
63
docs.wrm/api/utils/wordlists.wrm
Normal file
@ -0,0 +1,63 @@
|
||||
_section: Wordlists @<wordlists>
|
||||
|
||||
_subsection: Wordlist @<Wordlist>
|
||||
|
||||
_property: wordlist.locale => string
|
||||
The locale for this wordlist.
|
||||
|
||||
_property: wordlist.getWord(index) => string
|
||||
Returns the word at //index//.
|
||||
|
||||
_property: wordlist.getWordIndex(word) => number
|
||||
Returns the index of //word// within the wordlist.
|
||||
|
||||
_property: wordlist.split(mnemonic) => Array<string>
|
||||
Returns the mnemonic split into each individual word, according to a
|
||||
locale's valid whitespace character set.
|
||||
|
||||
_property: wordlist.join(words) => string
|
||||
Returns the mnemonic by joining //words// together using the
|
||||
whitespace that is standard for the locale.
|
||||
|
||||
_property: Wordlist.check(wordlists) => string<[[DataHexString]]<32>>
|
||||
Checks that all words map both directions correctly and return the
|
||||
hash of the lists. Sub-classes should use this to validate the wordlist
|
||||
is correct against the official wordlist hash.
|
||||
|
||||
_property: Wordlist.register(wordlist [ , name ]) => void
|
||||
Register a wordlist with the list of wordlists, optionally overriding
|
||||
the registered //name//.
|
||||
|
||||
_subsection: Languages @<wordlists--languages>
|
||||
|
||||
The [official wordlists](link-bip39-wordlists) available at
|
||||
`ethers.wordlists`. In the browser, only the english language is
|
||||
available by default; to include the others (which increases the
|
||||
size of the library), see the dist files in the `ethers` package.
|
||||
|
||||
_property: ethers.wordlists.cz => Wordlist
|
||||
The Czech [[Wordlist]].
|
||||
|
||||
_property: ethers.wordlists.en => Wordlist
|
||||
The English [[Wordlist]].
|
||||
|
||||
_property: ethers.wordlists.es => Wordlist
|
||||
The Spanish [[Wordlist]].
|
||||
|
||||
_property: ethers.wordlists.fr => Wordlist
|
||||
The French [[Wordlist]].
|
||||
|
||||
_property: ethers.wordlists.it => Wordlist
|
||||
The Italian [[Wordlist]].
|
||||
|
||||
_property: ethers.wordlists.ja => Wordlist
|
||||
The Japanese [[Wordlist]].
|
||||
|
||||
_property: ethers.wordlists.ko => Wordlist
|
||||
The Korean [[Wordlist]].
|
||||
|
||||
_property: ethers.wordlists.zh_cn => Wordlist
|
||||
The Simplified Chinese [[Wordlist]].
|
||||
|
||||
_property: ethers.wordlists.zh_tw => Wordlist
|
||||
The Traditional Chinese [[Wordlist]].
|
||||
@ -1,97 +0,0 @@
|
||||
_section: Application Binary Interfaces @<docs-abi>
|
||||
|
||||
When interacting with any application, whether it is on Ethereum,
|
||||
over the internet or within a compiled application on a computer
|
||||
all information is stored and sent as binary data which is just a
|
||||
sequence of bytes.
|
||||
|
||||
So every application must agree on how to encode and decode their
|
||||
information as a sequence of bytes.
|
||||
|
||||
An **Application Binary Interface** (ABI) provides a way to describe
|
||||
the encoding and decoding process, in a generic way so that a variety
|
||||
of types and structures of types can be defined.
|
||||
|
||||
For example, a string is often encoded as a UTF-8 sequence of bytes,
|
||||
which uses specific bits within sub-sequences to indicate emoji and
|
||||
other special characters. Every implementation of UTF-8 must understand
|
||||
and operate under the same rules so that strings work universally. In
|
||||
this way, UTF-8 standard is itself an ABI.
|
||||
|
||||
When interacting with Ethereum, a contract received a sequence of bytes
|
||||
as input (provided by sending a transaction or through a call) and
|
||||
returns a result as a sequence of bytes. So, each Contract has its own
|
||||
ABI that helps specify how to encode the input and how to decode the output.
|
||||
|
||||
It is up to the contract developer to make this ABI available. Many
|
||||
Contracts implement a standard (such as ERC-20), in which case the
|
||||
ABI for that standard can be used. Many developers choose to verify their
|
||||
source code on Etherscan, in which case Etherscan computes the ABI and
|
||||
provides it through their website (which can be fetched using the ``getContract``
|
||||
method). Otherwise, beyond reverse engineering the Contract there is
|
||||
not a meaningful way to extract the contract ABI.
|
||||
|
||||
_subsection: Call Data Representation
|
||||
|
||||
When calling a Contract on Ethereum, the input data must be encoded
|
||||
according to the ABI.
|
||||
|
||||
The first 4 bytes of the data are the **method selector**, which is
|
||||
the keccak256 hash of the normalized method signature.
|
||||
|
||||
Then the method parameters are encoded and concatenated to the selector.
|
||||
|
||||
All encoded data is made up of components padded to 32 bytes, so the length
|
||||
of input data will always be congruent to ``4 mod 32``.
|
||||
|
||||
The result of a successful call will be encoded values, whose components
|
||||
are padded to 32 bytes each as well, so the length of a result will always
|
||||
be congruent to ``0 mod 32``, on success.
|
||||
|
||||
The result of a reverted call will contain the **error selector** as the
|
||||
first 4 bytes, which is the keccak256 of the normalized error signature,
|
||||
followed by the encoded values, whose components are padded to 32 bytes
|
||||
each, so the length of a revert will be congruent to ``4 mod 32``.
|
||||
|
||||
The one exception to all this is that ``revert(false)`` will return a
|
||||
result or ``0x``.
|
||||
|
||||
|
||||
_subsection: Event Data Representation
|
||||
|
||||
When an Event is emitted from a contract, there are two places data is
|
||||
logged in a Log: the **topics** and the **data**.
|
||||
|
||||
An additonal fee is paid for each **topic**, but this affords a topic
|
||||
to be indexed in a bloom filter within the block, which allows efficient
|
||||
filtering.
|
||||
|
||||
The **topic hash** is always the first topic in a Log, which is the
|
||||
keccak256 of the normalized event signature. This allows a specific
|
||||
event to be efficiently filtered, finding the matching events in a block.
|
||||
|
||||
Each additional **indexed** parameter (i.e. parameters marked with
|
||||
``indexed`` in the signautre) are placed in the topics as well, but may be
|
||||
filtered to find matching values.
|
||||
|
||||
All non-indexed parameters are encoded and placed in the **data**. This
|
||||
is cheaper and more compact, but does not allow filtering on these values.
|
||||
|
||||
For example, the event ``Transfer(address indexed from, address indexed to, uint value)``
|
||||
would require 3 topics, which are the topic hash, the ``from`` address
|
||||
and the ``to`` address and the data would contain 32 bytes, which is
|
||||
the padded big-endian representation of ``value``. This allows for
|
||||
efficient filtering by the event (i.e. ``Transfer``) as well as the ``from``
|
||||
address and ``to`` address.
|
||||
|
||||
|
||||
_subsection: Deployment
|
||||
|
||||
When deploying a transaction, the data provided is treated as **initcode**,
|
||||
which executes the data as normal EVM bytecode, which returns a sequence
|
||||
of bytes, but instead of that sequence of bytes being treated as data that
|
||||
result is instead the bytecode to install as the bytecode of the contract.
|
||||
|
||||
The bytecode produced by Solidity is designed to have all constructor
|
||||
parameters encoded normally and concatenated to the bytecode and provided
|
||||
as the ``data`` to a transaction with no ``to`` address.
|
||||
@ -1,8 +0,0 @@
|
||||
_section: Ethereum Basics @<docs-basics> @priority<99>
|
||||
|
||||
This section aims to cover some of the basics for those interested
|
||||
in a deeper understanding of the inner-workings of Ethereum.
|
||||
|
||||
_subsection: Topics
|
||||
|
||||
- [Application Binary Interface](docs-abi)
|
||||
220
docs.wrm/cli/asm.wrm
Normal file
220
docs.wrm/cli/asm.wrm
Normal file
@ -0,0 +1,220 @@
|
||||
_section: Assembler @<cli-asm>
|
||||
|
||||
The assembler Command-Line utility allows you to assemble the
|
||||
[Ethers ASM Dialect](asm-dialect) into deployable EVM bytecode
|
||||
and disassemble EVM bytecode into human-readable mnemonics.
|
||||
|
||||
|
||||
_subsection: Help
|
||||
|
||||
_code: @lang<text>
|
||||
|
||||
Usage:
|
||||
ethers-asm [ FILENAME ] [ OPTIONS ]
|
||||
|
||||
OPTIONS
|
||||
--define KEY=VALUE provide assembler defines
|
||||
--disassemble Disassemble input bytecode
|
||||
--ignore-warnings Ignore warnings
|
||||
--pic generate position independent code
|
||||
--target LABEL output LABEL bytecode (default: _)
|
||||
|
||||
OTHER OPTIONS
|
||||
--debug Show stack traces for errors
|
||||
--help Show this usage and exit
|
||||
--version Show this version and exit
|
||||
|
||||
|
||||
_subsection: Example Input Files
|
||||
|
||||
_code: SimpleStore.asm @lang<asm>
|
||||
|
||||
; SimpleStore (uint)
|
||||
|
||||
; Set the initial value of 42
|
||||
sstore(0, 42)
|
||||
|
||||
; Init code to deploy myContract
|
||||
codecopy(0, $myContract, #myContract)
|
||||
return(0, #myContract)
|
||||
|
||||
@myContract {
|
||||
; Non-payable
|
||||
jumpi($error, callvalue)
|
||||
|
||||
; Get the Sighash
|
||||
shr({{= 256 - 32 }}, calldataload(0))
|
||||
|
||||
; getValue()
|
||||
dup1
|
||||
{{= sighash("getValue()") }}
|
||||
jumpi($getValue, eq)
|
||||
|
||||
; setValue(uint)
|
||||
dup1
|
||||
{{= sighash("setValue(uint)") }}
|
||||
jumpi($setValue, eq)
|
||||
|
||||
; No matching signature
|
||||
@error:
|
||||
revert(0, 0)
|
||||
|
||||
@getValue:
|
||||
mstore(0, sload(0))
|
||||
return (0, 32)
|
||||
|
||||
@setValue:
|
||||
; Make sure we have exactly a uint
|
||||
jumpi($error, iszero(eq(calldatasize, 36)))
|
||||
|
||||
; Store the value
|
||||
sstore(0, calldataload(4))
|
||||
return (0, 0)
|
||||
|
||||
; There is no *need* for the PUSH32, it just makes
|
||||
; decompiled code look nicer
|
||||
@checksum[
|
||||
{{= (defines.checksum ? concat([
|
||||
Opcode.from("PUSH32"),
|
||||
id(myContract.source)
|
||||
]): "0x")
|
||||
}}
|
||||
]
|
||||
}
|
||||
|
||||
|
||||
_code: SimpleStore.bin @lang<text>
|
||||
|
||||
0x602a6000556044601160003960446000f334601e5760003560e01c8063209652
|
||||
0x5514602457806355241077146030575b60006000fd5b60005460005260206000
|
||||
0xf35b6024361415601e5760043560005560006000f3
|
||||
|
||||
|
||||
_note: Note: Bytecode File Syntax
|
||||
A bin file may be made up of multiple blocks of bytecode, each may
|
||||
optionally begin with a ``0x`` prefix, all of which **must** be of
|
||||
even length (since bytes are required, with 2 nibbles per byte)
|
||||
|
||||
All whitespace is ignored.
|
||||
|
||||
_subsection: Assembler Examples
|
||||
|
||||
The assembler converts an [Ethers ASM Dialect](asm-dialect) into
|
||||
bytecode by running multiple passes of an assemble stage, each pass
|
||||
more closely approximating the final result.
|
||||
|
||||
This allows small portions of the bytecode to be massaged and tweaked
|
||||
until the bytecode stabilizes. This allows for more compact jump
|
||||
destinations and for code to include more advanced meta-programming
|
||||
techniques.
|
||||
|
||||
_code: @lang<shell>
|
||||
|
||||
/home/ethers> ethers-asm SimpleStore.asm
|
||||
0x602a6000556044601160003960446000f334601e5760003560e01c80632096525514602457806355241077146030575b60006000fd5b60005460005260206000f35b6024361415601e5760043560005560006000f3
|
||||
|
||||
# Piping in ASM source code
|
||||
/home/ethers> cat SimpleStore.asm | ethers-asm
|
||||
# Same as above
|
||||
|
||||
# Setting a define which the ASM file checks and adds a checksum
|
||||
/home/ethers> ethers-asm --define checksum SimpleStore.asm
|
||||
0x602a6000556065601160003960656000f334601e5760003560e01c80632096525514602457806355241077146030575b60006000fd5b60005460005260206000f35b6024361415601e5760043560005560006000f37f10358310d664c9aeb4bf4ce7a10a6a03176bd23194c8ccbd3160a6dac90774d6
|
||||
|
||||
|
||||
_heading: Options
|
||||
|
||||
_definition: **-\-define KEY=VALUE** //or// **-\-define FLAG**
|
||||
This allows key/value pairs (where the value is a string) and
|
||||
flags (which the value is ``true``) to be passed along to the
|
||||
assembler, which can be accessed in
|
||||
[Scripting Blocks](asm-dialect-scripting), such as ``{{= defined.someKey }}``.
|
||||
|
||||
_definition: **-\-ignore-warnings**
|
||||
By default any warning will be treated like an error. This enabled
|
||||
by-passing warnings.
|
||||
|
||||
_definition: **-\-pic**
|
||||
When a program is assembled, the labels are usually given as an
|
||||
absolute byte position, which can be jumped to for loops and
|
||||
control flow. This means that a program must be installed at a specific
|
||||
location.
|
||||
|
||||
Byt specifying the **Position Independent Code** flag, code
|
||||
will be generated in a way such that all offsets are relative, allowing
|
||||
the program to be moved without any impact to its logic.
|
||||
|
||||
This does incur an additional gas cost of 8 gas per offset access though.
|
||||
|
||||
_definition: **-\-target LABEL**
|
||||
All programs have a root scope named ``_`` which is by default
|
||||
assembled. This option allows another labelled target (either a
|
||||
[[asm-dialect-scope]] or a [[asm-dialect-datasegment]] to be
|
||||
assembled instead. The entire program is still assembled per usual,
|
||||
so this only impacts which part of the program is output.
|
||||
|
||||
_subsection: Disassembler Examples
|
||||
|
||||
A disassembled program shows offsets and mnemonics for the given
|
||||
bytecode. This format may change in the future to be more
|
||||
human-readable.
|
||||
|
||||
_code: @lang<shell>
|
||||
|
||||
/home/ethers> ethers-asm --disassemble SimpleStore.bin
|
||||
0000 : 0x2a ; #1
|
||||
0002 : 0x00 ; #1
|
||||
0004 : SSTORE
|
||||
0005 : 0x44 ; #1
|
||||
0007 : 0x11 ; #1
|
||||
0009 : 0x00 ; #1
|
||||
000b : CODECOPY
|
||||
000c : 0x44 ; #1
|
||||
000e : 0x00 ; #1
|
||||
0010 : RETURN
|
||||
0011 : CALLVALUE
|
||||
0012 : 0x1e ; #1
|
||||
0014 : JUMPI
|
||||
0015 : 0x00 ; #1
|
||||
0017 : CALLDATALOAD
|
||||
0018 : 0xe0 ; #1
|
||||
001a : SHR
|
||||
001b : DUP1
|
||||
001c : 0x20965255 ; #4
|
||||
0021 : EQ
|
||||
0022 : 0x24 ; #1
|
||||
0024 : JUMPI
|
||||
0025 : DUP1
|
||||
0026 : 0x55241077 ; #4
|
||||
002b : EQ
|
||||
002c : 0x30 ; #1
|
||||
002e : JUMPI
|
||||
002f*: JUMPDEST
|
||||
0030 : 0x00 ; #1
|
||||
0032 : 0x00 ; #1
|
||||
0034 : REVERT
|
||||
0035*: JUMPDEST
|
||||
0036 : 0x00 ; #1
|
||||
0038 : SLOAD
|
||||
0039 : 0x00 ; #1
|
||||
003b : MSTORE
|
||||
003c : 0x20 ; #1
|
||||
003e : 0x00 ; #1
|
||||
0040 : RETURN
|
||||
0041*: JUMPDEST
|
||||
0042 : 0x24 ; #1
|
||||
0044 : CALLDATASIZE
|
||||
0045 : EQ
|
||||
0046 : ISZERO
|
||||
0047 : 0x1e ; #1
|
||||
0049 : JUMPI
|
||||
004a : 0x04 ; #1
|
||||
004c : CALLDATALOAD
|
||||
004d : 0x00 ; #1
|
||||
004f : SSTORE
|
||||
0050 : 0x00 ; #1
|
||||
0052 : 0x00 ; #1
|
||||
0054 : RETURN
|
||||
|
||||
/home/ethers> cat SimpleStore.bin | ethers-asm --disassemble
|
||||
# Same as above
|
||||
82
docs.wrm/cli/ens.wrm
Normal file
82
docs.wrm/cli/ens.wrm
Normal file
@ -0,0 +1,82 @@
|
||||
_section: Ethereum Naming Service @NAV<ENS>
|
||||
|
||||
_subsection: Help
|
||||
|
||||
_code: @lang<text>
|
||||
|
||||
Usage:
|
||||
ethers-ens COMMAND [ ARGS ] [ OPTIONS ]
|
||||
|
||||
COMMANDS
|
||||
lookup [ NAME | ADDRESS [ ... ] ]
|
||||
Lookup a name or address
|
||||
commit NAME Submit a pre-commitment
|
||||
[ --duration DAYS ] Register duration (default: 365 days)
|
||||
[ --salt SALT ] SALT to blind the commit with
|
||||
[ --secret SECRET ] Use id(SECRET) as the salt
|
||||
[ --owner OWNER ] The target owner (default: current account)
|
||||
reveal NAME Reveal a previous pre-commitment
|
||||
[ --duration DAYS ] Register duration (default: 365 days)
|
||||
[ --salt SALT ] SALT to blind the commit with
|
||||
[ --secret SECRET ] Use id(SECRET) as the salt
|
||||
[ --owner OWNER ] The target owner (default: current account)
|
||||
set-controller NAME Set the controller (default: current account)
|
||||
[ --address ADDRESS ] Specify another address
|
||||
set-subnode NAME Set a subnode owner (default: current account)
|
||||
[ --address ADDRESS ] Specify another address
|
||||
set-resolver NAME Set the resolver (default: resolver.eth)
|
||||
[ --address ADDRESS ] Specify another address
|
||||
set-addr NAME Set the addr record (default: current account)
|
||||
[ --address ADDRESS ] Specify another address
|
||||
set-text NAME KEY VALUE Set a text record
|
||||
set-email NAME EMAIL Set the email text record
|
||||
set-website NAME URL Set the website text record
|
||||
set-content NAME HASH Set the IPFS Content Hash
|
||||
migrate-registrar NAME Migrate from the Legacy to the Permanent Registrar
|
||||
transfer NAME NEW_OWNER Transfer registrant ownership
|
||||
reclaim NAME Reset the controller by the registrant
|
||||
[ --address ADDRESS ] Specify another address
|
||||
|
||||
ACCOUNT OPTIONS
|
||||
--account FILENAME Load from a file (JSON, RAW or mnemonic)
|
||||
--account RAW_KEY Use a private key (insecure *)
|
||||
--account 'MNEMONIC' Use a mnemonic (insecure *)
|
||||
--account - Use secure entry for a raw key or mnemonic
|
||||
--account-void ADDRESS Use an address as a void signer
|
||||
--account-void ENS_NAME Add the resolved address as a void signer
|
||||
--account-rpc ADDRESS Add the address from a JSON-RPC provider
|
||||
--account-rpc INDEX Add the index from a JSON-RPC provider
|
||||
--mnemonic-password Prompt for a password for mnemonics
|
||||
--xxx-mnemonic-password Prompt for a (experimental) hard password
|
||||
|
||||
PROVIDER OPTIONS (default: all + homestead)
|
||||
--alchemy Include Alchemy
|
||||
--etherscan Include Etherscan
|
||||
--infura Include INFURA
|
||||
--nodesmith Include nodesmith
|
||||
--rpc URL Include a custom JSON-RPC
|
||||
--offline Dump signed transactions (no send)
|
||||
--network NETWORK Network to connect to (default: homestead)
|
||||
|
||||
TRANSACTION OPTIONS (default: query network)
|
||||
--gasPrice GWEI Default gas price for transactions(in wei)
|
||||
--gasLimit GAS Default gas limit for transactions
|
||||
--nonce NONCE Initial nonce for the first transaction
|
||||
--yes Always accept Signing and Sending
|
||||
|
||||
OTHER OPTIONS
|
||||
--wait Wait until transactions are mined
|
||||
--debug Show stack traces for errors
|
||||
--help Show this usage and exit
|
||||
--version Show this version and exit
|
||||
|
||||
(*) By including mnemonics or private keys on the command line they are
|
||||
possibly readable by other users on your system and may get stored in
|
||||
your bash history file. This is NOT recommended.
|
||||
|
||||
|
||||
_subsection: Examples
|
||||
|
||||
TODO examples
|
||||
|
||||
|
||||
254
docs.wrm/cli/ethers.wrm
Normal file
254
docs.wrm/cli/ethers.wrm
Normal file
@ -0,0 +1,254 @@
|
||||
_section: Sandbox Utility
|
||||
|
||||
The sandbox utility provides a simple way to use the most common
|
||||
ethers utilities required during learning, debugging 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: @lang<text>
|
||||
Usage:
|
||||
ethers [ COMMAND ] [ ARGS ] [ OPTIONS ]
|
||||
|
||||
COMMANDS (default: sandbox)
|
||||
sandbox Run a REPL VM environment with ethers
|
||||
init FILENAME Create a new JSON wallet
|
||||
[ --force ] Overwrite any existing files
|
||||
fund TARGET Fund TARGET with testnet ether
|
||||
info [ TARGET ... ] Dump info for accounts, addresses and ENS names
|
||||
send TARGET ETHER Send ETHER ether to TARGET form accounts[0]
|
||||
[ --allow-zero ] Allow sending to the address zero
|
||||
[ --data DATA ] Include data in the transaction
|
||||
sweep TARGET Send all ether from accounts[0] to TARGET
|
||||
sign-message MESSAGE Sign a MESSAGE with accounts[0]
|
||||
[ --hex ] The message content is hex encoded
|
||||
eval CODE Run CODE in a VM with ethers
|
||||
run FILENAME Run FILENAME in a VM with ethers
|
||||
wait HASH Wait for a transaction HASH to be mined
|
||||
wrap-ether VALUE Deposit VALUE into Wrapped Ether (WETH)
|
||||
unwrap-ether VALUE Withdraw VALUE from Wrapped Ether (WETH)
|
||||
send-token TOKEN ADDRESS VALUE
|
||||
Send VALUE tokens (at TOKEN) to ADDRESS
|
||||
compile FILENAME Compiles a Solidity contract
|
||||
[ --no-optimize ] Do not optimize the compiled output
|
||||
[ --warnings ] Error on any warning
|
||||
deploy FILENAME Compile and deploy a Solidity contract
|
||||
[ --no-optimize ] Do not optimize the compiled output
|
||||
[ --contract NAME ] Specify the contract to deploy
|
||||
|
||||
ACCOUNT OPTIONS
|
||||
--account FILENAME Load from a file (JSON, RAW or mnemonic)
|
||||
--account RAW_KEY Use a private key (insecure *)
|
||||
--account 'MNEMONIC' Use a mnemonic (insecure *)
|
||||
--account - Use secure entry for a raw key or mnemonic
|
||||
--account-void ADDRESS Use an address as a void signer
|
||||
--account-void ENS_NAME Add the resolved address as a void signer
|
||||
--account-rpc ADDRESS Add the address from a JSON-RPC provider
|
||||
--account-rpc INDEX Add the index from a JSON-RPC provider
|
||||
--mnemonic-password Prompt for a password for mnemonics
|
||||
--xxx-mnemonic-password Prompt for a (experimental) hard password
|
||||
|
||||
PROVIDER OPTIONS (default: all + homestead)
|
||||
--alchemy Include Alchemy
|
||||
--etherscan Include Etherscan
|
||||
--infura Include INFURA
|
||||
--nodesmith Include nodesmith
|
||||
--rpc URL Include a custom JSON-RPC
|
||||
--offline Dump signed transactions (no send)
|
||||
--network NETWORK Network to connect to (default: homestead)
|
||||
|
||||
TRANSACTION OPTIONS (default: query network)
|
||||
--gasPrice GWEI Default gas price for transactions(in wei)
|
||||
--gasLimit GAS Default gas limit for transactions
|
||||
--nonce NONCE Initial nonce for the first transaction
|
||||
--yes Always accept Signing and Sending
|
||||
|
||||
OTHER OPTIONS
|
||||
--wait Wait until transactions are mined
|
||||
--debug Show stack traces for errors
|
||||
--help Show this usage and exit
|
||||
--version Show this version and exit
|
||||
|
||||
(*) By including mnemonics or private keys on the command line they are
|
||||
possibly readable by other users on your system and may get stored in
|
||||
your bash history file. This is NOT recommended.
|
||||
|
||||
_subsection: Examples
|
||||
|
||||
_code: Creating New Wallets @lang<shell> @<cliex-init>
|
||||
|
||||
/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
|
||||
|
||||
|
||||
_code: Sending Ether and Tokens @<cliex-send> @lang<shell>
|
||||
|
||||
# Sending ether
|
||||
/home/ricmoo> ethers --account wallet.json send ricmoo.firefly.eth 0.123
|
||||
Password (wallet.json): ******
|
||||
Decrypting... 100%
|
||||
Transaction:
|
||||
To: 0x8ba1f109551bD432803012645Ac136ddd64DBA72
|
||||
From: 0xaB7C8803962c0f2F5BBBe3FA8bf41cd82AA1923C
|
||||
Value: 0.123 ether
|
||||
Nonce: 96
|
||||
Data: 0x
|
||||
Gas Limit: 21000
|
||||
Gas Price: 1.2 gwei
|
||||
Chain ID: 1
|
||||
Network: homestead
|
||||
Send Transaction? (y/N/a) y
|
||||
Response:
|
||||
Hash: 0xc4adf8b379033d7ab679d199aa35e6ceee9a802ca5ab0656af067e911c4a589a
|
||||
|
||||
|
||||
# Sending a token (SAI)
|
||||
# NOTE: the contract address could be used instead but
|
||||
# popular token contract addresses are also managed
|
||||
# by ethers
|
||||
/home/ricmoo> ethers --account wallet.json send-token sai.tokens.ethers.eth ricmoo.firefly.eth 1.0
|
||||
Sending Tokens:
|
||||
To: 0x8ba1f109551bD432803012645Ac136ddd64DBA72
|
||||
Token Contract: 0x89d24A6b4CcB1B6fAA2625fE562bDD9a23260359
|
||||
Value: 1.0
|
||||
Password (wallet.json): ******
|
||||
Decrypting... 100%
|
||||
Transaction:
|
||||
To: 0x89d24A6b4CcB1B6fAA2625fE562bDD9a23260359
|
||||
From: 0xaB7C8803962c0f2F5BBBe3FA8bf41cd82AA1923C
|
||||
Value: 0.0 ether
|
||||
Nonce: 95
|
||||
Data: 0xa9059cbb0000000000000000000000008ba1f109551bd432803012645ac136ddd64dba720000000000000000000000000000000000000000000000000de0b6b3a7640000
|
||||
Gas Limit: 37538
|
||||
Gas Price: 1.0 gwei
|
||||
Chain ID: 1
|
||||
Network: homestead
|
||||
Send Transaction? (y/N/a) y
|
||||
Response:
|
||||
Hash: 0xd609ecb7e3b5e8d36fd781dffceede3975ece6774b6322ea56cf1e4d0a17e3a1
|
||||
|
||||
|
||||
_code: Signing Messages @<cliex-signing> @lang<shell>
|
||||
|
||||
/home/ethers> ethers --account wallet.json sign-message 'Hello World'
|
||||
Password (wallet.json): ******
|
||||
Decrypting... 100%
|
||||
Message:
|
||||
Message: "Hello World"
|
||||
Message (hex): 0x48656c6c6f20576f726c64
|
||||
Sign Message? (y/N/a) y
|
||||
Signature
|
||||
Flat: 0xca3f0b32a22a5ab97ca8be7e4a36b1e81d565c6822465d769f4faa4aa24539fb122ee5649c8a37c9f5fc8446593674159e3a7b039997cd6ee697a24b787b1a161b
|
||||
r: 0xca3f0b32a22a5ab97ca8be7e4a36b1e81d565c6822465d769f4faa4aa24539fb
|
||||
s: 0x122ee5649c8a37c9f5fc8446593674159e3a7b039997cd6ee697a24b787b1a16
|
||||
vs: 0x122ee5649c8a37c9f5fc8446593674159e3a7b039997cd6ee697a24b787b1a16
|
||||
v: 27
|
||||
recid: 0
|
||||
|
||||
|
||||
_heading: Scripting @<cliex-scripting>
|
||||
|
||||
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: Get the formatted balance of an account @lang<shell>
|
||||
/home/ethers> ethers --network ropsten \
|
||||
--account wallet.json \
|
||||
eval \
|
||||
'accounts[0].getBalance().then(b => formatEther(b))'
|
||||
3.141592653589793238
|
||||
|
||||
_code: Get the current block number @lang<shell>
|
||||
/home/ethers> ethers --network rinkeby \
|
||||
eval "provider.getBlockNumber()"
|
||||
5761009
|
||||
|
||||
_code: Convert a Solidity signature to JSON @lang<shell>
|
||||
/home/ethers> ethers eval 'utils.Fragment.from(
|
||||
"function balanceOf(address) view returns (uint)"
|
||||
).format("json")' | json_pp
|
||||
{
|
||||
"inputs" : [
|
||||
{
|
||||
"type" : "address",
|
||||
"name" : "owner"
|
||||
}
|
||||
],
|
||||
"type" : "function",
|
||||
"payble" : false,
|
||||
"stateMutability" : "view",
|
||||
"ouputs" : [
|
||||
{
|
||||
"type" : "uint256"
|
||||
}
|
||||
],
|
||||
"name" : "balanceOf",
|
||||
"constant" : true
|
||||
}
|
||||
|
||||
|
||||
_code: Compute a topic hash @lang<shell>
|
||||
/home/ricmoo> ethers eval 'id("Transfer(address,address,uint256")'
|
||||
0xd99659a21de82e379975ce8df556f939a4ccb95e92144f38bb0dd35730ffcdd5
|
||||
|
||||
_code: Create a random mnemonic @lang<shell>
|
||||
/home/ricmoo> ethers eval 'Wallet.createRandom().mnemonic'
|
||||
useful pond inch knock ritual matrix giggle attend dilemma convince coach amazing
|
||||
|
||||
|
||||
_heading: Using Mnemonics (with a password) @<cliex-mnemonicpassword>
|
||||
|
||||
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: @lang<shell>
|
||||
|
||||
/home/ricmoo> ethers --account mnemonic.txt --mnemonic-password
|
||||
Password (mnemonic): ******
|
||||
network: homestead (chainId: 1)
|
||||
homestead> accounts[0].getAddress()
|
||||
<Promise id=0 resolved>
|
||||
'0x6d3F723EC1B73141AA4aC248c3ab34A5a1DAD776'
|
||||
homestead>
|
||||
|
||||
|
||||
_heading: Using Mnemonics (with experimental memory-hard passwords) @<cliex-mnemonicpassword-xxx>
|
||||
|
||||
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](link-wiki-scrypt)
|
||||
//password-based key derivation function// first, which is intentionally slow and makes
|
||||
a brute-force attack far more difficult.
|
||||
|
||||
_code: @lang<shell>
|
||||
|
||||
/home/ricmoo> ethers --account mnemonic.txt --xxx-mnemonic-password
|
||||
Password (mnemonic; experimental - hard): ******
|
||||
Decrypting... 100%
|
||||
network: homestead (chainId: 1)
|
||||
homestead> accounts[0].getAddress()
|
||||
<Promise id=0 resolved>
|
||||
'0x56FC8792cC17971C19bEC4Ced978beEA44711EeD'
|
||||
homestead>
|
||||
|
||||
_warning: Note
|
||||
This is still an experimental feature (hence the ``xxx``).
|
||||
|
||||
8
docs.wrm/cli/index.wrm
Normal file
8
docs.wrm/cli/index.wrm
Normal file
@ -0,0 +1,8 @@
|
||||
_section: Command Line Interfaces
|
||||
|
||||
_toc:
|
||||
ethers
|
||||
asm
|
||||
ens
|
||||
typescript
|
||||
plugin
|
||||
159
docs.wrm/cli/plugin.wrm
Normal file
159
docs.wrm/cli/plugin.wrm
Normal file
@ -0,0 +1,159 @@
|
||||
_section: Making Your Own @<cli-diy>
|
||||
|
||||
The //cli// library is meant to make it easy to create command
|
||||
line utilities of your own.
|
||||
|
||||
_subsection: CLI @<cli-cli> @SRC<cli:class.CLI>
|
||||
|
||||
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 @<cli-addplugin> @SRC<cli/cli>
|
||||
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 @<cli-setplugin> @SRC<cli/cli>
|
||||
Set a dedicated [[cli-plugin]] class which will handle all input. This
|
||||
may not be used in conjunction with addPlugin and will not automatically
|
||||
accept a command from the arguments.
|
||||
|
||||
_property: showUsage([ message = "" [ , status = 0 ] ]) => never @<cli-showusage> @SRC<cli/cli>
|
||||
Shows the usage help screen for the CLI and terminates.
|
||||
|
||||
_property: run(args) => Promise<void> @<cli-run> @SRC<cli/cli:CLI.run>
|
||||
Usually the value of //args// passed in will be ``process.argv.slice(2)``.
|
||||
|
||||
|
||||
_subsection: Plugin @<cli-plugin> @SRC<cli:class.Plugin>
|
||||
|
||||
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 generate 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 expected and throw
|
||||
an 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 => [[providers-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<void> @<plugin-prepareoptions> @SRC<cli/cli:Plugin.prepareOptions>
|
||||
|
||||
_property: plugin.prepareArgs(args) => Promise<void> @<plugin-prepareargs> @SRC<cli/cli>
|
||||
|
||||
_property: plugin.run() => Promise<void> @<plugin-run> @SRC<cli/cli:Plugin.run>
|
||||
|
||||
_property: plugin.getAddress(addressOrName [ , message = "", [ allowZero = false ] ]) => Promise<string> @<plugin-getaddress> @SRC<cli/cli:Plugin.getAddress>
|
||||
A plugin should use this method to resolve an address. If the resolved address is
|
||||
the zero address and //allowZero// is not true, an error is raised.
|
||||
|
||||
_property: plugin.dump(header, info) => void @<plugin-dump> @SRC<cli/cli:Plugin.dump>
|
||||
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 @<plugin-throwusageerror> @SRC<cli/cli>
|
||||
Stops execution of the plugin and shows the help screen of the plugin with
|
||||
the optional //message//.
|
||||
|
||||
_property: plugin.throwError(message) => never @<plugin-throwerror> @SRC<cli/cli>
|
||||
Stops execution of the plugin and shows //message//.
|
||||
|
||||
_heading: Static Methods
|
||||
|
||||
_property: Plugin.getHelp => Help @<plugin-gethelp> @SRC<cli/cli>
|
||||
Each subclass should implement this static method which is used to
|
||||
generate the help screen.
|
||||
|
||||
_property: Plugin.getOptionHelp => Array<Help> @<plugin-getoptionshelp> @SRC<cli/cli>
|
||||
Each subclass should implement this static method if it supports
|
||||
additional options which is used to generate the help screen.
|
||||
|
||||
|
||||
_subsection: ArgParser @<cli-argparser> @SRC<cli:class.ArgParser>
|
||||
|
||||
The **ArgParser** is used to parse a command line into flags, options
|
||||
and arguments.
|
||||
|
||||
_code: @lang<shell>
|
||||
|
||||
/home/ethers> ethers --account wallet.json --yes send ricmoo.eth 1.0
|
||||
# An Option ----------^ ^ ^
|
||||
# - name = "account" | |
|
||||
# - value = "wallet.json" | |
|
||||
# A Flag -----------------------------------+ |
|
||||
# - name = "yes" |
|
||||
# - value = true |
|
||||
# Arguments ------------------------------------+
|
||||
# - count = 3
|
||||
# - [ "send", "ricmoo.eth", "1.0" ]
|
||||
|
||||
_null:
|
||||
|
||||
Flags are simple binary options (such as the ``--yes``), which are true if present
|
||||
otherwise false.
|
||||
|
||||
Options require a single parameter follow them on the command line
|
||||
(such as ``--account wallet.json``, which has 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 @<argparser-consumeflag> @SRC<cli/cli>
|
||||
Remove the flag //name// and return true if it is present.
|
||||
|
||||
_property: argParser.consumeMultiOptions(names) => Array<{ name: string, value: string}> @<argparser-consumemultioptions> @SRC<cli/cli>
|
||||
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 @<argparser-consumeoption> @SRC<cli/cli>
|
||||
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<string> @<argparser-consumeoptions> @SRC<cli/cli>
|
||||
Remove all options with their values for //name// and return the list
|
||||
(in order) of values.
|
||||
28
docs.wrm/cli/typescript.wrm
Normal file
28
docs.wrm/cli/typescript.wrm
Normal file
@ -0,0 +1,28 @@
|
||||
_section: TypeScript
|
||||
|
||||
_subsection: Help
|
||||
|
||||
_code: @lang<text>
|
||||
|
||||
Usage:
|
||||
ethers-ts FILENAME [ ... ] [ OPTIONS ]
|
||||
|
||||
OPTIONS
|
||||
--output FILENAME Write the output to FILENAME (default: stdout)
|
||||
--force Overwrite files if they already exist
|
||||
--no-optimize Do not run the solc optimizer
|
||||
--no-bytecode Do not include bytecode and Factory methods
|
||||
|
||||
OTHER OPTIONS
|
||||
--debug Show stack traces for errors
|
||||
--help Show this usage and exit
|
||||
--version Show this version and exit
|
||||
|
||||
(*) By including mnemonics or private keys on the command line they are
|
||||
possibly readable by other users on your system and may get stored in
|
||||
your bash history file. This is NOT recommended.
|
||||
|
||||
|
||||
_subsection: Examples
|
||||
|
||||
TODO
|
||||
39
docs.wrm/concepts/best-practices.wrm
Normal file
39
docs.wrm/concepts/best-practices.wrm
Normal file
@ -0,0 +1,39 @@
|
||||
_section: Best Practices @<best-practices>
|
||||
|
||||
_subsection: Network Changes
|
||||
|
||||
Handling a change in the network (e.g. Ropsten vs Mainnet) is
|
||||
incredibly complex and a slight failure can at best make your
|
||||
application seem confusing and at worst cause the loss of funds,
|
||||
leak private data or misrepresent what an action performed.
|
||||
|
||||
Luckily, standard users should likely never change their networks
|
||||
unless tricked to do so or they make a mistake.
|
||||
|
||||
This is a problem you mainly need to worry about for developers, and
|
||||
most developers should understand the vast array of issues surrounding
|
||||
a network change during application operation and will understand the
|
||||
page reloading (which is already the default behaviour in many clients).
|
||||
|
||||
So, the best practice when a network change occurs is to simply
|
||||
refresh the page. This should cause all your UI components to
|
||||
reset to a known-safe state, including any banners and warnings
|
||||
to your users if they are on an unsupported network.
|
||||
|
||||
This can be accomplished by using the following function:
|
||||
|
||||
_code: Automatically Refresh on Network Change @lang<script>
|
||||
|
||||
// Force page refreshes on network changes
|
||||
{
|
||||
// The "any" network will allow spontaneous network changes
|
||||
const provider = new ethers.providers.Web3Provider(window.ethereum, "any");
|
||||
provider.on("network", (newNetwork, oldNetwork) => {
|
||||
// When a Provider makes its initial connection, it emits a "network"
|
||||
// event with a null oldNetwork along with the newNetwork. So, if the
|
||||
// oldNetwork exists, it represents a changing network
|
||||
if (oldNetwork) {
|
||||
window.location.reload();
|
||||
}
|
||||
});
|
||||
}
|
||||
213
docs.wrm/concepts/events.wrm
Normal file
213
docs.wrm/concepts/events.wrm
Normal file
@ -0,0 +1,213 @@
|
||||
_section: Events @<events>
|
||||
|
||||
_subsection: Logs and Filtering
|
||||
|
||||
Logs and filtering are used quite often in blockchain applications,
|
||||
since they allow for efficient queries of indexed data and provide
|
||||
lower-cost data storage when the data is not required to be
|
||||
accessed on-chain.
|
||||
|
||||
These can be used in conjunction with the [Provider Events API](Provider--event-methods)
|
||||
and with the [Contract Events API](Contract--events).
|
||||
|
||||
The Contract Events API also provides [higher-level methods](Contract--filters)
|
||||
to compute and query this data, which should be preferred over the lower-level filter.
|
||||
|
||||
_heading: Filters @<events--filters>
|
||||
|
||||
When a Contract creates a log, it can include up to 4 pieces of
|
||||
data to be indexed by. The indexed data is hashed and included in
|
||||
a [[link-wiki-bloomfilter]], which is a data structure that allows
|
||||
for efficient filtering.
|
||||
|
||||
So, a filter may correspondingly have up to 4 topic-sets, where each
|
||||
topic-set refers to a condition that must match the indexed log topic
|
||||
in that position (i.e. each condition is ``AND``-ed together).
|
||||
|
||||
If a topic-set is ``null``, a log topic in that position is **not filtered**
|
||||
at all and **any value** matches.
|
||||
|
||||
If a topic-set is a single topic, a log topic in that position **must** match
|
||||
**that topic**.
|
||||
|
||||
If a topic-set is an array of topics, a log topic in that position must
|
||||
match **any one** of the topics (i.e. the topic in this position are ``OR``-ed).
|
||||
|
||||
This may sound complicated at first, but is more easily understood with
|
||||
some examples.
|
||||
|
||||
_table: Example Log Matching @style<full>
|
||||
|
||||
$TopicABaCD: **[** (topic[0] = A) **OR** (topic[0] = B) **]** **AND**
|
||||
**[** (topic[1] = C) **OR** (topic[1] = D) **]**
|
||||
|
||||
| **Topic-Sets** | **Matching Logs** <<|
|
||||
| [ A ] | topic[0] = A <<|
|
||||
| [ A, null ] | ^ |
|
||||
| [ null, B ] | topic[1] = B <<|
|
||||
| [ null, [ B ] ] | ^ |
|
||||
| [ null, [ B ], null ] | ^ |
|
||||
| [ A, B ] | (topic[0] = A) **AND** (topic[1] = B) <<|
|
||||
| [ A, [ B ] ] | ^ |
|
||||
| [ A, [ B ], null ] | ^ |
|
||||
| [ [ A, B ] ] | (topic[0] = A) **OR** (topic[0] = B) <<|
|
||||
| [ [ A, B ], null ] | ^ |
|
||||
| [ [ A, B ], [ C, D ] ] | $TopicABaCD <<|
|
||||
|
||||
|
||||
_code: ERC-20 Transfer Filter Examples @lang<javascript>
|
||||
|
||||
//_hide: const tokenAddress = ethers.constants.AddressZero;
|
||||
//_hide: const myAddress = ethers.constants.AddressZero;
|
||||
//_hide: const myOtherAddress = ethers.constants.AddressZero;
|
||||
//_hide: const id = ethers.utils.id;
|
||||
//_hide: const hexZeroPad = ethers.utils.hexZeroPad;
|
||||
|
||||
// Short example of manually creating filters for an ERC-20
|
||||
// Transfer event.
|
||||
//
|
||||
// Most users should generally use the Contract API to
|
||||
// compute filters, as it is much simpler, but this is
|
||||
// provided as an illustration for those curious. See
|
||||
// below for examples of the equivalent Contract API.
|
||||
|
||||
// ERC-20:
|
||||
// Transfer(address indexed src, address indexed dst, uint val)
|
||||
//
|
||||
// -------------------^
|
||||
// ----------------------------------------^
|
||||
//
|
||||
// Notice that only *src* and *dst* are *indexed*, so ONLY they
|
||||
// qualify for filtering.
|
||||
//
|
||||
// Also, note that in Solidity an Event uses the first topic to
|
||||
// identify the Event name; for Transfer this will be:
|
||||
// id("Transfer(address,address,uint256)")
|
||||
//
|
||||
// Other Notes:
|
||||
// - A topic must be 32 bytes; so shorter types must be padded
|
||||
|
||||
// List all token transfers *from* myAddress
|
||||
filter = {
|
||||
address: tokenAddress,
|
||||
topics: [
|
||||
id("Transfer(address,address,uint256)"),
|
||||
hexZeroPad(myAddress, 32)
|
||||
]
|
||||
};
|
||||
|
||||
// List all token transfers *to* myAddress:
|
||||
filter = {
|
||||
address: tokenAddress,
|
||||
topics: [
|
||||
id("Transfer(address,address,uint256)"),
|
||||
null,
|
||||
hexZeroPad(myAddress, 32)
|
||||
]
|
||||
};
|
||||
|
||||
// List all token transfers *to* myAddress or myOtherAddress:
|
||||
filter = {
|
||||
address: tokenAddress,
|
||||
topics: [
|
||||
id("Transfer(address,address,uint256)"),
|
||||
null,
|
||||
[
|
||||
hexZeroPad(myAddress, 32),
|
||||
hexZeroPad(myOtherAddress, 32),
|
||||
]
|
||||
]
|
||||
};
|
||||
|
||||
_null:
|
||||
|
||||
To simplify life, ..., explain here, the contract API
|
||||
|
||||
|
||||
_code: ERC-20 Contract Filter Examples @lang<javascript>
|
||||
|
||||
//_hide: const tokenAddress = "0x6B175474E89094C44Da98b954EedeAC495271d0F"; /* DAI */
|
||||
//_hide: const myAddress = "0x8ba1f109551bD432803012645Ac136ddd64DBA72";
|
||||
//_hide: const otherAddress = "0xEA517D5a070e6705Cc5467858681Ed953d285Eb9";
|
||||
//_hide: const provider = ethers.getDefaultProvider();
|
||||
//_hide: const Contract = ethers.Contract;
|
||||
|
||||
abi = [
|
||||
"event Transfer(address indexed src, address indexed dst, uint val)"
|
||||
];
|
||||
|
||||
contract = new Contract(tokenAddress, abi, provider);
|
||||
|
||||
// List all token transfers *from* myAddress
|
||||
//_result:
|
||||
contract.filters.Transfer(myAddress)
|
||||
//_log:
|
||||
|
||||
// List all token transfers *to* myAddress:
|
||||
//_result:
|
||||
contract.filters.Transfer(null, myAddress)
|
||||
//_log:
|
||||
|
||||
// List all token transfers *from* myAddress *to* otherAddress:
|
||||
//_result:
|
||||
contract.filters.Transfer(myAddress, otherAddress)
|
||||
//_log:
|
||||
|
||||
// List all token transfers *to* myAddress OR otherAddress:
|
||||
//_result:
|
||||
contract.filters.Transfer(null, [ myAddress, otherAddress ])
|
||||
//_log:
|
||||
|
||||
|
||||
_subsection: Solidity Topics @<events-solidity>
|
||||
|
||||
This is a quick (and non-comprehensive) overview of how events are computed
|
||||
in Solidity.
|
||||
|
||||
This is likely out of the scope for most developers, but may be interesting
|
||||
to those who want to learn a bit more about the underlying technology.
|
||||
|
||||
Solidity provides two types of events, anonymous and non-anonymous. The
|
||||
default is non-anonymous, and most developers will not need to worry about
|
||||
anonymous events.
|
||||
|
||||
For non-anonymous events, up to 3 topics may be indexed (instead of 4), since
|
||||
the first topic is reserved to specify the event signature. This allows
|
||||
non-anonymous events to always be filtered by their event signature.
|
||||
|
||||
This topic hash is always in the first slot of the indexed data, and is
|
||||
computed by normalizing the Event signature and taking the keccak256 hash
|
||||
of it.
|
||||
|
||||
For anonymous events, up to 4 topics may be indexed, and there is no
|
||||
signature topic hash, so the events cannot be filtered by the event
|
||||
signature.
|
||||
|
||||
Each additional indexed property is processed depending on whether its
|
||||
length is fixed or dynamic.
|
||||
|
||||
For fixed length types (e.g. ``uint``, ``bytes5``), all of which are
|
||||
internally exactly 32 bytes (shorter types are padded with zeros;
|
||||
numeric values are padded on the left, data values padded on the right),
|
||||
these are included directly by their actual value, 32 bytes of data.
|
||||
|
||||
For dynamic types (e.g. ``string``, ``uint256[]``) , the value is hashed
|
||||
using keccak256 and this hash is used.
|
||||
|
||||
Because dynamic types are hashed, there are important consequences in
|
||||
parsing events that should be kept in mind. Mainly that the original
|
||||
value is lost in the event. So, it is possible to tell is a topic is
|
||||
equal to a given string, but if they do not match, there is no way
|
||||
to determine what the value was.
|
||||
|
||||
If a developer requires that a string value is required to be both
|
||||
able to be filtered and also able to be read, the value must be included
|
||||
in the signature twice, once indexed and once non-indexed (e.g.
|
||||
``someEvent(string indexed searchBy, string clearText)``).
|
||||
|
||||
For a more detailed description, please refer to the
|
||||
[Solidity Event Documentation](link-solidity-events).
|
||||
|
||||
_heading: Other Things? TODO
|
||||
|
||||
Explain what happens to strings and bytes, how to filter and retain the value
|
||||
12
docs.wrm/concepts/gas.wrm
Normal file
12
docs.wrm/concepts/gas.wrm
Normal file
@ -0,0 +1,12 @@
|
||||
_section: Gas @<gas>
|
||||
|
||||
Explain attack vectors
|
||||
|
||||
_subsection: Gas Price @<gas-price>
|
||||
|
||||
The gas price is used somewhat like a bid, indicating an amount
|
||||
you are willing to pay (per unit of execution) to have your transaction
|
||||
processed.
|
||||
|
||||
_subsection: Gas Limit @<gas-limit>
|
||||
|
||||
14
docs.wrm/concepts/index.wrm
Normal file
14
docs.wrm/concepts/index.wrm
Normal file
@ -0,0 +1,14 @@
|
||||
_section: Ethereum Basics
|
||||
|
||||
This is a brief overview of some aspects of //Ethereum//
|
||||
and blockchains which developers can make use of or should
|
||||
be aware of.
|
||||
|
||||
This section is sparse at the moment, but will be expanded
|
||||
as time goes on.
|
||||
|
||||
_toc:
|
||||
events
|
||||
gas
|
||||
security
|
||||
best-practices
|
||||
162
docs.wrm/concepts/security/index.wrm
Normal file
162
docs.wrm/concepts/security/index.wrm
Normal file
@ -0,0 +1,162 @@
|
||||
_section: Security @<security>
|
||||
|
||||
While security should be a concern for all developers, in the
|
||||
blockchain space developers must be additionally conscious of
|
||||
many areas which can be exploited.
|
||||
|
||||
Once a problem has an economic incentives to exploit it, there
|
||||
is a much larger risk and with blockchain apps it can become
|
||||
quite valuable to attack.
|
||||
|
||||
In addition to many of the other security issues app developers
|
||||
may have to worry about, there are a few additional vectors
|
||||
that JavaScript developers should be aware of.
|
||||
|
||||
_subsection: Side-Channel Attacks
|
||||
|
||||
A [Side-Channel Attack](link-wiki-side-channel-attack) occurs
|
||||
when something orthogonal to the implementation of the algorithm
|
||||
used can be exploited to learn more about secure or private
|
||||
information.
|
||||
|
||||
_heading: Released Data (Strings, Uint8Arrays, Buffers)
|
||||
|
||||
In JavaScript, memory may not be securely allocated, or more
|
||||
importantly securely released.
|
||||
|
||||
[Historically](https://github.com/nodejs/node/issues/4660),
|
||||
``new Buffer(16)`` would re-use old memory that had been
|
||||
released. This would mean that code runnint later, may have
|
||||
access to data that was discarded.
|
||||
|
||||
As an example of the dangers, imagine if you had used a Buffer
|
||||
to store a private key, signed data and then returned from the
|
||||
function, allowing the Buffer to be de-allocated. A future
|
||||
function may be able to request a new Buffer, which would still
|
||||
have that left-over private key, which it could then use to
|
||||
steal the funds from that account.
|
||||
|
||||
There are also many debugging tools and systems designed to
|
||||
assist develoeprs inspect the memory contents of JavaScript
|
||||
programs. In these cases, any //private key// or //mnemonic//
|
||||
siiting in memory may be visible to other users on the system,
|
||||
or malicious scripts.
|
||||
|
||||
_heading: Timing Attack
|
||||
|
||||
Timing attacks allow a malicious user or script to determine
|
||||
private data through analysing how long an operation requires
|
||||
to execute.
|
||||
|
||||
In JavaScript, //Garbage Collection// occurs periodically when the
|
||||
system determines it is required. Each JavaScript implementation
|
||||
is different, with a variety of strategies and and abilities.
|
||||
|
||||
Most Garbage Collection requires "stopping the world", or pausing
|
||||
all code being executed while it runs. This adds a large delay
|
||||
to any code that was currently running.
|
||||
|
||||
This can be exploited by attackers to "condition cause a delay".
|
||||
They will set up a scenario where the system is on the edge of
|
||||
needing to garbage collect, and call your code with two paths,
|
||||
a simple path and complex path. The simple path won't stir things
|
||||
up enough to cause a garbage collection, while the complex one
|
||||
will. By timing how long the code took to execute, they now know
|
||||
whether garbage collection occured and therefore whether the simple
|
||||
or complex path was taken.
|
||||
|
||||
Advancced timing attacks are very difficult to mitigate in any
|
||||
garbage-collection-based language. Most libraries where this
|
||||
matters will hopefully mitigated this for you as much as possible,
|
||||
but it is still good to be aware of.
|
||||
|
||||
_heading: General Concerns
|
||||
|
||||
- [Cross-Site Scripting](link-wiki-xss)
|
||||
- [Cross-Site Request Forgery](link-wiki-csrf)
|
||||
- [Phishing](link-wiki-phishing)
|
||||
|
||||
|
||||
_subsection: Key Derivation Functions @<security--pbkdf>
|
||||
|
||||
This is not specific to Ethereum, but is a useful technique
|
||||
to understand and has some implications on User Experience.
|
||||
|
||||
Many people are concerned that encrypting and decrypting an
|
||||
Ethereum wallet is quite slow and can take quite some time.
|
||||
It is important to understand this is intentional and provides
|
||||
much stronger security.
|
||||
|
||||
The algorithm usually used for this process is [scrypt](link-wiki-scrypt),
|
||||
which is a memory and CPU intensive algorithm which computes
|
||||
a key (fixed-length pseudo-random series of bytes) for a given
|
||||
password.
|
||||
|
||||
|
||||
_heading: Why does it take so long?
|
||||
|
||||
The goal is to use as much CPU and memory as possible during
|
||||
this algorithm, so that a single computer can only compute a
|
||||
very small number of results for some fixed amount of time. To
|
||||
scale up an attack, the attacker requires additional computers,
|
||||
increasing the cost to [brute-force attack](link-wiki-bruteforce)
|
||||
to guess the password.
|
||||
|
||||
For example, if a user knows their correct password, this process
|
||||
may take 10 seconds for them to unlock their own wallet and proceed.
|
||||
|
||||
But since an attacker does not know the password, they must guess; and
|
||||
each guess also requires 10 seconds. So, if they wish to try guessing 1
|
||||
million passwords, their computer would be completely tied up for 10
|
||||
million seconds, or around 115 days.
|
||||
|
||||
Without using an algorithm like this, a user would be able
|
||||
to log in instantly, however, 1 million passwords would only
|
||||
take a few seconds to attempt. Even secure passwords would
|
||||
likely be broken within a short period of time. There is no way
|
||||
the algorithm can be faster for a legitimate user without also
|
||||
being faster for an attacker.
|
||||
|
||||
_heading: Mitigating the User Experience
|
||||
|
||||
Rather than reducing the security (see below), a better practice is to make
|
||||
the user feel better about waiting. The Ethers encryption and decryption
|
||||
API allows the developer to incorporate a progress bar, by passing in a
|
||||
progress callback which will be periodically called with a number between
|
||||
0 and 1 indication percent completion.
|
||||
|
||||
In general a progress bar makes the experience feel faster, as well as
|
||||
more comfortable since there is a clear indication how much (relative) time
|
||||
is remaining. Additionally, using language like //"decrypting..."// in
|
||||
a progress bar makes a user feel like there time is not being //needlessly//
|
||||
wasted.
|
||||
|
||||
_heading: Work-Arounds (not recommended)
|
||||
|
||||
There are ways to reduce the time required to decrypt an Ethereum JSON
|
||||
Wallet, but please keep in mind that doing so **discards nearly all security**
|
||||
on that wallet.
|
||||
|
||||
The scrypt algorithm is designed to be tuned. The main purpose of this is
|
||||
to increase the difficulty as time goes on and computers get faster, but
|
||||
it can also be tuned down in situations where the security is less important.
|
||||
|
||||
_code: @LANG<javascript>
|
||||
|
||||
// Our wallet object
|
||||
const wallet = Wallet.createRandom();
|
||||
|
||||
// The password to encrypt with
|
||||
const password = "password123";
|
||||
|
||||
// WARNING: Doing this substantially reduces the security
|
||||
// of the wallet. This is highly NOT recommended.
|
||||
|
||||
// We override the default scrypt.N value, which is used
|
||||
// to indicate the difficulty to crack this wallet.
|
||||
const json = wallet.encrypt(password, {
|
||||
scrypt: {
|
||||
// The number must be a power of 2 (default: 131072)
|
||||
N: 64
|
||||
}
|
||||
});
|
||||
348
docs.wrm/config.js
Normal file
348
docs.wrm/config.js
Normal file
@ -0,0 +1,348 @@
|
||||
"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);
|
||||
}
|
||||
} else if (ts.isGetAccessorDeclaration(node)) {
|
||||
add("getter", (lastClass + "." + node.name.text), 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/master/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, name: d.name });
|
||||
});
|
||||
});
|
||||
if (result.length > 1) {
|
||||
throw new Error(`Ambiguous TypeScript link: ${ key } in [ ${ result.map((r) => JSON.stringify(r.filename + ":" + r.lineNo + "@" + r.name)).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.*"));
|
||||
|
||||
function codeContextify(context) {
|
||||
const { inspect } = require("util");
|
||||
const ethers = context.require("./packages/ethers");
|
||||
|
||||
context.ethers = ethers;
|
||||
context.BigNumber = ethers.BigNumber;
|
||||
context.constants = ethers.constants;
|
||||
context.utils = ethers.utils;
|
||||
context.arrayify = ethers.utils.arrayify;
|
||||
context.hexlify = ethers.utils.hexlify;
|
||||
context.hexValue = ethers.utils.hexValue;
|
||||
context.Wallet = ethers.Wallet;
|
||||
context.provider = new ethers.providers.InfuraProvider("mainnet", "49a0efa3aaee4fd99797bfa94d8ce2f1");
|
||||
|
||||
// We use a local dev node for some signing examples, but want to
|
||||
// resolve ENS names against mainnet; super hacky but makes the
|
||||
// docs nicer
|
||||
context.localProvider = new ethers.providers.JsonRpcProvider();
|
||||
context.localSigner = context.localProvider.getSigner();
|
||||
context.localProvider.resolveName = context.provider.resolveName.bind(context.provider);
|
||||
|
||||
context.BigNumber.prototype[inspect.custom] = function(depth, options) {
|
||||
return `{ BigNumber: ${JSON.stringify(this.toString()) } }`;
|
||||
}
|
||||
|
||||
context.createClass = function(name) {
|
||||
let C = class{ }
|
||||
Object.defineProperty(C, "name", { value: name })
|
||||
return C;
|
||||
}
|
||||
|
||||
|
||||
context._inspect = function(value, depth) {
|
||||
if (toString.call(value) === '[object Error]') {
|
||||
// Not an error from ethers...
|
||||
if (ethers.utils.Logger.errors[value.code] == null) {
|
||||
return `Error: ${ value.message }`;
|
||||
}
|
||||
|
||||
// Trim the ethers errors down on their verbosity for the docs...
|
||||
if (value.message) {
|
||||
value.message = value.message.split(" (")[0];
|
||||
}
|
||||
value.stack = undefined;
|
||||
}
|
||||
|
||||
if (value && value.constructor && value.constructor.name === "Uint8Array") {
|
||||
return `Uint8Array [ ${ Array.prototype.join.call(value, ", ") } ]`;
|
||||
}
|
||||
|
||||
if (typeof(value) === "string" && value.indexOf("\n") >= 0) {
|
||||
return "`" + value + "`";
|
||||
}
|
||||
|
||||
//return JSON.stringify(value);
|
||||
return inspect(value, {
|
||||
compact: false,
|
||||
depth: null,
|
||||
breakLength: Infinity,
|
||||
sorted: true,
|
||||
});
|
||||
}
|
||||
|
||||
context._startup = function() {
|
||||
console.log("Startup");
|
||||
}
|
||||
|
||||
context._shutdown = function() {
|
||||
console.log("Shutdown");
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
module.exports = {
|
||||
title: "ethers",
|
||||
subtitle: "v5.3",
|
||||
description: "Documentation for ethers, a complete, tiny and simple Ethereum library.",
|
||||
logo: "logo.svg",
|
||||
|
||||
socialImage: "social.jpg",
|
||||
|
||||
prefix: "/v5",
|
||||
|
||||
link: "https:/\/docs.ethers.io",
|
||||
copyright: "The content of this site is licensed under the [Creative Commons License](https:/\/choosealicense.com/licenses/cc-by-4.0/). Generated on &$now;.",
|
||||
|
||||
markdown: {
|
||||
"banner": "-----\n\nDocumentation: [html](https://docs.ethers.io/)\n\n-----\n\n"
|
||||
},
|
||||
|
||||
codeContextify: codeContextify,
|
||||
|
||||
getSourceUrl: getSourceUrl,
|
||||
|
||||
codeRoot: "../",
|
||||
|
||||
externalLinks: {
|
||||
"link-mail": "mailto:me@ricmoo.com",
|
||||
"link-alchemy": { name: "Alchemy", url: "https:/\/alchemyapi.io" },
|
||||
"link-cloudflare": { name: "Cloudflare", url: "https:/\/developers.cloudflare.com/distributed-web/ethereum-gateway/" },
|
||||
"link-ens": { name: "ENS", url: "https:/\/ens.domains/" },
|
||||
"link-ethereum": { name: "Ethereum", url: "https:/\/ethereumorg" },
|
||||
"link-etherscan": { name: "Etherscan", url: "https:/\/etherscan.io" },
|
||||
"link-expo": { name: "Expo", url: "https:/\/expo.io" },
|
||||
"link-etherscan-api": "https:/\/etherscan.io/apis",
|
||||
"link-flatworm": { name: "Flatworm", url: "https:/\/github.com/ricmoo/flatworm" },
|
||||
"link-geth": { name: "Geth", url: "https:/\/geth.ethereum.org" },
|
||||
"link-infura": { name: "INFURA", url: "https:/\/infura.io" },
|
||||
"link-javascriptcore": { name: "JavaScriptCore", url: "https:/\/developer.apple.com/documentation/javascriptcore?language=objc" },
|
||||
"link-ledger": "https:/\/www.ledger.com",
|
||||
"link-metamask": { name: "Metamask", url: "https:/\/metamask.io/" },
|
||||
"link-otto": "https:/\/github.com/robertkrimen/otto",
|
||||
"link-parity": { name: "Parity", url: "https:/\/www.parity.io" },
|
||||
"link-pocket": { name: "Pocket Network", url: "https:/\/pokt.network" },
|
||||
"link-react-native": { name: "React Native", url: "https:/\/reactnative.dev" },
|
||||
"link-rtd": "https:/\/github.com/readthedocs/sphinx_rtd_theme",
|
||||
"link-semver": { name: "semver", url: "https:/\/semver.org" },
|
||||
"link-solidity": { name: "Solidity" , url: "https:/\/solidity.readthedocs.io/" },
|
||||
"link-solidity-errors": "https:/\/docs.soliditylang.org/en/v0.8.4/abi-spec.html#errors",
|
||||
"link-solidity-events": "https:/\/docs.soliditylang.org/en/v0.8.4/abi-spec.html#events",
|
||||
"link-sphinx": { name: "Sphinx", url: "https:/\/www.sphinx-doc.org/" },
|
||||
|
||||
"link-alchemy-signup": "https:/\/dashboard.alchemyapi.io/signup?referral=55a35117-028e-4b7c-9e47-e275ad0acc6d",
|
||||
"link-etherscan-signup": "https:/\/etherscan.io/apis",
|
||||
"link-etherscan-ratelimit": "https:/\/info.etherscan.com/api-return-errors/",
|
||||
"link-infura-signup": "https:/\/infura.io/register",
|
||||
"link-pocket-signup": "https:/\/pokt.network/pocket-gateway-ethereum-mainnet/",
|
||||
|
||||
"link-json-rpc": "https:/\/github.com/ethereum/wiki/wiki/JSON-RPC",
|
||||
"link-web3-send": "https:/\/github.com/ethereum/web3.js/blob/1.x/packages/web3-providers-http/types/index.d.ts#L57",
|
||||
"link-parity-trace": "https:/\/openethereum.github.io/wiki/JSONRPC-trace-module",
|
||||
"link-parity-rpc": "https:/\/openethereum.github.io/wiki/JSONRPC",
|
||||
"link-geth-debug": "https:/\/github.com/ethereum/go-ethereum/wiki/Management-APIs#debug",
|
||||
"link-geth-rpc": "https:/\/github.com/ethereum/go-ethereum/wiki/Management-APIs",
|
||||
|
||||
"link-legacy-docs3": "https:/\/docs.ethers.io/v3/",
|
||||
"link-legacy-docs4": "https:/\/docs.ethers.io/v4/",
|
||||
|
||||
"link-github-ci": "https:/\/github.com/ethers-io/ethers.js/actions/runs/158006903",
|
||||
"link-github-issues": "https:/\/github.com/ethers-io/ethers.js/issues",
|
||||
|
||||
"link-issue-407": "https:/\/github.com/ethers-io/ethers.js/issues/407",
|
||||
|
||||
"link-infura-secret": "https:/\/infura.io/docs/gettingStarted/authentication",
|
||||
|
||||
"link-web3": "https:/\/github.com/ethereum/web3.js",
|
||||
"link-web3-http": "https:/\/github.com/ethereum/web3.js/tree/1.x/packages/web3-providers-http",
|
||||
"link-web3-ipc": "https:/\/github.com/ethereum/web3.js/tree/1.x/packages/web3-providers-ipc",
|
||||
"link-web3-ws": "https:/\/github.com/ethereum/web3.js/tree/1.x/packages/web3-providers-ws",
|
||||
|
||||
"link-solc-output": "https:/\/solidity.readthedocs.io/en/v0.6.0/using-the-compiler.html#output-description",
|
||||
"link-bip39-wordlists": "https:/\/github.com/bitcoin/bips/blob/master/bip-0039/bip-0039-wordlists.md",
|
||||
|
||||
"link-icap": "https:/\/github.com/ethereum/wiki/wiki/Inter-exchange-Client-Address-Protocol-%28ICAP%29",
|
||||
"link-jsonrpc": "https:/\/github.com/ethereum/wiki/wiki/JSON-RPC",
|
||||
"link-mit": { name: "MIT License", url: "https:/\/en.m.wikipedia.org/wiki/MIT_License" },
|
||||
"link-namehash": { name: "namehash", url: "https:/\/docs.ens.domains/contract-api-reference/name-processing#hashing-names" },
|
||||
"link-rlp": { name: "Recursive Length Prefix", url: "https:/\/github.com/ethereum/wiki/wiki/RLP" },
|
||||
|
||||
"link-ethersio": "https:/\/ethers.io/",
|
||||
"link-ethers-docs": "https:/\/docs.ethers.io/",
|
||||
"link-ethers-js": "https:/\/cdn.ethers.io/lib/ethers-5.1.esm.min.js",
|
||||
"link-ethers-npm": "https:/\/www.npmjs.com/search?q=%40ethersproject%2F",
|
||||
"link-ethers-asm-grammar": "https:/\/github.com/ethers-io/ethers.js/blob/master/packages/asm/grammar.jison",
|
||||
|
||||
"link-eip-155": { name: "EIP-155", url: "https:/\/eips.ethereum.org/EIPS/eip-155" },
|
||||
"link-eip-191": { name: "EIP-191", url: "https:/\/eips.ethereum.org/EIPS/eip-191" },
|
||||
"link-eip-609": { name: "EIP-609", url: "https:/\/eips.ethereum.org/EIPS/eip-609" },
|
||||
"link-eip-634": { name: "EIP-634", url: "https:/\/eips.ethereum.org/EIPS/eip-634" },
|
||||
"link-eip-712": { name: "EIP-712", url: "https:/\/eips.ethereum.org/EIPS/eip-712" },
|
||||
"link-eip-1014": { name: "EIP-1014", url: "https:/\/eips.ethereum.org/EIPS/eip-1014" },
|
||||
"link-eip-1193": { name: "EIP-1193", url: "https:/\/eips.ethereum.org/EIPS/eip-1193" },
|
||||
"link-eip-1577": { name: "EIP-1577", url: "https:/\/eips.ethereum.org/EIPS/eip-1577" },
|
||||
"link-eip-2098": { name: "EIP-2098", url: "https:/\/eips.ethereum.org/EIPS/eip-2098" },
|
||||
"link-eip-2304": { name: "EIP-2304", url: "https:/\/eips.ethereum.org/EIPS/eip-2304" },
|
||||
"link-eip-2718": { name: "EIP-2718", url: "https:/\/eips.ethereum.org/EIPS/eip-2718" },
|
||||
"link-eip-2930": { name: "EIP-2930", url: "https:/\/eips.ethereum.org/EIPS/eip-2930" },
|
||||
"link-bip-39": { name: "BIP-39", url: "https:/\/en.bitcoin.it/wiki/BIP_0039" },
|
||||
"link-bip-32": { name: "BIP-32", url: "https:/\/github.com/bitcoin/bips/blob/master/bip-0032.mediawiki" },
|
||||
"link-bip-44": { name: "BIP-44", url: "https:/\/en.bitcoin.it/wiki/BIP_0044" },
|
||||
|
||||
"link-npm-elliptic": { name: "elliptic", url: "https:/\/www.npmjs.com/package/elliptic" },
|
||||
"link-npm-ethersproject-shims": { name: "Shims", url: "https:/\/www.npmjs.com/package/@ethersproject/shims" },
|
||||
"link-npm-events": { name: "EventEmitter", url: "https:/\/nodejs.org/dist/latest-v13.x/docs/api/events.html#events_class_eventemitter" },
|
||||
"link-npm-bnjs": { name: "BN.js", url: "https:/\/www.npmjs.com/package/bn.js" },
|
||||
"link-npm-query-bignumber": "https:/\/www.npmjs.com/search?q=bignumber",
|
||||
"link-npm-react-native-get-random-values": { name: "React Native get-random-values", url: "https:/\/www.npmjs.com/package/react-native-get-random-values" },
|
||||
|
||||
"link-js-array": "https:/\/developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array",
|
||||
"link-js-bigint": "https:/\/developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt",
|
||||
"link-js-normalize": { name: "String.normalize", url: "https:/\/developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/normalize" },
|
||||
"link-js-maxsafe": "https:/\/developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/MAX_SAFE_INTEGER#Description",
|
||||
"link-js-proxy": "https:/\/developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy",
|
||||
"link-js-typedarray": "https:/\/developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray",
|
||||
|
||||
"link-cors": { name: "CORS", url: "https:/\/developer.mozilla.org/en-US/docs/Web/HTTP/CORS" },
|
||||
|
||||
"link-ricmoo-humanreadableabi": "https:/\/blog.ricmoo.com/human-readable-contract-abis-in-ethers-js-141902f4d917",
|
||||
|
||||
"link-other-ethereum-dev-docs": "https:/\/ethereum.org/en/developers/docs/",
|
||||
|
||||
"link-wiki-basicauth": { name: "Basic Authentication", url: "https:/\/en.wikipedia.org/wiki/Basic_access_authentication" },
|
||||
"link-wiki-backoff": { name: "Exponential Backoff", url: "https:/\/en.wikipedia.org/wiki/Exponential_backoff" },
|
||||
"link-wiki-bloomfilter": { name: "Bloom Filter", url: "https:/\/en.wikipedia.org/wiki/Bloom_filter" },
|
||||
"link-wiki-bruteforce": "https:/\/en.wikipedia.org/wiki/Brute-force_attack",
|
||||
"link-wiki-cryptographichash": "https:/\/en.wikipedia.org/wiki/Cryptographic_hash_function",
|
||||
"link-wiki-csrf": "https:/\/en.wikipedia.org/wiki/Cross-site_request_forgery",
|
||||
"link-wiki-ecrecover": { name: "ECDSA Public Key Recovery", url: "https:/\/en.wikipedia.org/wiki/Elliptic_Curve_Digital_Signature_Algorithm#Public_key_recovery" },
|
||||
"link-wiki-homoglyph": "https:/\/en.wikipedia.org/wiki/IDN_homograph_attack",
|
||||
"link-wiki-hmac": "https:/\/en.wikipedia.org/wiki/HMAC",
|
||||
"link-wiki-iban": "https:/\/en.wikipedia.org/wiki/International_Bank_Account_Number",
|
||||
"link-wiki-ieee754": "https:/\/en.wikipedia.org/wiki/Double-precision_floating-point_format",
|
||||
"link-wiki-observer-pattern": { name: "Obeserver Pattern", url: "https:/\/en.wikipedia.org/wiki/Observer_pattern" },
|
||||
"link-wiki-phishing": "https:/\/en.wikipedia.org/wiki/Phishing",
|
||||
"link-wiki-ripemd": "https:/\/en.m.wikipedia.org/wiki/RIPEMD",
|
||||
"link-wiki-sha2": "https:/\/en.wikipedia.org/wiki/SHA-2",
|
||||
"link-wiki-twoscomplement": "https:/\/en.wikipedia.org/wiki/Two%27s_complement",
|
||||
"link-wiki-unicode-equivalence": "https:/\/en.wikipedia.org/wiki/Unicode_equivalence",
|
||||
"link-wiki-utf8-overlong": "https:/\/en.wikipedia.org/wiki/UTF-8#Overlong_encodings",
|
||||
"link-wiki-utf8-replacement": "https:/\/en.wikipedia.org/wiki/Specials_%28Unicode_block%29#Replacement_character",
|
||||
"link-wiki-scrypt": "https:/\/en.wikipedia.org/wiki/Scrypt",
|
||||
"link-wiki-side-channel-attack": "https:/\/en.wikipedia.org/wiki/Side-channel_attack",
|
||||
"link-wiki-sha3": "https:/\/en.wikipedia.org/wiki/SHA-3",
|
||||
"link-wiki-shuffle": { name: "Fisher-Yates Shuffle", url: "https:/\/en.wikipedia.org/wiki/Fisher-Yates_shuffle" },
|
||||
"link-wiki-overflow": { name: "overflow", url: "https:/\/en.wikipedia.org/wiki/Integer_overflow" },
|
||||
"link-wiki-underflow": { name: "arithmetic underflow", url: "https:/\/en.wikipedia.org/wiki/Arithmetic_underflow" },
|
||||
"link-wiki-xss": "https:/\/en.wikipedia.org/wiki/Cross-site_scripting",
|
||||
},
|
||||
};
|
||||
15
docs.wrm/config.json
Normal file
15
docs.wrm/config.json
Normal file
@ -0,0 +1,15 @@
|
||||
{
|
||||
"title": "ethers",
|
||||
"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"
|
||||
},
|
||||
"source": {
|
||||
"path": "../packages/",
|
||||
"include": "packages/.*/src.ts/",
|
||||
"exclude": "/node_modules/|src.ts/.*browser.*",
|
||||
"link": "https://github.com/ethers-io/ethers.js/blob/ethers-v5-beta/packages$FILENAME#L$LINE"
|
||||
}
|
||||
}
|
||||
@ -1,86 +0,0 @@
|
||||
import { inspect } from "util";
|
||||
|
||||
import * as ethers from "../lib.esm/index.js";
|
||||
import { version } from "../lib.esm/_version.js";
|
||||
|
||||
import { getModifiedTime } from "../lib.esm/_admin/utils/git.js";
|
||||
|
||||
const title = "ethers";
|
||||
|
||||
const subtitle = (function(version) {
|
||||
const dash = version.indexOf("-");
|
||||
if (dash === -1) { return version; }
|
||||
return version.substring(dash + 1);
|
||||
})(version);
|
||||
|
||||
const extraLinks = function() {
|
||||
return [
|
||||
`link-cdnjs [ethers.min.js](https:/\/cdnjs.cloudflare.com/ajax/libs/ethers/${ version }/ethers.min.js)`,
|
||||
`link-cdnjs-wordlists [wordlists-extra.min.js](https:/\/cdnjs.cloudflare.com/ajax/libs/ethers/${ version }/wordlists-extra.min.js)`,
|
||||
];
|
||||
}
|
||||
|
||||
export default {
|
||||
title, subtitle,
|
||||
|
||||
// Where all the basic documentation is
|
||||
docRoot: ".",
|
||||
|
||||
// Where all the code is for the jsdocs API crawler
|
||||
codeRoot: "../src.ts/index.ts",
|
||||
|
||||
// Place all files in the /v6/ folder
|
||||
prefix: "v6",
|
||||
|
||||
// Prepare the context for running the examples
|
||||
contextify: function(context) {
|
||||
Object.assign(context, ethers);
|
||||
context.provider = new ethers.InfuraProvider();
|
||||
context.Uint8Array = Uint8Array;
|
||||
|
||||
ethers.InfuraProvider.prototype[inspect.custom] = function(depth, options, inspect) {
|
||||
if (depth > 0) { return `InfuraProvider { ... }`; }
|
||||
// Does this cause infinite recursion??
|
||||
return this;
|
||||
};
|
||||
|
||||
ethers.Interface.prototype[inspect.custom] = function(depth, options, inspect) {
|
||||
if (depth > 0) { return `Interface { ... }`; }
|
||||
// Does this cause infinite recursion??
|
||||
return this;
|
||||
};
|
||||
|
||||
ethers.Fragment.prototype[inspect.custom] = function(depth, options, inspect) {
|
||||
if (depth > 0) { return `${ this.constructor.name } { ... }`; }
|
||||
// Does this cause infinite recursion??
|
||||
return this;
|
||||
};
|
||||
},
|
||||
|
||||
// The base URL to use for the <src> links
|
||||
srcBaseUrl: "https:/\/github.com/ethers-io/ethers.js/blob/main/src.ts/{FILENAME}#L{LINENO}",
|
||||
|
||||
// Used at the bottom of each page to indicate the last-modified-time.
|
||||
// This uses the most recent time in the repo that the file was
|
||||
// updated.
|
||||
getTimestamp: function(path) {
|
||||
return getModifiedTime(path);
|
||||
},
|
||||
|
||||
// All the links to pull in
|
||||
links: [
|
||||
"./links/javascript.txt",
|
||||
"./links/npm.txt",
|
||||
"./links/projects.txt",
|
||||
"./links/ricmoo.txt",
|
||||
"./links/specs.txt",
|
||||
"./links/wiki.txt",
|
||||
extraLinks
|
||||
],
|
||||
|
||||
// Extra files to copy over to the /static folder
|
||||
staticFiles: [
|
||||
"logo.svg",
|
||||
"social.jpg"
|
||||
]
|
||||
};
|
||||
@ -1,123 +1,223 @@
|
||||
_section: Contributions and Hacking @<about-contrib> @priority<-90>
|
||||
_section: Contributing and Hacking @<contributing>
|
||||
|
||||
Pull requests are welcome, but please keep the following in mind:
|
||||
The ethers.js library is something that I've written out of necessity,
|
||||
and has grown somewhat organically over time.
|
||||
|
||||
- Backwards-compatibility-breaking changes will not be accepted;
|
||||
they may be considered for the next major version
|
||||
- Security is important; adding dependencies require fairly
|
||||
convincing arguments as to why
|
||||
- The library aims to be lean, so keep an eye on the
|
||||
``dist/ethers.min.js`` file size before and after your
|
||||
changes (the ``build-clean`` target includes these stats)
|
||||
- Keep the PR simple, readable and confined to the relevant
|
||||
files; see below for which files to change
|
||||
Many things are the way they are for good (at the time, at least) reasons,
|
||||
but I always welcome criticism, and am completely willing to have my mind
|
||||
changed on things.
|
||||
|
||||
Pull requests are always welcome, but please keep a few points in mind:
|
||||
|
||||
- Backwards-compatibility-breaking changes will not be accepted; they may be
|
||||
considered for the next major version
|
||||
- Security is important; adding dependencies require fairly convincing
|
||||
arguments as to why
|
||||
- The library aims to be lean, so keep an eye on the dist/ethers.min.js
|
||||
file size before and after your changes
|
||||
- Keep the PR simple and readable; only modify files in the ``docs.wrm/``
|
||||
and ``packages/*/src.ts/`` folders, as this allows the changes to be easily
|
||||
verified
|
||||
- Add test cases for both expected and unexpected input
|
||||
- Any new features need to be supported by me (future issues,
|
||||
documentation, testing, migration), so anything that is
|
||||
overly complicated or specific may not be accepted
|
||||
- Everyone is working hard; **be kind and respectful**
|
||||
- Any new features need to be supported by me (future issues, documentation,
|
||||
testing, migration), so anything that is overly complicated or specific
|
||||
may not be accepted
|
||||
|
||||
It is always //highly recommended// that you open a [[link-discussion]]
|
||||
**before** beginning a PR.
|
||||
In general, **please start an issue //before// beginning a pull request**, so we can
|
||||
have a public discussion and figure out the best way to address the problem/feature.
|
||||
**:)**
|
||||
|
||||
|
||||
_subsection: Documentation @<about-contrib-docs>
|
||||
_subsection: Building @<contributing--building>
|
||||
|
||||
The documentation is an area which can always benefit from extra
|
||||
eyes, extra knowledge and extra examples.
|
||||
The build process for ethers is unfortunatly not super trivial, but
|
||||
I have attempted to make it as straight-forward as possible.
|
||||
|
||||
Contributing to the documentation is welcome, but when making
|
||||
changes to documentation, please ensure that all changes are
|
||||
made **only** to:
|
||||
It is a mono-repo which attempts to be compatibile with a large
|
||||
number of environments, build tools and platforms, which is why
|
||||
there are a some weird things it must do.
|
||||
|
||||
- Updating ``/docs.wrm/*\*.wrm``
|
||||
- Adding links: ``/docs.wrm/links/*.txt``
|
||||
- Updating API jsdocs: ``/*\* ... */`` comment blocks within ``/src.ts/``
|
||||
There are several custom scripts in the ``misc/admin`` folder
|
||||
to help manage the monorepo. Developers working on contributing
|
||||
to ethers should not generally need to worry about those, since
|
||||
they are wrapped up behind ``npm run SCRIPT`` operations.
|
||||
|
||||
Generally changes to ``/docs.wrm/config.wrm`` should not be
|
||||
made, and if you feel it is necessary, please consider opening
|
||||
a [[link-discussion]] first.
|
||||
_code: Installing @lang<shell>
|
||||
|
||||
Similarly, when adding a new sections, a [[link-discussion]] is
|
||||
preferred.
|
||||
# Clone the repository
|
||||
/home/ricmoo> git clone https://github.com/ethers-io/ethers.js.git
|
||||
|
||||
All changes should be in the Flatworm Markdown Dialect.
|
||||
/home/ricmoo> cd ethers.js
|
||||
|
||||
_heading: Building the Documentation
|
||||
# Install all dependencies:
|
||||
# - Hoists all sub-package dependencies in the package.json (preinstall)
|
||||
# - Installs all the (hoisted) dependencies and devDependencies (install)
|
||||
# - Build the rat-nests (in .package_node_modules) (postinstall)
|
||||
# - Create a dependency graph for the TypeScript (postinstall)
|
||||
# - Link the rat-nets into each project (postinstall)
|
||||
/home/ricmoo/ethers.js> npm install
|
||||
|
||||
Currently, the documentation is built using an experimental v2 of the
|
||||
Flatworm documentation system, a system originally specifically made
|
||||
to maintain the Ethers documentation.
|
||||
_heading: Making Changes @<contributing--updating>
|
||||
|
||||
The new ``tsdocs`` branch has the ability to parse ``jsdocs`` from
|
||||
from TypeScript source files to create an API reference.
|
||||
Once your environment is set up, you should be able to simply
|
||||
start the ``auto-build`` feature, and make changes to the
|
||||
TypeScript source.
|
||||
|
||||
_code: Building with the v2 Flatworm @lang<shell>
|
||||
_code: Watching and Building @lang<shell>
|
||||
|
||||
# Clone the repo
|
||||
/home/ricmoo> git clone https://github.com/ricmoo/flatworm.git
|
||||
/home/ricmoo> cd flatworm
|
||||
# Begin watching the files and re-building whenever they change
|
||||
/home/ricmoo/ethers.js> npm run auto-build
|
||||
|
||||
# Check out the tsdocs branch
|
||||
/home/ricmoo/flatworm> git checkout tsdocs
|
||||
# Or if you do not want to watch and just build
|
||||
/home/ricmoo/ethers.js> npm run build
|
||||
|
||||
# Install the necessary dependencies
|
||||
/home/ricmoo/flatworm> npm install
|
||||
_heading: Creating Browser-Ready Files
|
||||
|
||||
# Ready to build the docs; output to a folder ./output/
|
||||
/home/ricmoo/flatworm> node lib/cli-test PATH_TO_WRM_ROOT
|
||||
To create files for use directly in a browser, the distribution
|
||||
files (located in ``packages/ethers/dist``) need to be built
|
||||
which requires several intermediate builds, scripts and for
|
||||
various rollup scripts to execute.
|
||||
|
||||
Eventually the code for the v2 branch will be cleaned up, and it
|
||||
will be much easier to include as a ``devDependency`` for Ethers.
|
||||
_code: Building Distribution Files @lang<shell>
|
||||
|
||||
In the meantime, expect new changes to be made frequently to the
|
||||
``tsdocs`` branch, so for stability you may wish to checkout a
|
||||
specific hash.
|
||||
# If you need to rebuild all the libs (esm + cjs) and dist files
|
||||
# Note: this requires node 10 or newer
|
||||
/home/ricmoo/ethers.js> npm run build-all
|
||||
|
||||
_heading: Testing
|
||||
|
||||
_code: Testing @lang<shell>
|
||||
|
||||
# Rebuilds all files (npm run build-all) and bundles testcases up for testing
|
||||
/home/ricmoo/ethers.js> npm test
|
||||
|
||||
# Often you don't need the full CI experience
|
||||
/home/ricmoo/ethers.js> npm run test-node
|
||||
|
||||
_heading: Distribution
|
||||
|
||||
Most developers should not ever require this step, but for people
|
||||
forking ethers and creating alternates (for example if you have
|
||||
a non-EVM compatible chain but are trying to reuse this package).
|
||||
|
||||
This script will rebuild the entire ethers project, compare it
|
||||
against npm, re-write package versions, update internal hashes,
|
||||
re-write various TypeScript files (to get around some ES+TS
|
||||
limitations for Tree Shaking and linking), re-write map files,
|
||||
bundle stripped versions of dependencies and basically just a
|
||||
whole bunch of stuff.
|
||||
|
||||
If you use this and get stuck, [message me](link-mail).
|
||||
|
||||
_code: Preparing the Distribution @lang<shell>
|
||||
|
||||
# Prepare all the distribution files
|
||||
# - Remove all generated files (i.e. npm run clean)
|
||||
# - Re-install all dependencies, hoisting, etc. (npm install)
|
||||
# - Spell check all strings in every TypeScript files
|
||||
# - Build everything from scratch with this clean install
|
||||
# - Compare local with npm, bumping the version if changed
|
||||
# - Build everything again (with the updated versions)
|
||||
# - Update the CHANGELOG.md with the git history since the last change
|
||||
/home/ricmoo/ethers.js> npm run update-version
|
||||
|
||||
_note: Do NOT check in dist files in a PR
|
||||
|
||||
For Pull Requests, please ONLY commit files in the ``docs.wrm/`` and
|
||||
``packages/*/src.ts/`` folders. I will prepare the distribution builds
|
||||
myself and keeping the PR relevant makes it easier to verify the changes.
|
||||
|
||||
_heading: Publishing
|
||||
|
||||
Again, this should not be necessary for most developers. This step
|
||||
requires using the ``misc/admin/cmds/config-set`` script for a number
|
||||
of values, including private keys, NPM session keys, AWS access keys,
|
||||
GitHub API tokens, etc.
|
||||
|
||||
The config file is encrypted with about 30 seconds of scrypt password-based
|
||||
key derivation function, so brute-forcing the file is quite expensive.
|
||||
|
||||
The config file also contains a plain-text mnemonic. This is a money-pot.
|
||||
Place a tempting amount of ether or Bitcoin on this account and set up an
|
||||
e-mail alert for this account.
|
||||
|
||||
If any attacker happens across your encrypted config, they will have instant
|
||||
access to the plain-text mnemonic, so they have the option to immediately
|
||||
steal the ether (i.e. the responsible-disclosure bond).
|
||||
|
||||
If you ever see this ether taken, your encrypted file is compromised! Rotate
|
||||
all your AWS keys, NPM session keys, etc. immedately.
|
||||
|
||||
@TODO: document all the keys that need to be set for each step
|
||||
|
||||
_code: Preparing the Distribution @lang<shell>
|
||||
|
||||
# Publish
|
||||
# - Update any changed packages to NPM
|
||||
# - Create a release on GitHub with the latest CHANGELOG.md description
|
||||
# - Upload the bundled files the the CDN
|
||||
# - Flush the CDN edge caches
|
||||
/home/ricmoo/ethers.js> npm run publish-all
|
||||
|
||||
|
||||
_subsection: Fixing Bugs @<about-contrib-bugs>
|
||||
_subsection: Documentation @<contributing--documentation>
|
||||
|
||||
In general the **only** files you should ever include in a PR are:
|
||||
The documents are generated using [Flatworm](flatworm) documentation
|
||||
generation tool, which was written for the purpose of writing the documentation
|
||||
for ethers.
|
||||
|
||||
- TypeScript source: ``/src.ts/*\*.ts``
|
||||
Style Guide (this section will have much more coming):
|
||||
|
||||
Do not include a ``package.json`` with the updated ``tarballHash``
|
||||
or ``version``, and do not include any generated files in your PR.
|
||||
|
||||
A bug fix **must not** modify anything requiring a minor version
|
||||
bump (see [[about-contrib-feature]]), such as changing a method
|
||||
signature or altering the exports.
|
||||
- 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 symlinks in the future
|
||||
- In general, I aim for consistency; look to similar situations throughout the documentation
|
||||
|
||||
|
||||
_subsection: Adding Features @<about-contrib-feature>
|
||||
_heading: Building
|
||||
|
||||
Contributing new features usually require a deeper understanding
|
||||
of the internal interactions with Ethers and its components, and
|
||||
generally requires a minor version bump.
|
||||
To build the documentation, you should first follow the
|
||||
[above steps](contributing--building) to build the ethers library.
|
||||
|
||||
When making any of the following changes, you must first open a
|
||||
[[link-discussion]] as the minor version will need to be bumped.
|
||||
Building the docs will generate several types of output:
|
||||
|
||||
- any signature change (such as adding a parameter, changing a
|
||||
parameter type, changing the return type)
|
||||
- adding any new export; such as a class, function or constants
|
||||
- adding any method to any class
|
||||
- changing any ``exports`` property within the ``package.json``
|
||||
- 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
|
||||
|
||||
Changes of this sort should not be made without serious consideration
|
||||
and discussion.
|
||||
_code: Building the Documentations @lang<shell>
|
||||
|
||||
/home/ricmoo/ethers.js> npm run build-docs
|
||||
|
||||
|
||||
_subsection: Building @<building>
|
||||
_heading: Evaluation
|
||||
|
||||
_code: @lang<shell>
|
||||
/home/ricmoo> git clone @TODO
|
||||
/home/ricmoo> cd ethers
|
||||
/home/ricmoo/ethers> npm install
|
||||
/home/ricmoo/ethers> npm run auto-build
|
||||
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.
|
||||
|
||||
_null:
|
||||
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
|
||||
|
||||
|
||||
_subsection: Previewing Documentation
|
||||
_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
|
||||
|
||||
@ -1,66 +0,0 @@
|
||||
_section: Cookbook: ENS Recipes @<cookbook-ens>
|
||||
|
||||
Here is a collection of short, but useful examples of working with
|
||||
ENS entries.
|
||||
|
||||
|
||||
_subsection: Get all Text records @<cookbook-ens-allText>
|
||||
|
||||
Here is a short recipe to get all the text records set for an ENS
|
||||
name.
|
||||
|
||||
It first queries all ``TextChanged`` events on the resovler, and
|
||||
uses a MulticallProvider to batch all the ``eth_call`` queries
|
||||
for each key into a single ``eth_call``. As such, you will need
|
||||
to install:
|
||||
|
||||
``/home/ricmoo> npm install @ethers-ext/provider-multicall``
|
||||
|
||||
|
||||
_code: Fetching all ENS text records. @lang<script>
|
||||
|
||||
import { ethers } from "ethers";
|
||||
import { MulticallProvider } from "@ethers-ext/provider-multicall";
|
||||
|
||||
async function getTextRecords(_provider, name) {
|
||||
// Prepare a multicall-based provider to batch all the call operations
|
||||
const provider = new MulticallProvider(_provider);
|
||||
|
||||
// Get the resolver for the given name
|
||||
const resolver = await provider.getResolver(name);
|
||||
|
||||
// A contract instance; used filter and parse logs
|
||||
const contract = new ethers.Contract(resolver.address, [
|
||||
"event TextChanged(bytes32 indexed node, string indexed _key, string key)"
|
||||
], provider);
|
||||
|
||||
// A filter for the given name
|
||||
const filter = contract.filters.TextChanged(ethers.namehash(name));
|
||||
|
||||
// Get the matching logs
|
||||
const logs = await contract.queryFilter(filter);
|
||||
|
||||
// Filter the *unique* keys
|
||||
const keys = [ ...(new Set(logs.map((log) => log.args.key))) ];
|
||||
|
||||
// Get the values for the keys; failures are discarded
|
||||
const values = await Promise.all(keys.map((key) => {
|
||||
try {
|
||||
return resolver.getText(key);
|
||||
} catch (error) { }
|
||||
return null;
|
||||
}));
|
||||
|
||||
// Return a Map of the key/value pairs
|
||||
return keys.reduce((accum, key, index) => {
|
||||
const value = values[index];
|
||||
if (value != null) { accum.set(key, value); }
|
||||
return accum;
|
||||
}, new Map());
|
||||
}
|
||||
|
||||
// Example usage
|
||||
(async function() {
|
||||
const provider = new ethers.InfuraProvider();
|
||||
console.log(await getTextRecords(provider, "ricmoo.eth"));
|
||||
})();
|
||||
@ -1,7 +1,9 @@
|
||||
_section: Cookbook @<cookbook>
|
||||
_section: Cookbook
|
||||
|
||||
A growing collection of code snippets for common problems and use cases
|
||||
when developing dapps and other blockchain tools.
|
||||
A collection (that will grow over time) of common, simple
|
||||
snippets of code that are in general useful.
|
||||
|
||||
_toc:
|
||||
|
||||
react-native
|
||||
|
||||
- [Signing Messages and Data](cookbook-signing)
|
||||
- [React Native Performance](cookbook-react-native)
|
||||
|
||||
@ -1,36 +1,60 @@
|
||||
_section: React Native @<cookbook-react-native>
|
||||
_section: React Native (and ilk) @<cookbook-reactnative>
|
||||
|
||||
When using React Native, many of the built-in cryptographic primitives
|
||||
can be replaced by native, substantially faster implementations.
|
||||
The [[link-react-native]] framework has become quite popular and
|
||||
has many popular forks, such as [[link-expo]].
|
||||
|
||||
This should be available in its own package in the future, but for now
|
||||
this is highly recommended, and requires installing the
|
||||
[[link-npm-react-native-quick-crypto]] package.
|
||||
React Native is based on [[link-javascriptcore]] (part of WebKit) and
|
||||
does not use Node.js or the common Web and DOM APIs. As such,
|
||||
there are many operations missing that a normal web environment
|
||||
or Node.js instance would provide.
|
||||
|
||||
For this reason, there is a [[link-npm-ethersproject-shims]] module
|
||||
provided to fill in the holes.
|
||||
|
||||
|
||||
_code:
|
||||
_subsection: Installing @<cookbook-reactnative-shims>
|
||||
|
||||
To use ethers in React Native, you must either provide shims for the needed
|
||||
missing functionality, or use the ethers.js shim.
|
||||
|
||||
It is **HIGHLY RECOMMENDED** you check out the [security section](cookbook-reactnative-security)
|
||||
below for instructions on installing packages which can affect the security
|
||||
of your application.
|
||||
|
||||
After installing packages, you may need to restart your packager and company.
|
||||
|
||||
_code: Installing @lang<shell>
|
||||
|
||||
/home/ricmoo/my-react-project> npm install @ethersproject/shims --save
|
||||
|
||||
_code: Importing @lang<script>
|
||||
|
||||
// Pull in the shims (BEFORE importing ethers)
|
||||
import "@ethersproject/shims"
|
||||
|
||||
// Import the ethers library
|
||||
import { ethers } from "ethers";
|
||||
|
||||
import crypto from "react-native-quick-crypto";
|
||||
|
||||
ethers.randomBytes.register((length) => {
|
||||
return new Uint8Array(crypto.randomBytes(length));
|
||||
});
|
||||
_subsection: Security @<cookbook-reactnative-security>
|
||||
|
||||
ethers.computeHmac.register((algo, key, data) => {
|
||||
return crypto.createHmac(algo, key).update(data).digest();
|
||||
});
|
||||
The React Native environment does not contain a secure random source, which
|
||||
is used when computing random private keys. This could result in private
|
||||
keys that others could possibly guess, allowing funds to be stolen and assets
|
||||
manipulated.
|
||||
|
||||
ethers.pbkdf2.register((passwd, salt, iter, keylen, algo) => {
|
||||
return crypto.pbkdf2Sync(passwd, salt, iter, keylen, algo);
|
||||
});
|
||||
For this reason, it is **HIGHLY RECOMMENDED** to also install the
|
||||
[[link-npm-react-native-get-random-values]], which **must** be included
|
||||
before the shims. If it worked correctly you should not receive any
|
||||
warning in the console regarding missing secure random sources.
|
||||
|
||||
ethers.sha256.register((data) => {
|
||||
return crypto.createHash('sha256').update(data).digest();
|
||||
});
|
||||
_code: Importing with Secure Random Sources @lang<script>
|
||||
|
||||
ethers.sha512.register((data) => {
|
||||
return crypto.createHash('sha512').update(data).digest();
|
||||
});
|
||||
// Import the crypto getRandomValues shim (**BEFORE** the shims)
|
||||
import "react-native-get-random-values"
|
||||
|
||||
// Import the the ethers shims (**BEFORE** ethers)
|
||||
import "@ethersproject/shims"
|
||||
|
||||
// Import the ethers library
|
||||
import { ethers } from "ethers";
|
||||
|
||||
@ -1,273 +0,0 @@
|
||||
_section: Signing @<cookbook-signing>
|
||||
|
||||
Signing content and providing the content and signature to a
|
||||
Contract allows on-chain validation that a signer has access
|
||||
to the private key of a specific address.
|
||||
|
||||
The ecrecover algorithm allows the public key to be determined
|
||||
given some message digest and the signature generated by the
|
||||
private key for that digest. From the public key, the address
|
||||
can then be computed.
|
||||
|
||||
How a digest is derived depends on the type of data being
|
||||
signed and a variety of encoding formats are employed. Each
|
||||
format is designed to ensure that they do not collide, so for
|
||||
example, a user **cannot** be tricked into signing a message
|
||||
which is actually a valid transaction.
|
||||
|
||||
For this reason, most APIs in Ethereum do not permit signing a
|
||||
raw digest, and instead require a separate API for each format
|
||||
type and require the related data be specified, protecting the
|
||||
user from accidentally authorizing an action they didn't intend.
|
||||
|
||||
_subsection: Messages @<cookbook-signing-messages>
|
||||
|
||||
A signed message can be any data, but it is generally recommended
|
||||
to use human-readable text, as this is easier for a user to
|
||||
verify visually.
|
||||
|
||||
This technique could be used, for example, to sign into a service
|
||||
by using the text ``"I am signing into ethers.org on 2023-06-04 12:57pm"``.
|
||||
The user can then see the message in MetaMask or on a Ledger
|
||||
Hardware Wallet and accept that they wish to sign the message which
|
||||
the site can then authenticate them with. By providing a timestamp
|
||||
the site can ensure that an older signed message cannot be used again
|
||||
in the future.
|
||||
|
||||
The format that is signed uses [[link-eip-191]] with the
|
||||
**personal sign** version code (``0x45``, or ``"E"``).
|
||||
|
||||
For those interested in the choice of this prefix, signed messages
|
||||
began as a Bitcoin feature, which used ``"\\x18Bitcoin Signed Message:\\n"``,
|
||||
which was a Bitcoin var-int length-prefixed string (as ``0x18`` is 24,
|
||||
the length of ``"Bitcoin Signed Message:\\n"``.). When Ethereum adopted
|
||||
the similar feature, the relevant string was ``"\\x19Ethereum Signed Message:\\n"``.
|
||||
|
||||
In one of the most brilliant instances of technical retcon-ing,
|
||||
since 0x19 is invalid as the first byte of a transaction (in [[link-rlp]] it
|
||||
indicates a single byte of value 25), the initial byte ``\\x19`` has
|
||||
now been adopted as a prefix for //some sort of signed data//,
|
||||
where the second byte determines how to interpret that data. If the
|
||||
second byte is 69 (the letter ``"E"``, as in
|
||||
``"Ethereum Signed Message:\\n"``), then the format is a
|
||||
the above prefixed message format.
|
||||
|
||||
So, all existing messages, tools and instances using the signed
|
||||
message format were already EIP-191 compliant, long before the
|
||||
standard existed or was even conceived and allowed for an extensible
|
||||
format for future formats (of which there now a few).
|
||||
|
||||
Anyways, the necessary JavaScript and Solidity are provided below.
|
||||
|
||||
_code: JavaScript @lang<javascript>
|
||||
|
||||
// The contract below is deployed to Sepolia at this address
|
||||
contractAddress = "0xf554DA5e35b2e40C09DDB481545A395da1736513";
|
||||
contract = new Contract(contractAddress, [
|
||||
"function recoverStringFromCompact(string message, (bytes32 r, bytes32 yParityAndS) sig) pure returns (address)",
|
||||
"function recoverStringFromExpanded(string message, (uint8 v, bytes32 r, bytes32 s) sig) pure returns (address)",
|
||||
"function recoverStringFromVRS(string message, uint8 v, bytes32 r, bytes32 s) pure returns (address)",
|
||||
"function recoverStringFromRaw(string message, bytes sig) pure returns (address)",
|
||||
"function recoverHashFromCompact(bytes32 hash, (bytes32 r, bytes32 yParityAndS) sig) pure returns (address)"
|
||||
], new ethers.InfuraProvider("sepolia"));
|
||||
|
||||
// The Signer; it does not need to be connected to a Provider to sign
|
||||
signer = new Wallet(id("foobar"));
|
||||
signer.address
|
||||
//_result:
|
||||
|
||||
// Our message
|
||||
message = "Hello World";
|
||||
|
||||
// The raw signature; 65 bytes
|
||||
rawSig = await signer.signMessage(message);
|
||||
//_result:
|
||||
|
||||
// Converting it to a Signature object provides more
|
||||
// flexibility, such as using it as a struct
|
||||
sig = Signature.from(rawSig);
|
||||
//_result:
|
||||
|
||||
|
||||
// If the signature matches the EIP-2098 format, a Signature
|
||||
// can be passed as the struct value directly, since the
|
||||
// parser will pull out the matching struct keys from sig.
|
||||
await contract.recoverStringFromCompact(message, sig);
|
||||
//_result:
|
||||
|
||||
// Likewise, if the struct keys match an expanded signature
|
||||
// struct, it can also be passed as the struct value directly.
|
||||
await contract.recoverStringFromExpanded(message, sig);
|
||||
//_result:
|
||||
|
||||
// If using an older API which requires the v, r and s be passed
|
||||
// separately, those members are present on the Signature.
|
||||
await contract.recoverStringFromVRS(message, sig.v, sig.r, sig.s);
|
||||
//_result:
|
||||
|
||||
// Or if using an API that expects a raw signature.
|
||||
await contract.recoverStringFromRaw(message, rawSig);
|
||||
//_result:
|
||||
|
||||
// Note: The above recovered addresses matches the signer address
|
||||
|
||||
_null:
|
||||
|
||||
The Solidity Contract has been deployed and verified on
|
||||
the Sepolia testnet at the address
|
||||
[0xf554DA5e35b2e40C09DDB481545A395da1736513](link-sol-recovermessage).
|
||||
|
||||
It provides a variety of examples using various Signature
|
||||
encodings and formats, to recover the address for an [[link-eip-191]]
|
||||
signed message.
|
||||
|
||||
_code: Solidity @lang<solidity>
|
||||
|
||||
// SPDX-License-Identifier: MIT
|
||||
|
||||
// For more info, see: https://docs.ethers.org
|
||||
|
||||
|
||||
pragma solidity ^0.8.21;
|
||||
|
||||
// Returns the decimal string representation of value
|
||||
function itoa(uint value) pure returns (string memory) {
|
||||
|
||||
// Count the length of the decimal string representation
|
||||
uint length = 1;
|
||||
uint v = value;
|
||||
while ((v /= 10) != 0) { length++; }
|
||||
|
||||
// Allocated enough bytes
|
||||
bytes memory result = new bytes(length);
|
||||
|
||||
// Place each ASCII string character in the string,
|
||||
// right to left
|
||||
while (true) {
|
||||
length--;
|
||||
|
||||
// The ASCII value of the modulo 10 value
|
||||
result[length] = bytes1(uint8(0x30 + (value % 10)));
|
||||
|
||||
value /= 10;
|
||||
|
||||
if (length == 0) { break; }
|
||||
}
|
||||
|
||||
return string(result);
|
||||
}
|
||||
|
||||
contract RecoverMessage {
|
||||
|
||||
// This is the EIP-2098 compact representation, which reduces gas costs
|
||||
struct SignatureCompact {
|
||||
bytes32 r;
|
||||
bytes32 yParityAndS;
|
||||
}
|
||||
|
||||
// This is an expaned Signature representation
|
||||
struct SignatureExpanded {
|
||||
uint8 v;
|
||||
bytes32 r;
|
||||
bytes32 s;
|
||||
}
|
||||
|
||||
// Helper function
|
||||
function _ecrecover(string memory message, uint8 v, bytes32 r, bytes32 s) internal pure returns (address) {
|
||||
// Compute the EIP-191 prefixed message
|
||||
bytes memory prefixedMessage = abi.encodePacked(
|
||||
"\x19Ethereum Signed Message:\n",
|
||||
itoa(bytes(message).length),
|
||||
message
|
||||
);
|
||||
|
||||
// Compute the message digest
|
||||
bytes32 digest = keccak256(prefixedMessage);
|
||||
|
||||
// Use the native ecrecover provided by the EVM
|
||||
return ecrecover(digest, v, r, s);
|
||||
}
|
||||
|
||||
// Recover the address from an EIP-2098 compact Signature, which packs the bit for
|
||||
// v into an unused bit within s, which saves gas overall, costing a little extra
|
||||
// in computation, but saves far more in calldata length.
|
||||
//
|
||||
// This Signature format is 64 bytes in length.
|
||||
function recoverStringFromCompact(string calldata message, SignatureCompact calldata sig) public pure returns (address) {
|
||||
|
||||
// Decompose the EIP-2098 signature (the struct is 64 bytes in length)
|
||||
uint8 v = 27 + uint8(uint256(sig.yParityAndS) >> 255);
|
||||
bytes32 s = bytes32((uint256(sig.yParityAndS) << 1) >> 1);
|
||||
|
||||
return _ecrecover(message, v, sig.r, s);
|
||||
}
|
||||
|
||||
// Recover the address from the expanded Signature struct.
|
||||
//
|
||||
// This Signature format is 96 bytes in length.
|
||||
function recoverStringFromExpanded(string calldata message, SignatureExpanded calldata sig) public pure returns (address) {
|
||||
|
||||
// The v, r and s are included directly within the struct, which is 96 bytes in length
|
||||
return _ecrecover(message, sig.v, sig.r, sig.s);
|
||||
}
|
||||
|
||||
// Recover the address from a v, r and s passed directly into the method.
|
||||
//
|
||||
// This Signature format is 96 bytes in length.
|
||||
function recoverStringFromVRS(string calldata message, uint8 v, bytes32 r, bytes32 s) public pure returns (address) {
|
||||
|
||||
// The v, r and s are included directly within the struct, which is 96 bytes in length
|
||||
return _ecrecover(message, v, r, s);
|
||||
}
|
||||
|
||||
// Recover the address from a raw signature. The signature is 65 bytes, which when
|
||||
// ABI encoded is 160 bytes long (a pointer, a length and the padded 3 words of data).
|
||||
//
|
||||
// When using raw signatures, some tools return the v as 0 or 1. In this case you must
|
||||
// add 27 to that value as v must be either 27 or 28.
|
||||
//
|
||||
// This Signature format is 65 bytes of data, but when ABI encoded is 160 bytes in length;
|
||||
// a pointer (32 bytes), a length (32 bytes) and the padded 3 words of data (96 bytes).
|
||||
function recoverStringFromRaw(string calldata message, bytes calldata sig) public pure returns (address) {
|
||||
|
||||
// Sanity check before using assembly
|
||||
require(sig.length == 65, "invalid signature");
|
||||
|
||||
// Decompose the raw signature into r, s and v (note the order)
|
||||
uint8 v;
|
||||
bytes32 r;
|
||||
bytes32 s;
|
||||
assembly {
|
||||
r := calldataload(sig.offset)
|
||||
s := calldataload(add(sig.offset, 0x20))
|
||||
v := calldataload(add(sig.offset, 0x21))
|
||||
}
|
||||
|
||||
return _ecrecover(message, v, r, s);
|
||||
}
|
||||
|
||||
// This is provided as a quick example for those that only need to recover a signature
|
||||
// for a signed hash (highly discouraged; but common), which means we can hardcode the
|
||||
// length in the prefix. This means we can drop the itoa and _ecrecover functions above.
|
||||
function recoverHashFromCompact(bytes32 hash, SignatureCompact calldata sig) public pure returns (address) {
|
||||
bytes memory prefixedMessage = abi.encodePacked(
|
||||
// Notice the length of the message is hard-coded to 32
|
||||
// here -----------------------v
|
||||
"\x19Ethereum Signed Message:\n32",
|
||||
hash
|
||||
);
|
||||
|
||||
bytes32 digest = keccak256(prefixedMessage);
|
||||
|
||||
// Decompose the EIP-2098 signature
|
||||
uint8 v = 27 + uint8(uint256(sig.yParityAndS) >> 255);
|
||||
bytes32 s = bytes32((uint256(sig.yParityAndS) << 1) >> 1);
|
||||
|
||||
return ecrecover(digest, v, sig.r, s);
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
_subsection: EIP-712 Typed Data @<cookbook-signing-eip712>
|
||||
|
||||
//Coming soon...//
|
||||
476
docs.wrm/documentation.wrm
Normal file
476
docs.wrm/documentation.wrm
Normal file
@ -0,0 +1,476 @@
|
||||
_section: Flatworm Docs @<flatworm>
|
||||
|
||||
The //Flatworm Docs// rendering engine is designed to be **very**
|
||||
simple, but provide enough formatting necessary for documenting
|
||||
JavaScript libraries.
|
||||
|
||||
A lot of its inspiration came from [Read the Docs](link-rtd) and
|
||||
the [Sphinx](link-sphinx) project.
|
||||
|
||||
|
||||
_subsection: Fragments @<flatworm-fragments>
|
||||
|
||||
Each page is made up of fragments. A fragment is a [directive](flatworm-directive),
|
||||
with an value and optional //link//, //extensions// and a body.
|
||||
|
||||
Many directives support [markdown](flatworm-markdown) in their value and body.
|
||||
|
||||
A fragment's body continues until another fragment is encountered.
|
||||
|
||||
|
||||
_heading: Directive Format
|
||||
|
||||
_code: @lang<text>
|
||||
|
||||
\_DIRECTIVE: VALUE @<LINK> @EXTENSION<PARAMETER>
|
||||
BODY
|
||||
|
||||
MORE BODY
|
||||
|
||||
DIRECTIVE: The directive name
|
||||
VALUE: Optional; the value to pass to the directive
|
||||
LINK: Optional; a name for internal linking
|
||||
EXTENSION: Optional; extended directive functionality
|
||||
PARAMETER: Optional; value to pass to extended directive functions
|
||||
BODY: Optional; the directive body (certain directives only)
|
||||
|
||||
|
||||
_heading: Flatworm Directives @<flatworm-directive>
|
||||
|
||||
_definition: **_section:** //TITLE//
|
||||
A //section// has its **TITLE** in an H1 font. Sections are linked
|
||||
to in //Table of Contents// and have a dividing line drawn above
|
||||
them.
|
||||
|
||||
The body supports markdown.
|
||||
|
||||
There should only be one ``_section:`` per page.
|
||||
|
||||
**Extensions:** [@inherit](flatworm--ext-inherit), [@src](flatworm--ext-src), [@nav](flatworm--ext-nav), [@note](flatworm--ext-note)
|
||||
|
||||
_definition: **_subsection:** //TITLE//
|
||||
A //subsection// has its **TITLE** in an H2 font. Subsections are linked
|
||||
to in //Table of Contents// and have a dividing line drawn above
|
||||
them.
|
||||
|
||||
The title and body support markdown.
|
||||
|
||||
**Extensions:** [@inherit](flatworm--ext-inherit), [@src](flatworm--ext-src), [@note](flatworm--ext-note)
|
||||
|
||||
_definition: **_heading:** //TITLE//
|
||||
A //heading// has its **TITLE** in an H3 font.
|
||||
|
||||
The title and body support markdown.
|
||||
|
||||
**Extensions:** [@inherit](flatworm--ext-inherit), [@src](flatworm--ext-src), [@note](flatworm--ext-note)
|
||||
|
||||
_definition: **_definition:** //TERM//
|
||||
A //definition// has its **TERM** in normal text and the body is
|
||||
indented.
|
||||
|
||||
The title and body support markdown.
|
||||
|
||||
_definition: **_property:** //SIGNATURE//
|
||||
A //property// has its JavaScript **SIGNATURE** formatted.
|
||||
|
||||
The body supports markdown and the return portion of the signature
|
||||
support markdown links.
|
||||
|
||||
**Extensions:** [@src](flatworm--ext-src)
|
||||
|
||||
_definition: **_note:** //BANNER//
|
||||
A //note// is placed in a blue bordered-box to draw attention to it.
|
||||
|
||||
The body supports markdown.
|
||||
|
||||
_definition: **_warning:** //BANNER//
|
||||
A //warning// is placed in an orange bordered-box to draw attention to it.
|
||||
|
||||
The body supports markdown.
|
||||
|
||||
_definition: **_code:** //CAPTION//
|
||||
Creates a [Code](flatworm--code) block.
|
||||
|
||||
The body does **not** support markdown, and will be output exactly as
|
||||
is, with the exception of [Code Evaluation](flatworm--code-eval).
|
||||
|
||||
If a line begins with a ``"_"``, it should be escaped with a ``"\\"``.
|
||||
|
||||
**Extensions:** [@lang](flatworm--ext-lang)
|
||||
|
||||
_definition: **_table:** //FOOTER//
|
||||
|
||||
Creates a [Table](flatworm--table) structured according to the body.
|
||||
|
||||
Each cell contents supports markdown and variables supports markdown.
|
||||
|
||||
**Extensions:** [@style](flatworm--ext-style)
|
||||
|
||||
_definition: **_toc:**
|
||||
A //toc// injects a Table of Contents, loading each line of the
|
||||
body as a filename and recursively loads the //toc// if present,
|
||||
otherwise all the //sections// and //subsections//.
|
||||
|
||||
The body does **not** support markdown, as it is interpreted as
|
||||
a list of files and directories to process.
|
||||
|
||||
_definition: **_null:**
|
||||
A //null// is used to terminated a directive. For example, after
|
||||
a //definition//, the bodies are indented, so a //null// can be
|
||||
used to reset the indentation.
|
||||
|
||||
The body supports markdown.
|
||||
|
||||
_code: Example @lang<text>
|
||||
|
||||
\_section: Hello World @<link-main>
|
||||
Body for section...
|
||||
|
||||
|
||||
\_subsection: Some Example @<link-secondary>
|
||||
Body for subsection...
|
||||
|
||||
|
||||
\_heading: Large Bold Text @<link-here>
|
||||
Body for heading...
|
||||
|
||||
|
||||
\_definition: Flatworm
|
||||
A phylum of relatively **simple** bilaterian, unsegmented,
|
||||
soft-bodied invertebrates.
|
||||
|
||||
|
||||
\_property: String.fromCharCode(code) => string
|
||||
Returns a string created from //code//, a sequence of
|
||||
UTF-16 code units.
|
||||
|
||||
|
||||
\_code: heading
|
||||
|
||||
// Some code goes here
|
||||
while(1);
|
||||
|
||||
|
||||
\_table: Table Footer
|
||||
|
||||
| **Name** | **Color** |
|
||||
| Apple | Red |
|
||||
| Banana | Yellow |
|
||||
| Grape | Purple |
|
||||
|
||||
|
||||
\_toc:
|
||||
some-file
|
||||
some-directory
|
||||
|
||||
|
||||
\_note: Title
|
||||
This is placed in a blue box.
|
||||
|
||||
|
||||
\_warning: Title
|
||||
This is placed in an orange box.
|
||||
|
||||
|
||||
\_null:
|
||||
This breaks out of a directive. For example, to end
|
||||
a ``_note:`` or ``_code:``.
|
||||
|
||||
|
||||
_subsection: Markdown @<flatworm-markdown>
|
||||
|
||||
The markdown is simple and does not have the flexibility of
|
||||
other dialects, but allows for **bold**, //italic//,
|
||||
__underlined__, ``monospaced``, super^^script^^ and ~~strike~~
|
||||
text, supporting [links](flatworm-markdown) and lists.
|
||||
|
||||
Lists are rendered as blocks of a body, so cannot be used within
|
||||
a title or within another list.
|
||||
|
||||
_code: @lang<text>
|
||||
|
||||
**bold text**
|
||||
|
||||
//italic text//
|
||||
|
||||
__underlined text__
|
||||
|
||||
``monospace code``
|
||||
|
||||
^^superscript text^^
|
||||
|
||||
~~strikeout text~~
|
||||
|
||||
- This is a list
|
||||
- With bullet points
|
||||
- With a total of three items
|
||||
|
||||
This is a [Link to Ethereum](https://ethereum.org) and this
|
||||
is an [Internal Link](some-link).
|
||||
|
||||
This is a self-titled link [[https://ethereumorg]] and this
|
||||
[[some-link]] will use the title from its directives value.
|
||||
|
||||
|
||||
_subsection: Code @<flatworm--code>
|
||||
|
||||
The code directive creates a monospace, contained block useful
|
||||
for displaying code samples.
|
||||
|
||||
_heading: JavaScript Evaluation @<flatworm--code-eval>
|
||||
|
||||
For JavaScript files, the file is transpiled and executed in a VM,
|
||||
allowiung output (or exceptions) of blocks to be included in the
|
||||
fragment output.
|
||||
|
||||
The entire **code fragment** source is included in an async IIFE,
|
||||
whick means ``await`` is allowed, and several special comment
|
||||
directives are allowed.
|
||||
|
||||
A ``/\/_hide:`` will include any following code directly into the
|
||||
output, but will not include it in the generated output for the fragment.
|
||||
|
||||
A ``/\/_log:`` will include the value of any following expression in the
|
||||
output, prefixed with a ``/\/ ``. Renderers will mark output in different
|
||||
style if possible.
|
||||
|
||||
A ``/\/_result:`` will begin a block, assigning the contents to ``_``. The
|
||||
block can be ended with a ``/\/_log:`` or ``/\/_null:``, if no value is given
|
||||
to log, then ``_`` is assumed. If an error occurs, generation fails.
|
||||
|
||||
A ``/\/_throws:`` will begin a block, which is expected to throw assigning
|
||||
the error to ``_``. The block can be ended with a ``/\/_log:`` or ``/\/_null:``,
|
||||
if no value is given to log, then ``_`` is assumed. If an error do not occur,
|
||||
generation fails.
|
||||
|
||||
_code: Code Evaluation Example @lang<text>
|
||||
|
||||
\_code: Result of Code Example @lang<javascript>
|
||||
|
||||
//_hide: const url = require("url");
|
||||
|
||||
//_result:
|
||||
url.parse("https://www.ricmoo.com/").protocol
|
||||
//_log:
|
||||
|
||||
//_throws:
|
||||
url.parse(45)
|
||||
//_log:
|
||||
|
||||
// You want to assign (doesn't emit eval) AND display the value
|
||||
const foo = 4 + 5;
|
||||
//_log: foo
|
||||
|
||||
|
||||
_code: Result of Code Example @lang<javascript>
|
||||
|
||||
//_hide: const url = require("url");
|
||||
|
||||
//_result:
|
||||
url.parse("https://www.ricmoo.com/").protocol
|
||||
//_log:
|
||||
|
||||
//_throws:
|
||||
url.parse(45)
|
||||
//_log:
|
||||
|
||||
// You want to assign (doesn't emit eval) AND display the value
|
||||
const foo = 4 + 5;
|
||||
//_log: foo
|
||||
|
||||
|
||||
_heading: Languages
|
||||
|
||||
The language can be specified using the [@lang extension](flatworm--ext-lang).
|
||||
|
||||
_table:
|
||||
|
||||
| **Language** | **Notes** |
|
||||
| javascript | Syntax highlights and [evaluates](flatworm--code-eval) the JavaScript |
|
||||
| script | Same as ``javascript``, but does not evaluate the results |
|
||||
| shell | Shell scripts or command-line |
|
||||
| text | Plain text with no syntax highlighting |
|
||||
|
||||
_subsection: Tables @<flatworm--table>
|
||||
|
||||
The table directive consumes the entire body up until the next
|
||||
directive. To terminate a table early to begin a text block,
|
||||
use a **_null:** directive.
|
||||
|
||||
Each line of the body should be [Row Data](flatworm--table-row) or a
|
||||
[Variable Declaration](flatworm--table-variable) (or continuation of
|
||||
a //Variable Declaration//). Blank lines are ignored.
|
||||
|
||||
_heading: Row Data @<flatworm--table-row>
|
||||
|
||||
Each **Row Data** line must begin and end with a **``"|"``**, with each
|
||||
gap representing the cell data, [alignment](flatworm--table-alignment)
|
||||
with optional [column and row spanning](flatworm--table-spanning).
|
||||
|
||||
|
||||
_heading: Alignment @<flatworm--table-alignment>
|
||||
|
||||
The alignment for a cell is determined by the whitespace surrounding the
|
||||
cell data.
|
||||
|
||||
_table: Alignment Conditions (higher precedence listed first)
|
||||
|
||||
| **Alignment** | **Whitespace** |
|
||||
| //Left// | 1 or fewer spaces before the content |
|
||||
| //Right// | 1 or fewer spaces after the content |
|
||||
| //Center// | 2 or more space **both** before and after the content |
|
||||
|
||||
|
||||
_code: Alignment Example @lang<text>
|
||||
|
||||
\_table: Result of Alignment Example @style<compact>
|
||||
|
||||
| center |
|
||||
|
||||
| left |
|
||||
|left |
|
||||
|
||||
| right |
|
||||
| right|
|
||||
|
||||
_table: Result of Alignment Example @style<compact>
|
||||
|
||||
| center |
|
||||
|
||||
| left |
|
||||
|left |
|
||||
|
||||
| right |
|
||||
| right|
|
||||
|
||||
|
||||
_heading: Row and Column Spanning @<flatworm--table-spanning>
|
||||
|
||||
A column may end its content with any number of **``"<"``** which indicates
|
||||
how many //additional// columns to extend into.
|
||||
|
||||
If the cell content contains only a **``"^"``**, then the row above is
|
||||
extended into this cell (into the same number of columns).
|
||||
|
||||
_code: Cell Spanning Example @lang<text>
|
||||
|
||||
\_table: Result of Cell Spanning Example @style<compact>
|
||||
|
||||
| (1x1) | (1x2) <| (2x1) |
|
||||
| (2x2) <| (2x1) | ^ |
|
||||
| ^ | ^ | (1x1) |
|
||||
|
||||
_table: Result of Cell Spanning Example @style<compact>
|
||||
|
||||
| (1x1) | (1x2) <| (2x1) |
|
||||
| (2x2) <| (2x1) | ^ |
|
||||
| ^ | ^ | (1x1) |
|
||||
|
||||
|
||||
_heading: Styles @<flatworm--table-style>
|
||||
|
||||
The [@style extension](flatworm--ext-style) for a table can be used to control its
|
||||
appearance.
|
||||
|
||||
_table:
|
||||
|
||||
| **Name** | **Width** | **Columns** |
|
||||
| //minimal// | minimum size | best fit |
|
||||
| //compact// | 40% | evenly spaced |
|
||||
| //wide// | 67% | evenly spaced |
|
||||
| //full// | 100% | evenly spaced |
|
||||
|
||||
|
||||
_heading: Variables @<flatworm--table-variable>
|
||||
|
||||
Often the layout of a table is easier to express and maintain without
|
||||
uneven or changing content within it. So the content can be defined
|
||||
separately within a table directive using **variables**. A variable
|
||||
name must begin with a letter and must only contain letters and numbers.
|
||||
|
||||
Variables are also useful when content is repeated throughout a table.
|
||||
|
||||
A variable is declared by starting a line with ``"$NAME:"``, which
|
||||
consumes all lines until the next variable declaration or until the
|
||||
next table row line.
|
||||
|
||||
A variable name must start with a letter and may consist of letters and
|
||||
numbers. (i.e. ``/[a-z][a-z0-9]*/i``)
|
||||
|
||||
_code: Variables Example @lang<text>
|
||||
|
||||
\_table: Result of Variables Example
|
||||
|
||||
$Yes: This option is supported.
|
||||
$No: This option is **not** supported
|
||||
$bottom: This just represents an example of
|
||||
what is possible. Notice that variable
|
||||
content can span multiple lines.
|
||||
|
||||
| **Feature** | **Supported** |
|
||||
| Dancing Monkey | $Yes |
|
||||
| Singing Turtle | $No |
|
||||
| Newt Hair | $Yes |
|
||||
| $bottom <|
|
||||
|
||||
_table: Result of Variables Example
|
||||
|
||||
$Yes: This option is supported.
|
||||
$No: This option is **not** supported.
|
||||
$bottom: This just represents an example of
|
||||
what is possible. Notice that variable
|
||||
content can span multiple lines.
|
||||
|
||||
| **Feature** | **Supported** |
|
||||
| Dancing Monkey | $Yes |
|
||||
| Singing Turtle | $No |
|
||||
| Newt Hair | $Yes |
|
||||
| $bottom <|
|
||||
|
||||
|
||||
_subsection: Configuration @<flatworm-config>
|
||||
|
||||
Configuration is optional (but highly recommended) and may be either
|
||||
a simple JSON file (config.json) or a JS file (config.js) placed in
|
||||
the top of the source folder.
|
||||
|
||||
TODO: example JSON and example JS
|
||||
|
||||
|
||||
_subsection: Extensions @<flatworm-extensions>
|
||||
|
||||
_heading: @inherit\< //markdown// > @<flatworm--ext-inherit>
|
||||
|
||||
Adds an inherits description to a directive. The //markdown// may contain links.
|
||||
|
||||
|
||||
_heading: @lang\< //text// > @<flatworm--ext-lang>
|
||||
|
||||
Set the language a [code directive](flatworm--code) should be
|
||||
syntax-highlighted for. If "javascript", the code will be evaluated.
|
||||
|
||||
|
||||
_heading: @nav\< //text// > @<flatworm--ext-nav>
|
||||
|
||||
Sets the name in the breadcrumbs when not the current node.
|
||||
|
||||
|
||||
_heading: @note\<// markdown// > @<flatworm--ext-note>
|
||||
|
||||
Adds a note to a directive. The //markdown// may contain links. If the directive
|
||||
already has an @INHERIT extension, that will be used instead and the @NOTE will
|
||||
be ignored.
|
||||
|
||||
|
||||
_heading: @src\< //key// > @<flatworm--ext-src>
|
||||
|
||||
Calls the configuration ``getSourceUrl(key, VALUE)`` to get a URL which
|
||||
will be linked to by a link next to the //directive//.
|
||||
|
||||
This extended directive function requires an advanced ``config.js`` [[flatworm-config]]
|
||||
file since it requires a JavaScript function.
|
||||
|
||||
|
||||
_heading: @style\< //text// > @<flatworm--ext-style>
|
||||
|
||||
The [Table Style](flatworm--table-style) to use for a table directive.
|
||||
113
docs.wrm/generate-redirects.js
Normal file
113
docs.wrm/generate-redirects.js
Normal file
@ -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);
|
||||
});
|
||||
|
||||
Some files were not shown because too many files have changed in this diff Show More
Loading…
Reference in New Issue
Block a user