Skip to content

Commit

Permalink
Merge branch 'main' into nightlyCheck
Browse files Browse the repository at this point in the history
  • Loading branch information
joaniefromtheblock authored Sep 26, 2024
2 parents 8cb4e3f + a1f32ea commit 066ac8f
Show file tree
Hide file tree
Showing 834 changed files with 14,323 additions and 6,233 deletions.
28 changes: 26 additions & 2 deletions .github/CODEOWNERS
Validating CODEOWNERS rules …
Original file line number Diff line number Diff line change
@@ -1,3 +1,27 @@
* @MetaMask/tech-writers
# This is a codeowners file. The last matching pattern takes precedence,
# so the listed codeowners apply only if there is no later match.

# Default owner for all other files
* @MetaMask/activation

# Docusaurus configuration
docusaurus.config.js @MetaMask/activation @MetaMask/tech-writers

# Vercel configuration
vercel.json @MetaMask/activation @MetaMask/tech-writers

# Sidebar files
*-sidebar.js @MetaMask/activation @MetaMask/tech-writers

# All other Markdown files
*.md @MetaMask/tech-writers
*.mdx @MetaMask/tech-writers

# Services documentation
/services/ @MetaMask/tech-writers

# Snaps documentation
/snaps/ @MetaMask/tech-writers @MetaMask/snaps
/wallet/ @MetaMask/tech-writers @MetaMask/dev-ex

