SIP-29 Improvements

SIPS/sip-29.md

@@ -35,85 +35,140 @@ in uppercase in this document are to be interpreted as described in [RFC
 2. Any time an asset needs to be identified, it MUST use the [CAIP-19][caip-19]
 representation.
 
-### Snap Assets API
+### 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:
+
+```json
+{
+  "initialPermissions": {
+    "endowment:assets": {}
+  }
+}
+```
+
+### Snap Implementation
 
 Two methods are defined in the Snap Assets API:
 
-#### Get Token Description
+Any Snap that wishes to provide asset information **MUST** implement the following API:
+
+#### Get Asset Description
+
+```typescript
+import { OnAssetDescriptionHandler } from "@metamask/snaps-sdk";
+
+export const onAssetDescription: OnAssetDescriptionHandler = async ({
+  asset
+}) => {
+  const description = /* Get description */;
+  return { description };
+};
+```
+
+The type for an `onAssetDescription` handler function’s arguments is:
 
 ```typescript
-// Represents a token unit.
-type TokenUnit = {
-    // Human-friendly name of the token unit.
+interface OnAssetDescriptionArgs {
+    asset: Caip19AssetType;
+}
+```
+The type for an `onAssetDescription` handler function’s return value is:
+
+```typescript
+// Represents a asset unit.
+type AssetUnit = {
+    // Human-friendly name of the asset unit.
     name: string;
 
-    // Ticker of the token unit.
+    // Ticker of the asset unit.
     ticker: string;
 
-    // Number of decimals of the token unit.
+    // Number of decimals of the asset unit.
     decimals: number;
 };
 
-// Token description.
-type TokenDescription = {
-    // Human-friendly name of the token.
+// Asset description.
+type AssetDescription = {
+    // The CAIP-19 ID of the asset.
+    id: Caip19AssetType;
+
+    // Human-friendly name of the asset.
     name: string;
 
-    // Ticker of the token.
+    // Ticker of the asset.
     ticker: string;
 
-    // Whether the token is native to the chain.
+    // Whether the asset is native to the chain.
     isNative: boolean;
 
-    // Base64 representation of the token icon.
+    // Base64 representation of the asset icon.
     iconBase64: string;
 
-    // List of token units.
-    units: TokenUnit[];
+    // List of asset units.
+    units: AssetUnit[];
 };
 
-// Returns the description of a non-fungible token. This description can then
-// be used by the client to display relevant information about the token.
-//
-// @example
-// ```typescript
-// const tokenDescription = await getTokenDescription('eip155:1/slip44:60');
-//
-// // Returns:
-// // {
-// //     name: 'Ether',
-// //     ticker: 'ETH',
-// //     isNative: true,
-// //     iconBase64: 'data:image/png;base64,...',
-// //     units: [
-// //         {
-// //             name: 'Ether',
-// //             ticker: 'ETH',
-// //             decimals: 18
-// //         },
-// //         {
-// //             name: 'Gwei',
-// //             ticker: 'Gwei',
-// //             decimals: 9
-// //         },
-// //         {
-// //             name: 'wei',
-// //             ticker: 'wei',
-// //             decimals: 0
-// //         }
-// //     ]
-// // }
-// ```
-function getTokenDescription(token: Caip19AssetType): TokenDescription;
+// {
+//     name: 'Ether',
+//     ticker: 'ETH',
+//     isNative: true,
+//     iconBase64: 'data:image/png;base64,...',
+//     units: [
+//         {
+//             name: 'Ether',
+//             ticker: 'ETH',
+//             decimals: 18
+//         },
+//         {
+//             name: 'Gwei',
+//             ticker: 'Gwei',
+//             decimals: 9
+//         },
+//         {
+//             name: 'wei',
+//             ticker: 'wei',
+//             decimals: 0
+//         }
+//    ]
+// }
+
+type OnAssetDescriptionReturn = {
+    description: AssetDescription;
+};
 ```
 
-#### Get Token Conversion Rate
+#### Get Asset Conversion Rate
+
+```typescript
+import { OnAssetConversionHandler } from "@metamask/snaps-sdk";
+
+export const onAssetConversion: OnAssetConversionHandler = async ({
+  from,
+  to
+}) => {
+  const conversionRate = /* Get conversion rate */;
+  return { conversionRate };
+};
+```
+The type for an `onAssetDescription` handler function’s arguments is:
 
 ```typescript
-type TokenConversionRate = {
-    // The rate of conversion from the source token to the target token. It
-    // means that 1 unit of the `from` token should be converted to this amount
-    // of the `to` token.
+interface OnAssetConversionArgs {
+    from: Caip19AssetType;
+    to: Caip19AssetType;
+}
+```
+The type for an `onAssetDescription` handler function’s return value is:
+
+```typescript
+type AssetConversionRate = {
+    // The rate of conversion from the source asset to the target asset. 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.
@@ -123,26 +178,16 @@ type TokenConversionRate = {
     expirationTime: number;
 };
 
-// Returns the conversion rate between two assets (tokens or fiat).
-//
-// @example
-// ```typescript
-// const conversionRate = await getTokenConversionRate(
-//   'eip155:1/slip44:60',
-//   'eip155:1/erc20:0x6b175474e89094c44da98b954eedeac495271d0f'
-// );
-//
-// // Returns:
-// // {
-// //     rate: '3906.38',
-// //     conversionTime: 1733389786,
-// //     expirationTime: 1733389816,
-// // }
-// ```
-function getTokenConversionRate(
-    from: Caip19AssetType,
-    to: Caip19AssetType
-): TokenConversionRate;
+
+// {
+//     rate: '3906.38',
+//     conversionTime: 1733389786,
+//     expirationTime: 1733389816,
+// }
+
+type OnAssetConversionReturn = {
+    conversionRate: AssetConversionRate;
+};
 ```
 
 ### Fiat currency representation