Service Metadata

Describing your AI services to the world

Service Naming Standards

The service metadata is the off-chain description of a SingularityNET service and is, by default, hosted on the SingularityNET IPFS cluster. In order to use a service, the client needs to know:

Fortunately the latter is included in the metadata. The daemon allowing access to the service also needs to know this metadata, in order to configure the necessary payment systems.

There are three ways of providing this metadata to the clients and the daemons:

  • as a simple JSON file
  • as a IPFS hash that points to the JSON metadata
  • as a name of service in the Registry - this can be resolved to an IPFS hash, pointing to the metadata, through the Registry’s getMetadataIPFSHash method.

As a security concern the client shoudn’t use mpe_address from the metadata as a sole source of the MPE contract address. The client should check that this address corresponds to the mpe_address it was expecting. The defaults MPE addresses for various networks are:

  • Mainnet - 0x9c9252ec9fa844e2c7bd2e6f54bec2901938479f
  • Ropsten - 0x7e6366fbe3bdfce3c906667911fc5237cc96bd08
  • Kovan (deprecated) - 0x39f31ac7b393fe2c6660b95b878feb16ea8f3156

A suspicious client should also check that hash of the metadata corresponds to the IPFS hash, otherwise the client can be attacked if the IPFS client is compromised. Fortunately, the snet-cli does this by default.

Metadata Overview

{
    // used to track format changes (current version is 1)
    "version": 1,
    // Display name of the service
    "display_name": "example-service",
    // Service encoding (proto or json)
    "encoding": "proto",
    // Service type (grpc, jsonrpc or process)
    "service_type": "grpc",
    // Service will reject payments with expiration less
    // than current_block + payment_expiration_threshold.
    // This field should be used by the client with caution.
    // Client should not accept arbitrary payment_expiration_threshold
    "payment_expiration_threshold": 40320,
    // IPFS HASH to the .tar archive of protobuf service specification
    "model_ipfs_hash": "QmSUGHW24YPjwMVhUnDwLExk4tgM8fVAKZCLqtLafbBQAu",
    // Address of MultiPartyEscrow contract.
    // - Client should use it for cross-checking of mpe_address
    // - Daemon can use it directly if authenticity of metadata is confirmed
    "mpe_address": "0x7E6366Fbe3bdfCE3C906667911FC5237Cc96BD08",
    // Pricing model
    // Only one pricing models currently implemented:
    // 1. Fixed price
    //    price_model   - "fixed_price"
    //    price_in_cogs -  unique fixed price in cogs for all method (1 AGI = 10^8 cogs)
    // (other pricing models can be easily supported)
    "pricing": {
        "price_model": "fixed_price",
        "price_in_cogs": 10
    },
    // group is the number of endpoints which shares same payment channel
    //      grouping strategy is defined by service provider;
    //      for example service provider can use region name as group name
    //    group_name - unique name of the group (human readable)
    //    group_id   - unique id of the group (random 32 byte string in base64 encoding)
    //    payment_address - Ethereum address to recieve payments
    "groups": [
        {
            "group_name": "default_group",
            "group_id": "58jzXGw13K3XC4VNNxZEPB36naQg2lEfduI/0z+axQs=",
            "payment_address": "0x464c564e427fA7A715922D9E0373a5D90589E021"
        }
    ],
    // Each entry specifies an endpoint URL for where the service is available,
    // and the corresponding payment group the replica belonds to
    "endpoints": [
        {
            "group_name": "default_group",
            "endpoint": "https://services-1.snet.sh:6306"
        }
    ]
}

This metadata file can be directly edited before publishing to IPFS, or manipulated by snet-cli through service subcommands that have the metadata-* prefix.

The python module for manipulating this metadata directly can be found here.