• Go: address.go

• Kotlin: MetadataAddress.kt

• Javascript: metadata-address.js

• As strings, the metadata addresses are represented using the bech32 address format.

• The IdInfo messages defined in metadata.proto (e.g. RecordIdInfo) are used in response messages and contain a breakdown of a metadata address.

• Variables that hold the addresses as byte arrays should end in _id.

• Variables that hold the addresses as bech32 strings should end in _addr.

• Variables that hold UUIDs as strings should use the standard UUID format and end in _uuid.

• If a variable is a byte array that ends in _id, then it should be the full Metadata Address byte array.

• String variables that end in _id should only be used in input messages. They should be flexible fields that can accept either the bech32 string version of the Metadata Address byte array, or a UUID in the standard UUID string format.

• If a variable ends in _addr, then it should be the bech32 string version of the Metadata Address byte array.

• If a variable ends in _uuid, then it should be a UUID in the standard UUID string format.

• Type byte: A single byte representing the type of index.

• Part 1: Address of the starting thing in the association.

• Part 2: Address of the entry to find.

• When a value owner address is being set to a marker, at least one of the signers must have deposit permission on that marker.

• When a value owner address is a marker and is being changed, at least one of the signers must have withdraw permission on that marker.

• When a value owner address is a non-marker address, and is being changed, that existing address must be one of the signers.

• When a value owner address is empty, and is being changed, standard scope signer requirements are also applied even if that's the only change to the scope.

• A party with a smart contract address MUST have the PROVENANCE role.

• A party with the PROVENANCE role MUST have the address of a smart contract.

• When a smart contract signs a message, it MUST be first or have only smart-contract signers before it, and SHOULD include the invoker address(es) after.

• When a smart contract is a signer, it must either be a party/owner, or have authorizations (via x/authz) from all signers after it.

• If a smart contract is a signer, but not a party, it cannot be the only signer, and cannot be the last signer.

• All roles required by the scope spec must have a party in the owners.

• If not new:
• All optional = false existing owners must be signers.
• All roles required by the scope spec must have a signer and associated party from the existing scope.

• Scope value owner address requirements are applied.

• All proposed session parties must be present in this scope's owners.

• All optional = false scope owners must be signers.

• If new:
• All roles required by the contract spec must have a signer and associated party in the proposed session.

• If not new:
• All roles required by the contract spec must have a signer and associated party in the existing session.
• All roles required by the contract spec must have parties in the proposed session.
• All optional = false existing parties must also be signers.

• All roles required by the record spec must have a signer and associated party in the session.

• All optional = false scope owners and session parties must be signers.

• If the record is changing sessions, all optional = false previous session parties must be signers.

• All roles required by the record spec must have a signer and associated party in the scope.

• All optional = false scope owners must be signers.

• All roles required by the scope spec must have a party in the owners.

• If not new, all existing owners must sign.

• Scope value owner address requirements are applied.

• All roles required by the contract spec must have a party in the session parties.

• All scope owners must sign.

• All roles required by the record spec must have a party in the session parties.

• All session parties must sign.

• If the record is changing to a new session, all previous session parties must sign.

• All scope owners must sign.

• A scope must conform to a pre-determined scope specification.

• A scope is used to group together many sessions and records.

• Field Name: Scope.scope_id

• Bech32 HRP: "scope"

• Bech32 Example: "scope1qzge0zaztu65tx5x5llv5xc9ztsqxlkwel"

protobuf
// Scope defines a root reference for a collection of records owned by one or more parties.
message Scope {
  option (gogoproto.goproto_stringer) = false;

  // Unique ID for this scope. Implements sdk.Address interface for use where addresses are required in Cosmos
  bytes scope_id = 1 [(gogoproto.nullable) = false, (gogoproto.customtype) = "MetadataAddress"];

  // the scope specification that contains the specifications for data elements allowed within this scope
  bytes specification_id = 2 [(gogoproto.nullable) = false, (gogoproto.customtype) = "MetadataAddress"];

  // These parties represent top level owners of the records within. These parties must sign any requests that modify
  // the data within the scope. These addresses are in union with parties listed on the sessions.
  repeated Party owners = 3 [(gogoproto.nullable) = false];

  // Addresses in this list are authorized to receive off-chain data associated with this scope.
  repeated string data_access = 4;

  // An address that controls the value associated with this scope. Standard blockchain accounts and marker accounts
  // are supported for this value. This attribute may only be changed by the entity indicated once it is set.
  string value_owner_address = 5;

  // Whether all parties in this scope and its sessions must be present in this scope's owners field.
  // This also enables use of optional=true scope owners and session parties.
  bool require_party_rollup = 6;
}

