search

EOSIO / manifest-spec

A specification detailing how EOSIO-enabled applications comply with the application manifest requirements of EOSIO-compatible user agents
MIT License
9 stars 5 forks source link

readme

EOSIO Manifest Specification

EOSIO Labs

Specification Version: 0.7.0

A specification for metadata describing integrating apps, and the actions they can request from a user. This specification can be used by wallets to provide more information about the app a user is interacting with, and to run transaction pre-flight security checks comparing the contents of a transaction request with what integrating apps have declared about themselves.

Related Reading

This is just one of several thought leadership pieces focusing on wallets, key management and authentication, and the relating user experience. For more context and related reading, check out these these pieces:

About EOSIO Labs

EOSIO Labs repositories are experimental. Developers in the community are encouraged to use EOSIO Labs repositories as the basis for code and concepts to incorporate into their applications. Community members are also welcome to contribute and further develop these repositories. Since these repositories are not supported by Block.one, we may not provide responses to issue reports, pull requests, updates to functionality, or other requests from the community, and we encourage the community to take responsibility for these.

Why an Application Manifest?

  1. Provides user agents metadata about the app for use in application listings (history, favorites, app directories, etc.)
  2. Provides app developers with a way to declare which contract actions on a given chain an application on their domain is able to propose to end users
  3. Allows user agents to run various transaction pre-flight security assertions comparing the contents of a transaction request with what apps have declared about themselves
  4. Provides end users with more security and a better sense of trust--information about the apps they're using is displayed consistently and the transactions themselves are secured with on-chain assertions

Application Requirements for EOSIO User Agent Compatibility

How It Works

  1. In order for an EOSIO-enabled application to be compatible with EOSIO user agents, developers must submit an app manifest to the EOSIO chains on which it wishes to push transactions.
  2. When the application makes a request or proposes a transaction, it must pass along a declaredDomain. The user agent will verify the following items. If any fails verification, an error will be displayed to the user or returned to the application. It will verify:
    • that the domain is hosting a chain-manifests.json file and that all manifests listed reference the declared domain and app metadata consistently;
    • that the domain is hosting a app-metadata.json file and that it contains all required fields;
    • that the domain in the provided manifest matches the domain submitting the transaction (applicable only to web applications);
    • that the application's identifier (bundle ID, package name, etc.) as reported by the OS is whitelisted by the metadata's appIdentifiers field (applicable only to native applications);
    • that the contract action(s) in the transaction are whitelisted in the manifest;
    • that the hash of the icon in app-metadata.json matches the checksum of the icon file itself;
    • that the hash of app-metadata.json matches the hash declared in the provided manifest;
  3. When the user accepts the transaction, the user agent will hash the manifest and add an assertion action to the transaction so that the chain can validate that the manifest provided to the user agent has been registered for the given domain on that chain. If the manifest's hash is not found on the chain, the chain may reject the transaction.

Specification Versioning

Both the application metadata and chain manifest files defined below include fields defining the version of the manifest specification that they follow. Version numbers follow a semantic versioning (semver) inspired scheme consisting of three integers separated by periods . and represent the Major, Minor, and Patch levels in the form M.m.p. For example 1.2.3.

Fields are interpretted as follows:

Application Metadata Specification

Application metadata must be declared in a publicly available JSON file. The location of this file, along with its checksum hash, will be referenced by the EOSIO chain(s). Having this file referenced on-chain enables EOSIO-compatible user agents to validate the integrity of the metadata and may provide other future benefits. For example, developers could look for these records on the chain and put together public directories of EOSIO-compatible applications.

All of the following fields are required with the exception of description, sslfingerprint, and appIdentifiers.

Metadata Fields

Note: While the icon specification is still being developed, for now, these should be PNGs or JPGs at 256px x 256px.

Example

