Metadata Queries
In this section we describe the queries available for looking up metadata information. All state objects specified by each message are defined within the state section.
Each entry or specification state object is wrapped with an *_id_info message containing information about that state object's address/id.
By default, the *_id_info fields are populated with information about the metadata address(es) involved, but each applicable request has an exclude_id_info flag to cause those field to not be populated in the result.
If a requested entry or specification isn't found, an empty wrapper containing only id info is returned.
- Params
- Scope
- ScopesAll
- Sessions
- SessionsAll
- Records
- RecordsAll
- Ownership
- ValueOwnership
- ScopeSpecification
- ScopeSpecificationsAll
- ContractSpecification
- ContractSpecificationsAll
- RecordSpecificationsForContractSpecification
- RecordSpecification
- RecordSpecificationsAll
- GetByAddr
- OSLocatorParams
- OSLocator
- OSLocatorsByURI
- OSLocatorsByScope
- OSAllLocators
- AccountData
Params
The Params query gets the parameters of the metadata module.
Request
There are no inputs for this query.
Response
Scope
The Scope query gets a scope.
Request
The scope_id, if provided, must either be scope uuid, e.g. 91978ba2-5f35-459a-86a7-feca1b0512e0 or a scope address,
e.g. scope1qzge0zaztu65tx5x5llv5xc9ztsqxlkwel. The session addr, if provided, must be a bech32 session address,
e.g. session1qxge0zaztu65tx5x5llv5xc9zts9sqlch3sxwn44j50jzgt8rshvqyfrjcr. The record_addr, if provided, must be a
bech32 record address, e.g. record1q2ge0zaztu65tx5x5llv5xc9ztsw42dq2jdvmdazuwzcaddhh8gmu3mcze3.
- If only a
scope_idis provided, that scope is returned. - If only a
session_addris provided, the scope containing that session is returned. - If only a
record_addris provided, the scope containing that record is returned. - If more than one of
scope_id,session_addr, andrecord_addrare provided, and they don't refer to the same scope, a bad request is returned.
Providing a session_addr or record_addr does not limit the sessions and records returned (if requested).
Those parameters are only used to find the scope.
By default, sessions and records are not included.
Set include_sessions and/or include_records to true to include sessions and/or records.
Response
ScopesAll
The ScopesAll query gets all scopes.
This query is paginated.
Request
The only input to this query is pagination information.
Response
Sessions
The Sessions query gets sessions.
Request
The scope_id can either be scope uuid, e.g. 91978ba2-5f35-459a-86a7-feca1b0512e0 or a scope address, e.g.
scope1qzge0zaztu65tx5x5llv5xc9ztsqxlkwel. Similarly, the session_id can either be a uuid or session address, e.g.
session1qxge0zaztu65tx5x5llv5xc9zts9sqlch3sxwn44j50jzgt8rshvqyfrjcr. The record_addr, if provided, must be a
bech32 record address, e.g. record1q2ge0zaztu65tx5x5llv5xc9ztsw42dq2jdvmdazuwzcaddhh8gmu3mcze3.
- If only a
scope_idis provided, all sessions in that scope are returned. - If only a
session_idis provided, it must be an address, and that single session is returned. - If the
session_idis a uuid, then either ascope_idorrecord_addrmust also be provided, and that single session is returned. - If only a
record_addris provided, the session containing that record will be returned. - If a
record_nameis provided then either ascope_id,session_idas an address, orrecord_addrmust also be provided, and the session containing that record will be returned.
A bad request is returned if:
- The
session_idis a uuid and is provided without ascope_idorrecord_addr. - A
record_nameis provided without any way to identify the scope (e.g. ascope_id, asession_idas an address, or arecord_addr). - Two or more of
scope_id,session_idas an address, andrecord_addrare provided and don't all refer to the same scope. - A
record_addr(orscope_idandrecord_name) is provided with asession_idand that session does not contain such a record. - A
record_addrandrecord_nameare both provided, but reference different records.
By default, the scope and records are not included.
Set include_scope and/or include_records to true to include the scope and/or records.
Response
SessionsAll
The SessionsAll query gets all sessions.
This query is paginated.
Request
The only input to this query is pagination information.
Response
Records
The Records query gets records.
Request
The record_addr, if provided, must be a bech32 record address, e.g.
record1q2ge0zaztu65tx5x5llv5xc9ztsw42dq2jdvmdazuwzcaddhh8gmu3mcze3. The scope_id can either be scope uuid, e.g.
91978ba2-5f35-459a-86a7-feca1b0512e0 or a scope address, e.g. scope1qzge0zaztu65tx5x5llv5xc9ztsqxlkwel. Similarly,
the session_id can either be a uuid or session address, e.g.
session1qxge0zaztu65tx5x5llv5xc9zts9sqlch3sxwn44j50jzgt8rshvqyfrjcr. The name is the name of the record you're
interested in.
- If only a
record_addris provided, that single record will be returned. - If only a
scope_idis provided, all records in that scope will be returned. - If only a
session_id(or scope_id/session_id), all records in that session will be returned. - If a
nameis provided with ascope_idand/orsession_id, that single record will be returned.
A bad request is returned if:
- The
session_idis a uuid and noscope_idis provided. - There are two or more of
record_addr,session_id, andscope_id, and they don't all refer to the same scope. - A
nameis provided, but not ascope_idand/or asession_id. - A
nameandrecord_addrare provided and the name doesn't match the record_addr.
By default, the scope and sessions are not included.
Set include_scope and/or include_sessions to true to include the scope and/or sessions.
Response
RecordsAll
The RecordsAll query gets all records.
This query is paginated.
Request
The only input to this query is pagination information.
Response
Ownership
The Ownership query gets the ids of scopes owned by an address.
A scope is owned by an address if the address is listed as either an owner, or the value owner.
This query is paginated.
Request
The address should be a bech32 address string.
Response
ValueOwnership
The ValueOwnership query gets gets the ids of scopes that list an address as the value owner.
This query is paginated.
Request
The address should be a bech32 address string.
Response
ScopeSpecification
The ScopeSpecification query gets a scope specification.
Request
The specification_id can either be a uuid, e.g. dc83ea70-eacd-40fe-9adf-1cf6148bf8a2 or a bech32 scope
specification address, e.g. scopespec1qnwg86nsatx5pl56muw0v9ytlz3qu3jx6m.
Response
ScopeSpecificationsAll
The ScopeSpecificationsAll query gets all scope specifications.
This query is paginated.
Request
The only input to this query is pagination information.
Response
ContractSpecification
The ContractSpecification query gets a contract specification.
Request
The specification_id can either be a uuid, e.g. def6bc0a-c9dd-4874-948f-5206e6060a84, a bech32 contract
specification address, e.g. contractspec1q000d0q2e8w5say53afqdesxp2zqzkr4fn, or a bech32 record specification
address, e.g. recspec1qh00d0q2e8w5say53afqdesxp2zw42dq2jdvmdazuwzcaddhh8gmuqhez44. If it is a record specification
address, then the contract specification that contains that record specification is looked up.
By default, the record specifications for this contract specification are not included.
Set include_record_specs to true to include them in the result.
Response
ContractSpecificationsAll
The ContractSpecificationsAll query gets all contract specifications.
This query is paginated.
Request
The only input to this query is pagination information.
Response
RecordSpecificationsForContractSpecification
The RecordSpecificationsForContractSpecification query gets all record specifications for a contract specification.
The only difference between this query and ContractSpecification with include_record_specs = true is that
this query does not return the contract specification.
Request
The specification_id can either be a uuid, e.g. def6bc0a-c9dd-4874-948f-5206e6060a84, a bech32 contract
specification address, e.g. contractspec1q000d0q2e8w5say53afqdesxp2zqzkr4fn, or a bech32 record specification
address, e.g. recspec1qh00d0q2e8w5say53afqdesxp2zw42dq2jdvmdazuwzcaddhh8gmuqhez44. If it is a record specification
address, then the contract specification that contains that record specification is used.
Response
RecordSpecification
The RecordSpecification query gets a record specification.
Request
The specification_id can either be a uuid, e.g. def6bc0a-c9dd-4874-948f-5206e6060a84 or a bech32 contract specification
address, e.g. contractspec1q000d0q2e8w5say53afqdesxp2zqzkr4fn.
It can also be a record specification address, e.g.
recspec1qh00d0q2e8w5say53afqdesxp2zw42dq2jdvmdazuwzcaddhh8gmuqhez44.
The name is the name of the record to look up.
It is required if the specification_id is a uuid or contract specification address.
It is ignored if the specification_id is a record specification address.
Response
RecordSpecificationsAll
The RecordSpecificationsAll query gets all record specifications.
This query is paginated.
Request
The only input to this query is pagination information.
Response
GetByAddr
The GetByAddr query looks up metadata entries and/or specifications for a given list of addresses.
The results of this query are not wrapped with id information like the other queries, and only returns the exact entries requested.
Request
The addrs can contain any valid metadata address bech32 strings.
Response
Any invalid or nonexistent addrs will be in the not_found list.
OSLocatorParams
The OSLocatorParams query gets the parameters of the Object Store Locator sub-module.
Request
There are no inputs for this query.
Response
OSLocator
The OSLocator query gets an Object Store Locator for an address.
Request
The owner should be a bech32 address string.
Response
OSLocatorsByURI
The OSLocatorsByURI query gets the object store locators by URI.
Request
The uri is string the URI to find object store locators for.
Response
OSLocatorsByScope
The OSLocatorsByScope query gets the object store locators for the owners and value owner of a scope.
Request
The scope_id, must either be scope uuid, e.g. 91978ba2-5f35-459a-86a7-feca1b0512e0 or a scope address,
e.g. scope1qzge0zaztu65tx5x5llv5xc9ztsqxlkwel
Response
OSAllLocators
The OSAllLocators query gets all object store locators.
This query is paginated.
Request
The only input to this query is pagination information.
Response
AccountData
The AccountData query gets the account data associated with a scope.
Request
The metadata_addr must be a scope id, e.g. scope1qzge0zaztu65tx5x5llv5xc9ztsqxlkwel.