• Type byte: 0x17

• Part 1: The owner address (length byte then value bytes)

• Part 2: All bytes of the scope key

• Type byte: 0x11

• Part 1: All bytes of the scope specification key

• Part 2: All bytes of the scope key

• Type byte: 0x18

• Part 1: The value owner address (length byte then value bytes)

• Part 2: All bytes of the scope key

• A session must conform to a pre-determined contract specification.

• A session groups together a collection of records.

• A session is part of exactly one scope.

• Field Name: Session.session_id

• Bech32 HRP: "session"

• Bech32 Example: "session1qxge0zaztu65tx5x5llv5xc9zts9sqlch3sxwn44j50jzgt8rshvqyfrjcr"

protobuf
// Session defines an execution context against a specific specification instance.
// The context will have a specification and set of parties involved.
//
// NOTE: When there are no more Records within a Scope that reference a Session, the Session is removed.
message Session {
  option (gogoproto.goproto_stringer) = false;

  bytes session_id = 1 [(gogoproto.nullable) = false, (gogoproto.customtype) = "MetadataAddress"];

  // unique id of the contract specification that was used to create this session.
  bytes specification_id = 2 [(gogoproto.nullable) = false, (gogoproto.customtype) = "MetadataAddress"];

  // parties is the set of identities that signed this contract
  repeated Party parties = 3 [(gogoproto.nullable) = false];

  // name to associate with this session execution context, typically classname
  string name = 4;

  // context is a field for storing client specific data associated with a session.
  bytes context = 5;

  // Created by, updated by, timestamps, version number, and related info.
  AuditFields audit = 99;
}

• A record must conform to a pre-determined record specification.

• A record is part of exactly one scope.

• A record is part of exactly one session.

• Field Name: Record.record_id

• Bech32 HRP: "record"

• Bech32 Example: "record1q2ge0zaztu65tx5x5llv5xc9ztsw42dq2jdvmdazuwzcaddhh8gmu3mcze3"

protobuf
// A record (of fact) is attached to a session or each consideration output from a contract
message Record {
  option (gogoproto.goproto_stringer) = false;

  // name/identifier for this record. Value must be unique within the scope. Also known as a Fact name
  string name = 1;

  // id of the session context that was used to create this record (use with filtered kvprefix iterator)
  bytes session_id = 2 [(gogoproto.nullable) = false, (gogoproto.customtype) = "MetadataAddress"];

  // process contain information used to uniquely identify an execution on or off chain that generated this record
  Process process = 3 [(gogoproto.nullable) = false];

  // inputs used with the process to achieve the output on this record
  repeated RecordInput inputs = 4 [(gogoproto.nullable) = false];

  // output(s) is the results of executing the process on the given process indicated in this record
  repeated RecordOutput outputs = 5 [(gogoproto.nullable) = false];

  // specification_id is the id of the record specification that was used to create this record.
  bytes specification_id = 6 [(gogoproto.nullable) = false, (gogoproto.customtype) = "MetadataAddress"];
}

• Field Name: ScopeSpecification.specification_id

• Bech32 HRP: "scopespec"

• Bech32 Example: "scopespec1qnwg86nsatx5pl56muw0v9ytlz3qu3jx6m"

protobuf
// ScopeSpecification defines the required parties, resources, conditions, and consideration outputs for a contract
message ScopeSpecification {
  option (gogoproto.goproto_stringer) = false;

  // unique identifier for this specification on chain
  bytes specification_id = 1 [(gogoproto.nullable) = false, (gogoproto.customtype) = "MetadataAddress"];

  // General information about this scope specification.
  Description description = 2;

  // Addresses of the owners of this scope specification.
  repeated string owner_addresses = 3;

  // A list of parties that must be present on a scope (and their associated roles)
  repeated PartyType parties_involved = 4;

  // A list of contract specification ids allowed for a scope based on this specification.
  repeated bytes contract_spec_ids = 5 [(gogoproto.nullable) = false, (gogoproto.customtype) = "MetadataAddress"];
}

• Type byte: 0x19

• Part 1: The owner address (length byte then value bytes)

• Part 2: All bytes of the scope specification key

• Type byte: 0x14

• Part 1: All bytes of the contract specification key

• Part 2: All bytes of the scope specification key

• Type byte: 0x11

• Part 1: All bytes of the scope specification key

• Part 2: All bytes of the scope key

• Field Name: ContractSpecification.specification_id

• Bech32 HRP: "contractspec"

• Bech32 Example: "contractspec1q000d0q2e8w5say53afqdesxp2zqzkr4fn"

