SIP-29: Snap Assets API

Abstract

This SIP aims to define a new API that can be exposed by Snaps to allow clients to retrieve asset information in a chain-agnostic way.

Motivation

To enable clients to be chain-agnostic, the logic for obtaining asset information should be abstracted away from the client. Additionally, this SIP defines the types that represent the asset information required by clients.

Specification

Indented sections like this are considered non-normative.

Language

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “NOT RECOMMENDED”, “MAY”, and “OPTIONAL” written in uppercase in this document are to be interpreted as described in RFC 2119

Definitions

1. In this document, all definitions are written in TypeScript.

2. Any time an asset needs to be identified, it MUST use the CAIP-19 representation.

Snap Manifest

This SIP introduces a new permission named endowment:assets. This permission grants a Snap the ability to provide asset information to the client.

This permission is specified as follows in snap.manifest.json files:

{
  "initialPermissions": {
    "endowment:assets": {
      "scopes": [
        "bip122:000000000019d6689c085ae165831e93"
      ]
    }
  }
}

scopes - A non-empty array of CAIP-2 chain IDs that the Snap supports. This field is useful for a client in order to avoid unnecessary overhead. Any asset returned by the Snap MUST be filtered out if it isn’t part of the supported scopes.

Snap Implementation

Two methods are defined in the Snap Assets API:

Any Snap that wishes to provide asset information MUST implement the following API:

Get Assets Metadata

Caip19AssetType - A string that represents an asset using the CAIP-19 standard.

import { OnAssetsLookupHandler } from "@metamask/snaps-sdk";

export const onAssetsLookup: OnAssetsLookupHandler = async ({
  assets
}) => {
  const assetsMetadata = /* Get metadata for given `assets` */;
  return { assets: assetsMetadata };
};

The type for an onAssetsLookup handler function’s arguments is:

interface OnAssetsLookupArguments {
  assets: Caip19AssetType[];
}

The type for an onAssetsLookup handler function’s return value is:

type OnAssetsLookupResponse = {
  assets: Record<Caip19AssetType, AssetMetadata>;
};

Get Assets Conversion Rate

import { OnAssetsConversionHandler } from "@metamask/snaps-sdk";

export const onAssetsConversion: OnAssetsConversionHandler = async ({
  conversions
}) => {
  const conversionRates = /* Get conversion rate for given `conversions` */;
  return { conversionRates };
};

The type for an onAssetsConversion handler function’s arguments is:

type Conversion = {
  from: Caip19AssetType;
  to: Caip19AssetType;
};

type OnAssetsConversionArguments = {
  conversions: Conversion[];
};

The type for an onAssetsConversion handler function’s return value is:

type AssetConversionRate = {
  // The rate of conversion from the source asset to the target asset represented as a decimal number in a string.
  // It means that 1 unit of the `from` asset should be converted to this amount
  // of the `to` asset.
  rate: string;

  // The UNIX timestamp of when the conversion rate was last updated.
  conversionTime: number;

  // The UNIX timestamp of when the conversion rate will expire.
  expirationTime?: number;
};

type FromAsset = Conversion["from"];

type ToAsset = Conversion["to"];

type OnAssetsConversionResponse = {
  conversionRates: Record<From, Record<To, AssetConversionRate>>;
};

Appendix I: Fungible Asset Metadata

The following asset metadata fields for a fungible asset are defined. As of the time of creation of this SIP, they are the only possible assets requested by clients.

// Represents an asset unit.
type FungibleAssetUnit = {
  // Human-friendly name of the asset unit.
  name: string;

  // Ticker symbol of the asset unit.
  symbol: string;

  // Number of decimals of the asset unit.
  decimals: number;
};

// Fungible asset metadata.
type FungibleAssetMetadata = {
  // Human-friendly name of the asset.
  name: string;

  // Ticker symbol of the asset's main unit.
  symbol: string;

  // Represents a fungible asset
  fungible: true;

  // Base64 data URI or URL representation of the asset icon.
  iconUrl: string;

  // List of asset units.
  units: FungibleAssetUnit[];
};

// Represents the metadata of an asset.
type AssetMetadata = FungibleAssetMetadata

Copyright

Copyright and related rights waived via CC0.

Citation

Please cite this document as:

Daniel Rocha, Guillaume Roux, "SIP-29: Snap Assets API [DRAFT]," Snaps Improvement Proposals, no. 29, December 2024. [Online serial]. Available: https://github.com/MetaMask/SIPs/blob/master/SIPS/sip-29.md