{
  "spec_version": "0.7.0",
  "name": "Landeos Property Registry",
  "shortname": "Landeos",
  "scope": "/",
  "apphome": "/home",
  "icon": "https://landeos.io/icon.png#SHA256HASH",
  "appIdentifiers": ["io.landeos.registry"],
  "description": "Landeos is a decentralized property registry...",
  "sslfingerprint": "E1 3F 0E 03 2D 05 3C D2 81 FB 57 02 42 51 D0 44 32 08 35 58 8C 73 C4 44 83 4D CA 3E 71 15 16 20",
  "chains": [
    {
      "chainId": "EOSIO1111",
      "chainName": "Property Chain",
      "icon": "/propertyChain.png#SHA256HASH"
    },
    {
      "chainId": "EOSIO2222",
      "chainName": "Other Chain",
      "icon": "/otherChain.png#SHA256HASH"
    }
  ]
}

This specification will be extended later to include additional application metadata (e.g., app screenshots and other listing-related data.)

Application Manifest Specification

Manifests must be registered using the eosio.assert::add.manifest action on every chain on which your app will transact. (See: https://github.com/EOSIO/eosio.assert.) Furthermore, an array of chain manifests must be declared in a publicly available JSON file at the root of the application's declaredDomain.

Manifest Fields

{
  account: string,
  domain: string,
  appmeta: string,
  whitelist: contract_action[]
}

contract_action

{
  contract: string,
  action: string
},

Example

{
  "account": "landeospropr",
  "domain": "https://landeos.io",
  "appmeta": "https://landeos.io/app-metadata.json#SHA256HASH",
  "whitelist": [
    {
      "contract": "eosio.token",
      "action": ""
    },
    {
      "contract": "landeospropr",
      "action": "register"
    }
  ]
}

chain-manifests.json

This file must reside at the root of your application's declared domain. Consists of a top-level object of two properties:

Here's an example:

{
  "spec_version": "0.0.7",
  "manifests": [
    {
      "chainId": "EOSIO1111",
      "manifest": {
        "account": "landeospropr",
        "domain": "https://landeos.io",
        "appmeta": "https://landeos.io/app-metadata.json#SHA256HASH",
        "whitelist": [
          {
            "contract": "eosio.token",
            "action": ""
          },
          {
            "contract": "landeospropr",
            "action": "register"
          }
        ]
      }
    },
    {
      "chainId": "EOSIO2222",
      "manifest": {
        "account": "landeospropr",
        "domain": "https://landeos.io",
        "appmeta": "https://landeos.io/app-metadata.json#SHA256HASH",
        "whitelist": [
          {
            "contract": "eosio.token",
            "action": ""
          },
          {
            "contract": "landeospropr",
            "action": "register"
          }
        ]
      }
    }
  ]
}

Contributing

Contributing Guide

Code of Conduct

License

MIT

Important

See LICENSE for copyright and license terms. Block.one makes its contribution on a voluntary basis as a member of the EOSIO community and is not responsible for ensuring the overall performance of the software or any related applications. We make no representation, warranty, guarantee or undertaking in respect of the software or any related documentation, whether expressed or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose and noninfringement. In no event shall we be liable for any claim, damages or other liability, whether in an action of contract, tort or otherwise, arising from, out of or in connection with the software or documentation or the use or other dealings in the software or documentation. Any test results or performance figures are indicative and will not reflect performance under all conditions. Any reference to any third party or third-party product, service or other resource is not an endorsement or recommendation by Block.one. We are not responsible, and disclaim any and all responsibility and liability, for your use of or reliance on any of these resources. Third-party resources may be updated, changed or terminated at any time, so the information here may be out of date or inaccurate. Any person using or offering this software in connection with providing software, goods or services to third parties shall advise such third parties of these license terms, disclaimers and exclusions of liability. Block.one, EOSIO, EOSIO Labs, EOS, the heptahedron and associated logos are trademarks of Block.one.

Wallets and related components are complex software that require the highest levels of security. If incorrectly built or used, they may compromise users’ private keys and digital assets. Wallet applications and related components should undergo thorough security evaluations before being used. Only experienced developers should work with this software.