protobuf
// ContractSpecification defines the required parties, resources, conditions, and consideration outputs for a contract
message ContractSpecification {
  option (gogoproto.goproto_stringer) = false;

  // unique identifier for this specification on chain
  bytes specification_id = 1 [(gogoproto.nullable) = false, (gogoproto.customtype) = "MetadataAddress"];

  // Description information for this contract specification
  Description description = 2;

  // Address of the account that owns this specificaiton
  repeated string owner_addresses = 3;

  // a list of party roles that must be fullfilled when signing a transaction for this contract specification
  repeated PartyType parties_involved = 4;

  // Reference to a metadata record with a hash and type information for the instance of code that will process this
  // contract
  oneof source {
    // the address of a record on chain that represents this contract
    bytes resource_id = 5 [(gogoproto.casttype) = "github.com/cosmos/cosmos-sdk/types.AccAddress"];
    // the hash of contract binary (off-chain instance)
    string hash = 6;
  }

  // name of the class/type of this contract executable
  string class_name = 7;
}

• Type byte: 0x20

• Part 1: The owner address (length byte then value bytes)

• Part 2: All bytes of the contract specification key

• Type byte: 0x14

• Part 1: All bytes of the contract specification key

• Part 2: All bytes of the scope specification key

• Field Name: RecordSpecification.specification_id

• Bech32 HRP: "recspec"

• Bech32 Example: "recspec1qh00d0q2e8w5say53afqdesxp2zw42dq2jdvmdazuwzcaddhh8gmuqhez44"

protobuf
// RecordSpecification defines the specification for a Record including allowed/required inputs/outputs
message RecordSpecification {
  option (gogoproto.goproto_stringer) = false;

  // unique identifier for this specification on chain
  bytes specification_id = 1 [(gogoproto.nullable) = false, (gogoproto.customtype) = "MetadataAddress"];

  // Name of Record that will be created when this specification is used
  string name = 2;

  // A set of inputs that must be satisified to apply this RecordSpecification and create a Record
  repeated InputSpecification inputs = 3;

  // A type name for data associated with this record (typically a class or proto name)
  string type_name = 4;

  // Type of result for this record specification (must be RECORD or RECORD_LIST)
  DefinitionType result_type = 5;

  // Type of party responsible for this record
  repeated PartyType responsible_parties = 6;
}

protobuf
// Defines an Locator object stored on chain, which represents a owner( blockchain address) associated with a endpoint
// uri for it's associated object store.
message ObjectStoreLocator {
  option (cosmos.msg.v1.signer) = "owner";

  // account address the endpoint is owned by
  string owner = 1;

  // locator endpoint uri
  string locator_uri = 2;

  // owners encryption key address
  string encryption_key = 3;
}

protobuf
message MsgWriteScopeRequest {
  Scope scope = 1;
  repeated string signers = 2;
  string scope_uuid = 3;
  string spec_uuid = 4;
}

protobuf
message MsgWriteScopeResponse {
  MetadataAddress scope_id_info = 1;
}

• The scope_id is missing or invalid.

• The specification_id is missing or invalid.

• The owners list is empty.

• Any of the owner address values aren't bech32 address strings.

• Any of the data_access values aren't bech32 address strings.

• A value_owner_address is provided that isn't a bech32 address string.

• The signers do not have permission to write the scope.

protobuf
message MsgDeleteScopeRequest {
  bytes scope_id = 1;
  repeated string signers = 2;
}

protobuf
message MsgDeleteScopeResponse {}

• No scope exists with the given scope_id.

• The signers do not have permission to delete the scope.

protobuf
message MsgAddScopeDataAccessRequest {
  bytes scope_id = 1;
  repeated string data_access = 2;
  repeated string signers = 3;
}

protobuf
message MsgAddScopeDataAccessResponse {}

• Any provided address is invalid.

• Any provided address is already in the scope's data access list.

• The signers do not have permission to update the scope.

protobuf
message MsgDeleteScopeDataAccessRequest {
  bytes scope_id = 1;
  repeated string data_access = 2;
  repeated string signers = 3;
}

protobuf
message MsgDeleteScopeDataAccessResponse {}

• Any provided address is not already in the scope's data access list.

• The signers do not have permission to update the scope.

protobuf
message MsgAddScopeOwnerRequest {
  bytes scope_id = 1;
  repeated Party owners = 2;
  repeated string signers = 3;
}

protobuf
message MsgAddScopeOwnerResponse {}

• Any new party is invalid.

• An optional = true party is being added to a require_party_rollup = false scope.

• The signers do not have permission to update the scope.

