The Metadata Service API

This document describes using the service as an API. Working knowledge of gRpc is assumed.

Service API

This is a partial listing of the MetadataService (v0.2)

service MetadataService {
  rpc SubmitMetadata(SubmitMetadataRequest) returns (stream SubmitMetadataResponse);
  rpc ListMetadata(ListMetadataRequest) returns (stream ListMetadataResponse);
  rpc TransactionMetadata(TransactionMetadataRequest) returns (stream TransactionMetadataResponse);
}

message SubmitMetadataRequest {
  oneof options {
    string metadata = 1;
    string tx_id = 2; 
  }
  int32 until_depth = 3;
  iog.psg.service.common.CredentialsMessage credentials = 4;
}

message SubmitMetadataResponse {
  oneof result {
    AppError problem = 1;
    TxStatus tx_status = 2;
  }
}

message TransactionMetadataRequest {
  string txHash = 1;
  iog.psg.service.common.CredentialsMessage credentials = 2;
}

message ListMetadataRequest {
  google.protobuf.Timestamp startAt = 1;
  google.protobuf.Timestamp endAt = 2;
  iog.psg.service.common.CredentialsMessage credentials = 3;
}

message TransactionMetadataResponse {
  oneof result {
    AppError problem = 1;
    google.protobuf.Struct metadata = 2;
  }
}

message ListMetadataResponse {
  oneof result {
    AppError problem = 1;
    TxStatus tx_status = 2;
  }
}

There are 3 functions

  • Submit metadata to the blockchain

  • List transaction statuses.

  • Gets metadata on an already submitted metadata transaction

All methods provide a stream of responses.

Submit Metadata

To submit metadata the caller provides

  • the depth - This is the number of blocks the caller wants the metadata transaction buried under. If the caller specifies a depth of 1 block there is always the chance the blockchain will reorganise itself and remove the transaction, a depth of 100 means that possibility is vanishingly small, but the call will take longer.

  • the credentials - These are the credentials generated by the PSG Services web application after the user has created a “log in” and paid for use of the services. new_user_guide

  • either

    • the metadata - Provide the metadata as a string in JSON format, but conforming to the schema described here.
      The first result in the stream of results returned by the call will contain the transaction id (tx_id). In the case where the call is interrupted it can be restarted by calling SubmitMetadata again but providing the transaction id instead of the metadata. The result will be a stream of responses. These responses are checked for status, first to make sure the request has a state ‘IN_LEDGER’ and finally, to indicate the transaction has been ‘buried’ under the requisite number of blocks. In the case of a problem, that problem is described in the problem field of the response.`

    • the transaction id

List Metadata

List all metadata transactions between the dates given.

Note: The list contains transactions from all users. In order to get transactions for a particular user - you need to filter a list by metadata or transactionId.

Note: the dates are optional and when not provided, all metadata transactions are returned.

Note: if a transaction has no metadata, it will not be listed by this call.

Note: on the very rare occasions where the internal service configuration drastically changes transactions associated with a clientId may not be returned. Client applications that have a critical long term dependency on remembering the ids of the transactions they posted are advised to make an independent record of the transaction id.

Transaction Metadata

Get metadata for given transaction hash. The caller provides

  • transaction Hash

  • credentials - These are the credentials generated by the PSG Services web application after the user has created a “log in” and paid for use of the services.new_user_guide