Introduction to Aptos Wallet Standard

"Wallet Standard" is the new wallet interoperability standard designed by the Aptos ecosystem., which simplifies the interaction between wallets and dapps through an event-based communication model, while reducing resource consumption, maintenance stress, and supply chain attack risk."

Due to its versatility, wallets supporting this standard can easily migrate from one blockchain to another and seamlessly integrate with dApps across multiple chains. The integration and implementation process is simple, and in most cases only requires the registration and testing process to be completed using the provided methodology. Any future new features or improvements should avoid importing disruptive changes, as each wallet runs its own private plugin code and implements features in a separate context.

Impact of new wallet standards:

Dapp developers need to:

1. Understand and familiarize yourself with the new wallet standard

2. Migrate your code to the new TypeScript SDK.

3、Enabling wallet discoverability to block non-Aptos wallets

Wallet developers are needed:

1. Understand and be familiar with the new wallet label

2. Migrate to the new TypeScript SDK or maintain the type conversion layer from the new SDK to the old SDK as needed.

3. Register your wallet and make sure it can be properly discovered by dapp.

4. Implement the AptosWallet class that conforms to the Aptos Wallet protocol in accordance with the new standard

Normative details

(i) Standardized functional specifications

The following lists the standardized functions that the wallet needs to follow, including the required versus recommended methods of implementation. Check the recommended Aptos Feature List

Functions marked with * are optional

The aptos:connect method is designed to establish a connection between the dapp and the wallet.

// `silent?: boolean` - allows connections to be triggered without attracting the user's attention (e.g. for auto-connect functionality)
// `networkInfo?: NetworkInfo` - specifies the network information selected by the dapp (facilitates connecting and switching network operations)

connect(silent?: boolean, networkInfo?: NetworkInfo): Promise<UserResponse>;.

The aptos:disconnect method is used to disconnect the connection established between the dapp and the wallet.

disconnect(): Promise;
aptos:getAccount is used to get the currently connected account in the wallet

getAccount():Promise<UserResponse>
aptos:getNetwork is used to get the current network in the wallet

getNetwork(): Promise<UserResponse>;.

aptos:signTransaction is used to sign messages in the wallet for the currently connected account.

// `transaction: AnyRawTransaction` - a generated raw transaction created with Aptos' TS SDK

signTransaction(transaction: AnyRawTransaction):AccountAuthenticator

aptos:signMessage is used to sign messages in the wallet for the currently connected account.

// `message: AptosSignMessageInput` - a message to sign

signMessage(message: AptosSignMessageInput):Promise<UserResponse>;.

The aptos:onAccountChange event, which is triggered by the wallet when an account in the wallet changes.

// `newAccount: AccountInfo` - The new connected account

onAccountChange(newAccount: AccountInfo): Promise

The aptos:onNetworkChange event, which is triggered by the wallet when the network in the wallet changes.

// `newNetwork: NetworkInfo` - The new wallet current network

onNetworkChange(newNetwork: NetworkInfo):Promise

The aptos:signAndSubmitTransaction* method signs and submits the transaction using the currently connected account in the wallet.

// `transaction: AnyRawTransaction` - a generated raw transaction created with Aptos' TS SDK

signAndSubmitTransaction(transaction: AnyRawTransaction): Promise<UserResponse>;.

aptos:changeNetwork* event that dapp sends to the wallet to change the wallet's current network

// `network:NetworkInfo` - The network for the wallet to change to

changeNetwork(network:NetworkInfo):Promise<UserResponse>

The aptos:openInMobileApp* function, which supports redirecting the user from the mobile device's web browser to the native mobile app. The wallet plugin should add the URL of the location where the wallet should be opened in the in-app browser.

openInMobileApp(): void

(ii) Types

Note: The UserResponse type is used when the user rejects a request that can be rejected. For example, when the user wants to connect but closes the window popup.

export enum UserResponseStatus {
  APPROVED = 'Approved'.
  REJECTED = 'Rejected'
}

export interface UserApproval {
 status: UserResponseStatus.APPROVED
 args: TResponseArgs
}

export interface UserRejection {
 status: UserResponseStatus.REJECTED
}

export type UserResponse = UserApproval | UserRejection.

export interface AccountInfo = { account: Account, ansName?: string }

export interface NetworkInfo {
  name: Network
  chainId: number
  url?: string
}