protobuf
message MsgDeleteScopeOwnerRequest {
  bytes scope_id = 1;
  repeated string owners = 2;
  repeated string signers = 3;
}

protobuf
message MsgDeleteScopeOwnerResponse {}

• Any provided owners (addresses) are not an address in a party in the scope.

• The resulting scope owners do not meet scope specification requirements.

• The signers do not have permission to update the scope.

protobuf
message MsgUpdateValueOwnersRequest {
  repeated bytes scope_ids = 1;
  string value_owner_address = 2;
  repeated string signers = 3;
}

protobuf
message MsgUpdateValueOwnersResponse {}

• The new value owner address is invalid.

• Any of the provided scope ids are not metadata scope identifiers or do not exist.

• The signers are not allowed to update the value owner address of a provided scope.

protobuf
message MsgMigrateValueOwnerRequest {
  string existing = 1;
  string proposed = 2;
  repeated string signers = 3;
}

protobuf
message MsgMigrateValueOwnerResponse {}

• Either the existing or proposed values are not valid bech32 addresses.

• The existing address is not a value owner on any scopes.

• The signers are not allowed to update the value owner address of a scope being updated.

protobuf
message MsgWriteSessionRequest {
  Session session = 1;
  repeated string signers = 2;
  SessionIdComponents session_id_components = 3;
  string spec_uuid = 4;
}

protobuf
message MsgWriteSessionResponse {
  MetadataAddress session_id_info = 1;
}

protobuf
message MsgWriteRecordRequest {
  Record record = 1;
  repeated string signers = 2;
  SessionIdComponents session_id_components = 3;
  string contract_spec_uuid = 4;
}

protobuf
message MsgWriteRecordResponse {
  MetadataAddress record_id_info = 1;
}

protobuf
message MsgDeleteRecordRequest {
  bytes record_id = 1;
  repeated string signers = 2;
}

protobuf
message MsgDeleteRecordResponse {}

• No record exists with the given record_id.

• The signers do not have permission to delete the record.

protobuf
message MsgWriteScopeSpecificationRequest {
  ScopeSpecification specification = 1;
  repeated string signers = 2;
  string spec_uuid = 3;
}

protobuf
message MsgWriteScopeSpecificationResponse {
  MetadataAddress scope_spec_id_info = 1;
}

protobuf
message MsgDeleteScopeSpecificationRequest {
  bytes specification_id = 1;
  repeated string signers = 2;
}

protobuf
message MsgDeleteScopeSpecificationResponse {}

protobuf
message MsgWriteContractSpecificationRequest {
  ContractSpecification specification = 1;
  repeated string signers = 2;
  string spec_uuid = 3;
}

protobuf
message MsgWriteContractSpecificationResponse {
  MetadataAddress contract_spec_id_info = 1;
}

protobuf
message MsgDeleteContractSpecificationRequest {
  bytes specification_id = 1;
  repeated string signers = 2;
}

protobuf
message MsgDeleteContractSpecificationResponse {}

protobuf
message MsgAddContractSpecToScopeSpecRequest {
  bytes contract_specification_id = 1;
  bytes scope_specification_id = 2;
  repeated string signers = 3;
}

protobuf
message MsgAddContractSpecToScopeSpecResponse {}

protobuf
message MsgDeleteContractSpecFromScopeSpecRequest {
  bytes contract_specification_id = 1;
  bytes scope_specification_id = 2;
  repeated string signers = 3;
}

protobuf
message MsgDeleteContractSpecFromScopeSpecResponse {}

protobuf
message MsgWriteRecordSpecificationRequest {
  RecordSpecification specification = 1;
  repeated string signers = 2;
  string contract_spec_uuid = 3;
}

protobuf
message MsgWriteRecordSpecificationResponse {
  MetadataAddress record_spec_id_info = 1;
}

protobuf
message MsgDeleteRecordSpecificationRequest {
  bytes specification_id = 1;
  repeated string signers = 2;
}

protobuf
message MsgDeleteRecordSpecificationResponse {}

protobuf
message MsgBindOSLocatorRequest {
  ObjectStoreLocator locator = 1;
}

protobuf
message MsgBindOSLocatorResponse {
  ObjectStoreLocator locator = 1;
}

protobuf
message MsgDeleteOSLocatorRequest {
  ObjectStoreLocator locator = 1;
}

protobuf
message MsgDeleteOSLocatorResponse {
  ObjectStoreLocator locator = 1;
}

protobuf
message MsgModifyOSLocatorRequest {
  ObjectStoreLocator locator = 1;
}

protobuf
message MsgModifyOSLocatorResponse {
  ObjectStoreLocator locator = 1;
}

