SIP-9: snap.manifest.json v0.1 Source

Author Erik Marks, Olaf Tomalka
Status Final
Created 2022-11-07

Table of Contents

Abstract

This document specifies version 0.1 of the Snaps manifest file, snap.manifest.json.

Motivation

The goal of this SIP is to supersede Snaps Publishing Specification v0.1, and move Snaps specifications into one place - Snaps Improvement Proposals.

Specification

Indented sections like this are considered non-normative.

Paths that traverse JSON objects are using jq syntax.

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

Folder Structure

The published files of an example Snap published to npm under the package name @metamask/example-snap may look like this:

example-snap/
├─ dist/
│  ├─ bundle.js
├─ package.json
├─ snap.manifest.json

The snap MUST contain both package.json and snap.manifest.json files in the root directory of the snap package.

package.json

The package.json file MUST adhere to the requirements of npm.

snap.manifest.json

Note that the manifest intentionally does not contain any information explicitly identifying its author. Author information should be verifiable out-of-band at the point of Snap installation, and is beyond the scope of this specification.

  • snap.manifest.json - The contents of the file MUST be a JSON object.

    • .version - MUST be a valid SemVer version string and equal to the corresponding package.json field.

    • .proposedName - MUST be a string less than or equal to 214 characters. The proposed name SHOULD be human-readable.

      The snap’s author proposed name for the snap.

      The Snap host application may display this name unmodified in its user interface.

    • .description - MUST be a non-empty string less than or equal to 280 characters. MAY differ from the corresponding package.json:.description field

      A short description of the Snap.

      The Snap host application may display this description unmodified in its user interface.

    • .repository - MAY be omitted. If present, MUST be equal to the corresponding package.json:.repository field.
    • .source - MUST be a JSON object.
      • .shasum - MUST hash of the snap source file as specified in Checksum paragraph.
      • .location - MUST be a JSON object.
        • .npm - MUST be a JSON object.
          • .filePath - MUST be a Unix-style path relative to the package root directory pointing to the Snap source file.
          • .packageName - MUST be equal to the package.json:.name field.
          • .iconPath - MAY be omitted. If present, MUST be a Unix-style path relative to the package root directory pointing to an .svg file.
          • .registry - MUST be string https://registry.npmjs.org.
    • .initialPermissions - MUST be a valid EIP-2255 wallet_requestPermissions parameter object.

      Specifies the initial permissions that will be requested when the Snap is added to the host application.

    • .manifestVersion - MUST be the string 0.1.

Checksum

The checksum MUST be calculated using SHA-256 algorithm as specified in NIST’s FIPS PUB 180-4.

The checksum MUST be calculated over the file located under snap.manifest.json:.source.location.npm.filePath path and saved under snap.manifest.json:.source.shasum as Base64 field with exactly 44 characters. The Base64 character set MUST be A-Z, a-z, 0-9, +, / with = used for padding. The padding MUST NOT be optional.

Snap Source File

Represented in the example as dist/bundle.js. The Snap “source” or “bundle” file can be named anything and kept anywhere in the package file hierarchy.

The snap source file, located under snap.manifest.json:.source.location.npm.filePath path MUST:

  • have the .js file extension.
  • contain the entire source of the Snap program, including all dependencies.
  • execute under SES.

Test vectors

Snap package

A full example snap package can be found in the assets.

Manifest

A complete JSON Schema can be found in the assets.

Checksum

The shashum was generated using shasum -a 256 assets/sip-9/source.js | cut -d ' ' -f 1 | xxd -r -p | base64 command

  • assets/sip-9/source.js - x3coXGvZxPMsVCqPA1zr9SG/bw8SzrCPncClIClCfwA=
  • <empty file> - 47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=

Errata

2023-05-08:

  • Fix JSON Schema having some properties at the wrong nesting level.
  • Fix JSON Schema not supporting NPM registry with / suffix.
  • Added titles and descriptions to all properties in JSON Schema which are required for suggestions in Visual Studio Code.

Copyright and related rights waived via CC0.

Citation

Please cite this document as:

Erik Marks, Olaf Tomalka, "SIP-9: snap.manifest.json v0.1," Snaps Improvement Proposals, no. 9, November 2022. [Online serial]. Available: https://github.com/MetaMask/SIPs/blob/master/SIPS/sip-9.md