export type AptosSignMessageInput = {
  address?: boolean
  application?: boolean
  chainId?: boolean
  message: string
  nonce: string
}

export type AptosSignMessageOutput = {
  address?: string
  application?: string
  chainId?: number
  fullMessage: string
  message: string
  nonce: string
  prefix: 'APTOS'
  signature: Signature
}

(iii) Errors

The wallet must throw an AptosWalletError. the standard requires support for Unauthorized and InternalError, but the wallet can throw a custom AptosWalletError error

Using the default message

if (error) {
  throw new AptosWalletError(AptosWalletErrorCode.Unauthorized);
}

Using custom messages

if (error) {
  throw new AptosWalletError(
    AptosWalletErrorCode.Unauthorized,
    "My custom unauthorized message"
  );
}

Using Custom Errors

if (error) {
  throw new AptosWalletError(-32000, "Invalid Input");
}

reference implementation

The standard exposes a detect function that detects whether an existing wallet conforms to the Aptos standard by verifying that the required functions are present in the wallet. These functions are called features, and each feature should be defined in the aptos namespace, colon, and {method} name, aptos:connect.

(i) Purse providers

AptosWallet Interface Implementation

The wallet must implement an AptosWallet interface and provide information and characteristics of the wallet provider:

class MyWallet implements AptosWallet {
  url: string;
  version: "1.0.0".
  name: string;
  icon.
    | `data:image/svg+xml;base64,${string}`
    | `data:image/webp;base64,${string}`
    | `data:image/png;base64,${string}`
    | `data:image/gif;base64,${string}`.
  chains: AptosChain.
  features: AptosFeatures.
  accounts: readonly AptosWalletAccount[].
}

AptosWalletAccount Interface Implementation

The wallet must implement an AptosWalletAccount interface that represents the account that has been authorized by the dapp.

enum AptosAccountVariant {
  Ed25519.
  MultiEd25519.
  SingleKey.
  MultiKey.
}

class AptosWalletAccount implements WalletAccount {
  address: string;

  publicKey: Uint8Array.

  chains: AptosChain.

  features: AptosFeatures.

  variant: AptosAccountVariant.

  label?: string;

  icon?
    | `data:image/svg+xml;base64,${string}`
    | `data:image/webp;base64,${string}`
    | `data:image/png;base64,${string}`
    | `data:image/gif;base64,${string}`
    | undefined.
}

Register Wallet

To notify the dapp that it is ready, the wallet registers itself by using the registerWallet method.

const myWallet = new MyWallet();

registerWallet(myWallet).

(ii) Dapp

Get Wallet

Dapp uses the getAptosWallets() function, which gets all Aptos-compliant wallets.

import { getAptosWallets } from "@aptos-labs/wallet-standard".

let { aptosWallets, on } = getAptosWallets();

registered event

Prior to initial loading and dapp startup, the system will obtain information about all registered wallets. In order to continue monitoring newly registered wallets after this point in time, the dapp needs to subscribe to the registration of new wallets using an event listener that provides an unsubscribe function that can be used to revoke the listener later.

const removeRegisterListener = on("register", function () {
  // Dapps can add newly registered aptos wallets to their own state context.
  let { aptosWallets } = getAptosWallets();
});

const removeUnregisterListener = on("unregister", function () {
  let { aptosWallets } = getAptosWallets();
});

Dapp now has an event listener, so it can see new wallets immediately, without polling or listing them again. This also works if the dapp loads before any wallets are loaded (it will initialize but not see any wallets, then see the wallets as they load).

wallet request

Dapp makes a wallet request by invoking the name of the feature that corresponds to the desired action.

const onConnect = () => {
  this.wallet.features["aptos:connect"].connect();
};

For more details, please refer to AIP-62 (https://github.com/ALCOVE-LAB/Aptos-Docs/blob/main/AIP/aip-62.md) 

We have translated the Chinese version of the official English documentation for your reference.

Launched in November 2023, alcove is the first Move on Aptos Chinese developer community in Asia built by Aptos public chain and Alibaba Cloud. We are committed to helping developers use Move language to build next-generation Web3 applications on Aptos by providing a full range of resources such as education, technology, and financial support, so as to realize individual value and promote the innovation and development of the industry.

Official Twitter feed: alcove_pro