From 3c6d8e20d87616af297bd8a9c45ddb9ae8540830 Mon Sep 17 00:00:00 2001 From: Piotr Roslaniec Date: Thu, 4 Jan 2024 17:28:54 +0100 Subject: [PATCH] update snap docs --- docs/_config.yml | 26 +++++- docs/assets/images/aleph-zero-logo.png | Bin 0 -> 3987 bytes docs/assets/images/favicon.svg | 1 + docs/index.md | 35 ++++---- docs/integration.md | 97 +++++++++++++++++++++ docs/security.md | 24 ++++++ docs/snap.md | 113 +++++++++++++++++++++++++ 7 files changed, 272 insertions(+), 24 deletions(-) create mode 100644 docs/assets/images/aleph-zero-logo.png create mode 100644 docs/assets/images/favicon.svg create mode 100644 docs/integration.md create mode 100644 docs/security.md create mode 100644 docs/snap.md diff --git a/docs/_config.yml b/docs/_config.yml index faa6eaa..1df26f2 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -1,8 +1,26 @@ -title: Just the Docs Template -description: A starter template for a Jeykll site using the Just the Docs theme! +title: Aleph Zero Wallet Documentation +description: Aleph Zero Wallet is a MetaMask snap for Aleph Zero blockchain. theme: just-the-docs -url: https://just-the-docs.github.io +url: https://test.azero.dev aux_links: - Template Repository: https://github.com/just-the-docs/just-the-docs-template + Source Repository: https://github.com/bide-dev/azero-wallet + +logo: "/assets/images/aleph-zero-logo.png" +favicon_ico: "/assets/images/favicon.svg" + +mermaid: + # Version of mermaid library + # Pick an available version from https://cdn.jsdelivr.net/npm/mermaid/ + version: "9.1.3" + +heading_anchors: true + +# Footer "Edit this page on GitHub" link text +gh_edit_link: true +gh_edit_link_text: "Edit this page on GitHub." +gh_edit_repository: "https://github.com/bide-dev/azero-wallet" +gh_edit_branch: "main" # the branch that your docs is served from +gh_edit_source: docs +gh_edit_view_mode: "edit" diff --git a/docs/assets/images/aleph-zero-logo.png b/docs/assets/images/aleph-zero-logo.png new file mode 100644 index 0000000000000000000000000000000000000000..c4e998c32cf1a97ae83f180f7144f4a6ba2e46b2 GIT binary patch literal 3987 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 tN}8m$JQL^_^{={X1D|yd{6 \ No newline at end of file diff --git a/docs/index.md b/docs/index.md index ca0c545..9751c83 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,35 +1,30 @@ --- title: Home layout: home +nav_order: 0 --- -This is a *bare-minimum* template to create a Jekyll site that uses the [Just the Docs] theme. You can easily set the created site to be published on [GitHub Pages] – the [README] file explains how to do that, along with other details. +# Azero Wallet snap -If [Jekyll] is installed on your computer, you can also build and preview the created site *locally*. This lets you test changes before committing them, and avoids waiting for GitHub Pages.[^1] And you will be able to deploy your local build to a different platform than GitHub Pages. +This documentation explains how to use Aleph Zero Wallet snap, or `azero-wallet`. In order to use the snap on the Aleph +Zero network, visit [azero.dev][azero-dev]. -More specifically, the created site: +To understand how the snap works and it's limitations, visit the [snap documentation](/snap). -- uses a gem-based approach, i.e. uses a `Gemfile` and loads the `just-the-docs` gem -- uses the [GitHub Pages / Actions workflow] to build and publish the site on GitHub Pages +If you're interested in integrating the snap into your web app, see the [integration documentation](/integration). -Other than that, you're free to customize sites that you create with this template, however you like. You can easily change the versions of `just-the-docs` and Jekyll it uses, as well as adding further plugins. +## Learn more -[Browse our documentation][Just the Docs] to learn more about how to use this theme. +- You can learn more about Aleph Zero [here][Aleph Zero docs]. +- You can see a live demo of the snap [here][live demo]. +- To learn more about MetaMask snaps, see the [MetaMask snap documentation][MetaMask snap documentations]. -To get started with creating a site, simply: - -1. click "[use this template]" to create a GitHub repository -2. go to Settings > Pages > Build and deployment > Source, and select GitHub Actions +---- -If you want to maintain your docs in the `docs` directory of an existing project repo, see [Hosting your docs from an existing project repo](https://github.com/just-the-docs/just-the-docs-template/blob/main/README.md#hosting-your-docs-from-an-existing-project-repo) in the template README. +[azero-dev]: https://azero.dev ----- +[Aleph Zero docs]: https://docs.alephzero.org/aleph-zero/ -[^1]: [It can take up to 10 minutes for changes to your site to publish after you push the changes to GitHub](https://docs.github.com/en/pages/setting-up-a-github-pages-site-with-jekyll/creating-a-github-pages-site-with-jekyll#creating-your-site). +[live demo]: https://azero-snap.netlify.app/ -[Just the Docs]: https://just-the-docs.github.io/just-the-docs/ -[GitHub Pages]: https://docs.github.com/en/pages -[README]: https://github.com/just-the-docs/just-the-docs-template/blob/main/README.md -[Jekyll]: https://jekyllrb.com -[GitHub Pages / Actions workflow]: https://github.blog/changelog/2022-07-27-github-pages-custom-github-actions-workflows-beta/ -[use this template]: https://github.com/just-the-docs/just-the-docs-template/generate +[MetaMask snap documentations]: https://docs.metamask.io/guide/snap.html diff --git a/docs/integration.md b/docs/integration.md new file mode 100644 index 0000000..e0791c5 --- /dev/null +++ b/docs/integration.md @@ -0,0 +1,97 @@ +--- +layout: default +title: Integration Guide +nav_order: 4 +--- + +# Integration guide + +This document outlines the step-by-step process of integrating `azero-wallet` into a web app using React. + +Aleph Zero Snap consists of three packages: + +- [azero-wallet-snap]: The core snap functionality. +- [azero-wallet-adapter]: A wrapper to facilitate interaction with the snap API. +- [azero-wallet-types]: TypeScript types shared by the snap and snap API. + +As a developer who wants to integrate the snap into a web app, you will primarily be interested +in `azero-wallet-adapter` and `azero-wallet-types` packages. + +## Integration using `azero-wallet-adapter` + +While direct integration with `azero-wallet` is possible, using [azero-wallet-adapter] is recommended for ease and +efficiency. This package contains the API methods exposed by the snap. + +### Installation + +```bash +npm install azero-wallet-adapter +``` + +### Usage + +Below we outline the usage of the `azero-wallet-adapter` package. For a complete list of methods and their parameters, +refer to the [API documentation](/snap). + +First, we implement the `MetaMaskSnapSigner` class which we'll use to sign transactions in our app. `MetaMaskSnapSigner` +will connect to (and install, if needed) the snap and sign transactions using the snap API. + +```typescript +import {signSignerPayload} from 'azero-wallet-adapter'; +import {connectSnap} from './snap'; + +export class MetaMaskSnapSigner { + public async signPayload(payload: SignerPayloadJSON): Promise { + // Connect to snap + await connectSnap(); + + // Sign payload + const signingResult = await signSignerPayload({payload}); + + // Did that work? + if (!signingResult.success) { + throw new Error(signingResult.error); + } + + return { + signature: signingResult.data.signature + }; + } +} +``` + +For the `signPayload` method to work, the snap connection must be established. Below is the `connectSnap` function which +connects to the snap and sets up the RPC URL. Here, we use the public testnet RPC URL. + +```typescript +import * as snap from 'azero-wallet-adapter'; + +export const connectSnap = async () => { + // Actually connect to snap + await snap.connect(); + + // Set RPC URL - if we skip this part, we will connect to the default RPC URL at https://rpc.azero.dev/ + await snap.setRpcUrl({rpcUrl: 'https://rpc.test.azero.dev/'}); + + // Get account + const accountResult = await snap.getAccount(); + + // Did that work? + if (!accountResult.success) { + throw accountResult.error; + } + const {address} = accountResult.data; + console.log(`Connected to snap with account ${address}`); +}; +``` + +In this function, `snap.connect()` is used to establish a connection to the snap. The RPC URL is then set +using `snap.setRpcUrl()`. Lastly, the account is fetched using `snap.getAccount()` and printed. + +We see that snap API methods return a `Result` object. This object contains a `success` boolean and either an `error` +or `data` object. The `data` object contains the result of the API call. The `error` object contains the error message +if the API call failed. + +--- + +[azero-wallet-adapter]: https://www.npmjs.com/package/azero-wallet-adapter diff --git a/docs/security.md b/docs/security.md new file mode 100644 index 0000000..189d721 --- /dev/null +++ b/docs/security.md @@ -0,0 +1,24 @@ +--- +layout: default +title: Security & Support +nav_order: 5 +--- + +# Security + +## Audit + +Aleph Zero Wallet snap has been audited by [Sayfer]. The audit report is available [here][audit report]. + +## Support and Feedback + +If you have any questions or feedback, please reach out to us at [support@bide.dev][support] + + +--- + +[Sayfer]: https://sayfer.io/audits/metamask-snap-audit-report-for-alephzero/ + +[audit report]: https://sayfer.io/audits/metamask-snap-audit-report-for-alephzero/ + +[support]: mailto:support@bide.dev. diff --git a/docs/snap.md b/docs/snap.md new file mode 100644 index 0000000..d0a0ce1 --- /dev/null +++ b/docs/snap.md @@ -0,0 +1,113 @@ +--- +layout: default +title: Snap API docs +nav_order: 3 +--- + +# Snap API Docs + +This document explains how the workings of the snap and it's limitations. + +## Account derivation + +The snap implements a single Aleph Zero-compatible account. This account is derived automatically and deterministically +upon the snap startup. This implies a consistent account for a given MetaMask wallet. The deterministic derivation +eliminates the need for backing up the account seed phrase, just the MetaMask seed phrase is required. + +### Limitations + +- It's currently not possible to derive multiple accounts from a single MetaMask wallet. +- Exporting the account from the snap is not possible. +- Accounts may only be viewed using snap API calls, not from MetaMask interface. + +## Snap methods + +The snap avails the following methods: + +### 1. Get Account Address + +The `getAccount` method extracts the account address without needing any additional parameters. + +```typescript +import {getAccount, isSuccess} from 'azero-wallet-adapter'; + +const result: Result = await getAccount(); +if (isSuccess(result)) { + console.log(result.data); // {address: "account address"} +} else { + console.error(result.error); +} +``` + +### 2. Sign and Send Payload + +This method sends and signs a payload via the `SignAndSendTransactionRequestParams` type parameters. + +```typescript +import {signAndSendExtrinsicTransactionPayload, SignAndSendTransactionRequestParams, isSuccess} + from 'azero-wallet-adapter'; + +const txParams: SignAndSendTransactionRequestParams = {transaction: /*...*/, payload: /*...*/} + +signAndSendExtrinsicTransactionPayload(txParams).then(result => { + if (isSuccess(result)) { + // handle result transaction + } else { + // handle error + } +}); +``` + +### 3. Sign Payload + +This method signs a payload without sending it. It uses the `SignSignerPayloadRequestParams`. + +```typescript +import {signSignerPayload, SignSignerPayloadRequestParams, isSuccess} from 'azero-wallet-adapter'; + +const signParams: SignSignerPayloadRequestParams = {payload: /*...*/}; + +signSignerPayload(signParams).then(result => { + if (isSuccess(result)) { + // handle result transaction + } else { + // handle error + } +}); +``` + +### 4. Transfer Native Assets + +This function transfers native assets using the `TransferNativeAssetRequestParams` type for its parameters. + +```typescript +import {transferNativeAsset, TransferNativeAssetRequestParams, isSuccess} from 'azero-wallet-adapter'; + +const transferParams: TransferNativeAssetRequestParams = {recipient: /*...*/, amount: /*...*/}; + +transferNativeAsset(transferParams).then(result => { + if (isSuccess(result)) { + // handle result transaction + } else { + // handle error + } +}); +``` + +### 5. Set the RPC URL + +To configure the RPC URL, use the `setRpcUrl` with `SetRpcUrlRequestParams` as its parameters. + +```typescript +import {setRpcUrl, SetRpcUrlRequestParams, isSuccess,} from 'azero-wallet-adapter'; + +const rpcParams: SetRpcUrlRequestParams = {rpcUrl: 'http://my-rpc-url'}; + +setRpcUrl(rpcParams).then((result) => { + if (isSuccess(result)) { + // execute callback after RPC URL is set + } else { + // handle error + } +}); +```