protobuf
message MsgSetAccountDataRequest {
  string metadata_addr = 1;
  string value = 2;
  string signer = 3;
}

protobuf
message MsgSetAccountDataResponse {}

• The provided address is not a scope id.

• The provided scope id does not exist.

• The signers do not have authority to update the entry.

• The provided value is too long (as defined by the attribute module params).

• /provenance.metadata.v1.MsgWriteScopeRequest

• /provenance.metadata.v1.MsgDeleteScopeRequest

• /provenance.metadata.v1.MsgAddScopeDataAccessRequest

• /provenance.metadata.v1.MsgDeleteScopeDataAccessRequest

• /provenance.metadata.v1.MsgAddScopeOwnerRequest

• /provenance.metadata.v1.MsgDeleteScopeOwnerRequest

• /provenance.metadata.v1.MsgUpdateValueOwnersRequest

• /provenance.metadata.v1.MsgMigrateValueOwnerRequest

• /provenance.metadata.v1.MsgWriteSessionRequest

• /provenance.metadata.v1.MsgWriteRecordRequest

• /provenance.metadata.v1.MsgDeleteRecordRequest

• /provenance.metadata.v1.MsgWriteScopeSpecificationRequest

• /provenance.metadata.v1.MsgDeleteScopeSpecificationRequest

• /provenance.metadata.v1.MsgWriteContractSpecificationRequest

• /provenance.metadata.v1.MsgDeleteContractSpecificationRequest

• /provenance.metadata.v1.MsgAddContractSpecToScopeSpecRequest

• /provenance.metadata.v1.MsgDeleteContractSpecFromScopeSpecRequest

• /provenance.metadata.v1.MsgWriteRecordSpecificationRequest

• /provenance.metadata.v1.MsgDeleteRecordSpecificationRequest

• /provenance.metadata.v1.MsgBindOSLocatorRequest

• /provenance.metadata.v1.MsgDeleteOSLocatorRequest

• /provenance.metadata.v1.MsgModifyOSLocatorRequest

• /provenance.metadata.v1.MsgSetAccountDataRequest

• GET /provenance/metadata/v1/scope/{scope_id}

• GET /provenance/metadata/v1/session/{session_addr}/scope

• GET /provenance/metadata/v1/record/{record_addr}/scope

• GET /provenance/metadata/v1/session/{session_id}

• GET /provenance/metadata/v1/scope/{scope_id}/sessions

• GET /provenance/metadata/v1/scope/{scope_id}/session/{session_id}

• GET /provenance/metadata/v1/record/{record_addr}/session

• GET /provenance/metadata/v1/scope/{scope_id}/record/{record_name}/session

• GET /provenance/metadata/v1/record/{record_addr}

• GET /provenance/metadata/v1/scope/{scope_id}/records

• GET /provenance/metadata/v1/scope/{scope_id}/record/{name}

• GET /provenance/metadata/v1/scope/{scope_id}/session/{session_id}/records

• GET /provenance/metadata/v1/scope/{scope_id}/session/{session_id}/record/{name}

• GET /provenance/metadata/v1/session/{session_id}/records

• GET /provenance/metadata/v1/session/{session_id}/record/{name}

• GET /provenance/metadata/v1/recordspec/{specification_id}

• GET /provenance/metadata/v1/contractspec/{specification_id}/recordspec/{name}

• GitHub Repository: provenance-io/provenance

• Documentation: Provenance Blockchain Developer Portal

protobuf
// Example Query Service Definition
// Source: https://github.com/provenance-io/provenance

service Query {
  // Params queries the parameters of x/metadata module.
  rpc Params(QueryParamsRequest) returns (QueryParamsResponse) {
    option (google.api.http).get = "/provenance/metadata/v1/params";
  }

  // Scope searches for a scope.
  rpc Scope(ScopeRequest) returns (ScopeResponse) {
    option (google.api.http) = {
      get: "/provenance/metadata/v1/scope/{scope_id}"
      additional_bindings: {get: "/provenance/metadata/v1/session/{session_addr}/scope"}
      additional_bindings: {get: "/provenance/metadata/v1/record/{record_addr}/scope"}
    };
  }
}

• Main Repository: provenance-io/provenance

• Metadata Asset Model: provenance-io/metadata-asset-model

• Documentation: Provenance Blockchain Developer Portal

protobuf
// Example from metadata asset model repository
// Source: https://github.com/provenance-io/metadata-asset-model

// Metadata address structure for scopes, sessions, and records
message MetadataAddress {
  bytes scope_id = 1;
  bytes specification_id = 2;
  // Additional fields for metadata addressing
}