# Wallet and SDK documentation
/wallet/ @MetaMask/tech-writers @MetaMask/wallet-api-platform-engineers @MetaMask/sdk-devs
168 changes: 127 additions & 41 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,8 +11,10 @@ guide in some places.
- [Preview locally](#preview-locally)
- [Style guide](#style-guide)
- [Add images](#add-images)
- [Format Markdown and MDX](#format-markdown-and-mdx)
- [Live code blocks](#live-code-blocks)
- [Update the interactive API reference](#update-the-interactive-api-reference)
- [Update `MetaMask/api-specs`](#update-metamaskapi-specs)
- [Update `ethereum/execution-apis`](#update-ethereumexecution-apis)
- [Test analytics](#test-analytics)

## Contribution workflow

Expand All @@ -35,7 +37,7 @@ To contribute changes:
this repository to your computer and navigate into it.

```bash
git clone https://github.com/MetaMask/metamask-docs.git
git clone git@github.com:MetaMask/metamask-docs.git
cd metamask-docs
```

Expand All @@ -46,9 +48,9 @@ To contribute changes:
> to be able to pull from and push to the original repository.
>
> ```bash
> git clone https://github.com/<YOUR-USERNAME>/metamask-docs.git
> git clone git@github.com:<YOUR-USERNAME>/metamask-docs.git
> cd metamask-docs
> git remote add upstream https://github.com/MetaMask/metamask-docs.git
> git remote add upstream git@github.com:MetaMask/metamask-docs.git
> ```
3. [Create and checkout a topic branch](https://git-scm.com/book/en/v2/Git-Branching-Basic-Branching-and-Merging),
Expand All @@ -69,12 +71,16 @@ To contribute changes:
> **Notes:**
>
> - All documentation content is located in the `wallet` and `snaps` directories.
> - If you add a new documentation page, make sure to edit `wallet-sidebar.js` or
> `snaps-sidebar.js` to add the page to the
> - All documentation content is located in the `wallet`, `snaps`, `services`, and
> `developer-tools` directories.
> - If you add a new documentation page, edit `wallet-sidebar.js`, `snaps-sidebar.js`,
> `services-sidebar.js`, or `dashboard-sidebar.js` to add the page to the
> [sidebar](https://docs-template.consensys.net/contribute/configure-docusaurus#sidebar).
> - If you delete, rename, or move a documentation file, make sure to add a
> [redirect](https://docs-template.consensys.net/contribute/configure-docusaurus#redirects).
> - If you delete, rename, or move a documentation file, add a
> [redirect](https://vercel.com/docs/edge-network/redirects#configuration-redirects).
> - See additional instructions for [updating the interactive API reference](#update-the-interactive-api-reference).
> - If the PR contains a major change to the documentation content, add an entry to the top of
> the ["What's new?"](docs/whats-new.md) page.
5. [Preview your changes locally](https://docs-template.consensys.net/contribute/preview) to check
that the changes render correctly.
Expand Down Expand Up @@ -114,49 +120,129 @@ Refer to the [Consensys documentation style guide](https://docs-template.consens
## Add images
All images are located in the `wallet/assets` and `snaps/assets` directories.
All images are located in the `wallet/assets`, `snaps/assets`, `services/images`, and
`developer-tools/images` directories.
When adding a new image, such as a screenshot or diagram, make sure the image has a white or
`#1b1b1d` color background in order for it to be compatible with the site's light and dark modes.
Additionally, follow the [Consensys guidelines on adding images](https://docs-template.consensys.net/contribute/add-images).
## Format Markdown and MDX
## Update the interactive API reference
The documentation is built using [Docusaurus](https://docusaurus.io/), which is powered by
[MDX](https://mdxjs.com/), an extension to [Markdown](https://www.markdownguide.org/) that allows
you to use [React JSX](https://www.w3schools.com/react/react_jsx.asp) in your Markdown content.
The [Wallet JSON-RPC API reference](https://docs.metamask.io/wallet/reference/json-rpc-api/) uses the
[`docusaurus-openrpc`](https://github.com/MetaMask/docusaurus-openrpc) plugin to import OpenRPC
specifications from [`MetaMask/api-specs`](https://github.com/MetaMask/api-specs) (MetaMask-specific
methods) and [`ethereum/execution-apis`](https://github.com/ethereum/execution-apis) (standard
Ethereum methods).
The site renders documentation for each method based on the specification, and displays an
interactive module to test the methods in your browser.
Follow the [Consensys guidelines on formatting Markdown](https://docs-template.consensys.net/contribute/format-markdown).
The MetaMask docs also use a plugin to implement [live code blocks](#live-code-blocks).
### Update `MetaMask/api-specs`
### Live code blocks
To update documentation for MetaMask-specific JSON-RPC API methods:
The [`remark-codesandbox`](https://github.com/kevin940726/remark-codesandbox/) plugin allows you to
define a code block to be loaded live in a CodeSandbox iframe.
This enhances the documentation by keeping the code blocks versioned and in the codebase, while
using CodeSandbox to showcase any example with any dependency.
1. Fork [`MetaMask/api-specs`](https://github.com/MetaMask/api-specs), clone the forked repository
to your computer, and navigate into it:
Define a live code block by adding a `codesandbox` key to the code block.
For example:
````jsx
```javascript codesandbox=vanilla
// JavaScript live code block
```
````
`remark-codesandbox` allows for simple code blocks where the content of the block replaces the
CodeSandbox entry point, and more complex code blocks that can be loaded directly from the
filesystem.
See the
[`remark-codesandbox` documentation](https://github.com/kevin940726/remark-codesandbox/#documentation)
for more information.
## Analytics
```bash
git clone [email protected]:<YOUR-USERNAME>/api-specs.git
cd api-specs
```
2. Follow the repository's [`README.md`](https://github.com/MetaMask/api-specs/blob/main/README.md)
instructions to edit the OpenRPC specification and generate the output file, `openrpc.json`.
3. To test the API updates in the MetaMask doc site's interactive reference, make the following
temporary changes on a local branch of the doc site, `metamask-docs`:
1. Copy and paste the output file `openrpc.json` into the root directory of `metamask-docs`.
2. In `docusaurus.config.js`, update the following line to point to your local output file:
```diff
openrpcDocument:
- "https://metamask.github.io/api-specs/0.10.5/openrpc.json",
+ "./openrpc.json",
```
3. Preview the doc site locally, navigate to the API reference, and view your updates.
4. Add and commit your changes to `api-specs`, and create a PR.
5. Once your PR is approved and merged, the following must happen to publish the changes to the
MetaMask doc site:
1. A new version of `api-specs` must be released by a user with write access to the repository.
To release, go to the [Create Release Pull Request](https://github.com/MetaMask/api-specs/actions/workflows/create-release-pr.yml)
action, select **Run workflow**, and enter a specific version to bump to in the last text box
(for example, `0.10.6`). This creates a PR releasing a version of `api-specs`.
2. Once the release PR is merged, the [Publish Release](https://github.com/MetaMask/api-specs/actions/workflows/publish-release.yml)
action must be approved by an npm publisher.
You can request an approval in the **#metamask-dev** Slack channel tagging
**@metamask-npm-publishers**.
For example:
> @metamask-npm-publishers `@metamask/[email protected]` is awaiting deployment :rocketship:
https://github.com/MetaMask/api-specs/actions/runs/10615788573
3. Once the release is published on npm, `docusaurus.config.js` in `metamask-docs` must be
updated with the new `api-specs` version to publish.
For example:
```diff
openrpcDocument:
- "https://metamask.github.io/api-specs/0.10.5/openrpc.json",
+ "https://metamask.github.io/api-specs/0.10.6/openrpc.json",
```
### Update `ethereum/execution-apis`
To update documentation for standard Ethereum JSON-RPC API methods:
1. Fork [`ethereum/execution-apis`](https://github.com/ethereum/execution-apis), clone the forked
repository to your computer, and navigate into it:
The [`docusaurus-plugin-segment`](https://github.com/xer0x/docusaurus-plugin-segment) plugin enables simple usage analytics to inform documentation improvements that may be needed.
```bash
git clone [email protected]:<YOUR-USERNAME>/execution-apis.git
cd execution-apis
```
If you need to test analytics events in your local development environment be sure to export the appropriate key for the environment you are testing against before building and running the project:
2. Follow the repository's [`README.md`](https://github.com/ethereum/execution-apis/blob/main/README.md)
instructions to edit the OpenRPC specification and generate the output file, `openrpc.json`.
3. To test the API updates in the MetaMask doc site's interactive reference, make the following
temporary changes on a local branch of the doc site, `metamask-docs`:
1. Copy and paste the output file `openrpc.json` into the root directory of `metamask-docs`.
2. In `docusaurus.config.js`, update the following line to point to your local output file:
```diff
openrpcDocument:
- "https://metamask.github.io/api-specs/0.10.5/openrpc.json",
+ "./openrpc.json",
```
3. Preview the doc site locally, navigate to the API reference, and view your updates.
4. Add and commit your changes to `execution-apis`, and create a PR.
5. Once your PR is approved and merged, the following must happen to publish the changes to the
MetaMask doc site:
1. `api-specs` must import the updated Ethereum API specification.
Go to the [commit history](https://github.com/ethereum/execution-apis/commits/assembled-spec/)
of the `assembled-spec` branch of `execution-apis`.
Copy the full commit hash of the latest commit titled "assemble openrpc.json."
Update the following line in `merge-openrpc.js` of `api-specs` with the updated commit hash,
and create a PR:
```diff
const getFilteredExecutionAPIs = () => {
- return fetch("https://raw.githubusercontent.com/ethereum/execution-apis/ac19b518a2596221cd7cd6421ee3dc654d7ff3b7/refs-openrpc.json")
+ return fetch("https://raw.githubusercontent.com/ethereum/execution-apis/f75d4cc8eeb5d1952bd69f901954686b74c34c9b/refs-openrpc.json")
```
2. Once the change to `merge-openrpc.js` is merged, Step 5 in
[Update `MetaMask/api-specs`](#update-metamaskapi-specs) must be completed to publish the
changes to the MetaMask doc site.
## Test analytics
The [`docusaurus-plugin-segment`](https://github.com/xer0x/docusaurus-plugin-segment) plugin enables
simple usage analytics to inform documentation improvements.
If you need to test analytics events in your local development environment, export the appropriate
key for the environment you are testing against before building and running the project:
```bash
export SEGMENT_ANALYTICS_KEY="<your key>"
Expand Down
31 changes: 31 additions & 0 deletions developer-tools/dashboard/how-to/credit-usage.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
---
description: View your Infura credit usage stats.
---

# View credit usage

:::info

The [credit pricing model](../api/learn/pricing/) replaces request-based billing for free-tier (Core)
customers. Customers on Developer and Team plans will be transitioned to the credit model on
September 30, 2024.

**Existing customers on Growth and Custom plans will remain on request-based billing**.
:::

You can view your daily credit usage in relation to your daily credit quota limit. Daily credit usage
counts are reset everyday at 00:00 UTC for all customers.

Select **View Usage** from the **Daily Credit Usage** section on the Infura dashboard, or select
the **Usage** tab from the **Settings** > **Billing** dropdown.

View your usage for the previous 24 hours, 7 days, or 30 days by methods used, networks, or API key.

<div class="left-align-container">
<div class="img-large">
<img
src={require('../../images/credit-usage.png').default}
/>
</div>
</div>

27 changes: 19 additions & 8 deletions developer-tools/dashboard/how-to/secure-an-api/set-rate-limits.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,21 +4,32 @@ description: Set rate limits to control access to the API key.

# Rate limits

Set rate limits to control access to the API key and to limit costs in case of a leaked API key. Set rate limiting in the API key's
**Settings** tab **REQUESTS** section.
:::info

The credit pricing model replaces the request-based billing for free-tier (Core) customers.
**Existing paid customers will not be immediately affected and will continue to limit the number of requests per second**.

:::

Set credit rate limits to control access to the API key and to limit costs in case of a leaked API key.
Set rate limiting in the API key's **Settings** tab **Key Credit Limits** section.

<div class="left-align-container">
<div class="img-medium">
<div class="img-large">
<img
src={require("../../../images/rate-limiting-settings.png").default}
src={require('../../../images/rate-limiting-settings.png').default}
/>
</div>
</div>

- **PER SECOND REQUESTS RATE-LIMITING** restricts requests per second for the API key. Set the maximum number of requests per second in decimals, e.g. 1.2. Whenever the rate of requests exceeds this value, requests are rejected. When the rate of requests drops below the limit again, requests are accepted again.
- **PER SECOND CREDIT RATE-LIMITING** restricts credits per second (throughput) for the API key. Set
the maximum number of credits per second in whole numbers. When credits per second rate exceeds
this value, requests are rejected. When the credit rate drops below the limit, requests
are accepted again.

Decimal value 0.0 means default limits are applied.
The value `0` means default limits are applied.

- **PER DAY TOTAL REQUESTS** restricts total daily requests for the API key. Set a limit on number of requests per day in integers, e.g. 20000. Integer value 0 means default limits are applied.
- **PER DAY TOTAL CREDITS** restricts total daily credit usage for the API key. Set a limit on number of
credits per day in integers, e.g. 20000. The value `0` means default limits are applied.

When the number of requests reach this limit, all requests will be rejected until the next day (00:00 UTC).
When the number of used credits reach this limit, all requests will be rejected until the next day (00:00 UTC).
Original file line number Diff line number Diff line change
Expand Up @@ -65,7 +65,7 @@ To allow a specific Ethereum address, click **ADD** and input it into the **CONT
Test with a method from the list.

```bash
curl https://mainnet.infura.io/v3/<PROJECT_ID> \
curl https://mainnet.infura.io/v3/<YOUR-API-KEY> \
-H 'Content-Type: application/json' \
-X POST \
-d '{"jsonrpc": "2.0", "method": "eth_getBalance", "params": ["0xfe05a3e72235c9f92fd9f2282f41a8154d6d342b", "latest"], "id": 1}'
Expand Down Expand Up @@ -116,7 +116,7 @@ the **USER AGENTS** allowlist.
Test with a simple call from a desktop terminal.

```bash
curl https://mainnet.infura.io/v3/<PROJECT_ID> \
curl https://mainnet.infura.io/v3/<YOUR-API-KEY> \
-X POST \
-H "Content-Type: application/json" \
-d '{"jsonrpc": "2.0", "method": "eth_accounts", "params": [], "id": 1}'
Expand Down Expand Up @@ -214,7 +214,7 @@ This feature provides the following benefits:

## Best practices

- Ensure the `API-KEY-SECRET` is not exposed publicly, and include it in your requests.
- Ensure the API key secret is not exposed publicly, and include it in your requests.
- Use all allowlist options wherever possible.
- Create a new API key for each application. This allows you to allowlist the contract addresses relevant to that application.
- Avoid committing your project keys to a repo by using a package like [dotenv](https://www.npmjs.com/package/dotenv).
Expand Down
Binary file added developer-tools/images/credit-usage.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified developer-tools/images/rate-limiting-settings.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
19 changes: 19 additions & 0 deletions docs/whats-new.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,11 +9,30 @@ The latest major MetaMask documentation updates are listed by the month they wer
For a comprehensive list of recent product changes, visit the "Release Notes" section at the bottom
of the [MetaMask developer page](https://metamask.io/developer/).

## September 2024

- Documented new [Snaps custom UI JSX components](/snaps/features/custom-ui) for Flask
version 12.4, and removed documentation for deprecated function-based library.
([#1540](https://github.com/MetaMask/metamask-docs/pull/1540))
- Documented [Snaps user-defined components](/snaps/features/custom-ui/user-defined-components).
([#1557](https://github.com/MetaMask/metamask-docs/pull/1557))
- Updated [Android SDK documentation](/wallet/how-to/use-sdk/mobile/android) with convenience
methods and examples using coroutines.
([#1546](https://github.com/MetaMask/metamask-docs/pull/1546))
- Documented [Infura's credit pricing model](/services/get-started/pricing).
([#1530](https://github.com/MetaMask/metamask-docs/pull/1530))
- Added tutorial for [authenticating with JWT](/services/tutorials/ethereum/authenticate-with-jwt).
([#1528](https://github.com/MetaMask/metamask-docs/pull/1528))
- Documented [opBNB](/services/reference/opbnb) support.
([#1528](https://github.com/MetaMask/metamask-docs/pull/1528))

## August 2024

- *The documentation site underwent a temporary freeze in August.*
- Updated [Starknet documentation](/services/reference/starknet) with API methods supported by new partners, Bware and Chainstack. ([#1483](https://github.com/MetaMask/metamask-docs/pull/1483))

## July 2024

- Documented [Binance Smart Chain](/services/reference/bnb-smart-chain/) support. ([#1458](https://github.com/MetaMask/metamask-docs/pull/1458))
- Documented [Celo WebSocket](/services/reference/celo/) support. ([#1446](https://github.com/MetaMask/metamask-docs/pull/1446))
- Documented [ZKsync Era WebSocket](/services/reference/zksync) support. ([#1438](https://github.com/MetaMask/metamask-docs/pull/1438))
Expand Down
Loading

0 comments on commit 066ac8f

Please sign in to comment.