From 29ce3818f9adc70877fb9357cc83200e663510ce Mon Sep 17 00:00:00 2001 From: Bot Anik <98603954+bot-anik@users.noreply.github.com> Date: Fri, 2 Aug 2024 14:09:01 +0000 Subject: [PATCH 1/2] feat(contracts): add axone-protocol/contracts v6.0.0 contracts documentation --- contracts/axone-cognitarium.md | 2 +- contracts/axone-dataverse.md | 2 +- contracts/axone-law-stone.md | 2 +- contracts/axone-objectarium.md | 2 +- .../version-v6.0.0/axone-cognitarium.md | 879 ++++++++++++++++++ .../version-v6.0.0/axone-dataverse.md | 242 +++++ .../version-v6.0.0/axone-law-stone.md | 139 +++ .../version-v6.0.0/axone-objectarium.md | 528 +++++++++++ .../version-v6.0.0-sidebars.json | 8 + contracts_versions.json | 1 + 10 files changed, 1801 insertions(+), 4 deletions(-) create mode 100644 contracts_versioned_docs/version-v6.0.0/axone-cognitarium.md create mode 100644 contracts_versioned_docs/version-v6.0.0/axone-dataverse.md create mode 100644 contracts_versioned_docs/version-v6.0.0/axone-law-stone.md create mode 100644 contracts_versioned_docs/version-v6.0.0/axone-objectarium.md create mode 100644 contracts_versioned_sidebars/version-v6.0.0-sidebars.json diff --git a/contracts/axone-cognitarium.md b/contracts/axone-cognitarium.md index 0ee9f03d0b0..22f79d21ab5 100644 --- a/contracts/axone-cognitarium.md +++ b/contracts/axone-cognitarium.md @@ -876,4 +876,4 @@ Represents a condition in a [WhereClause]. --- -_Rendered by [Fadroma](https://fadroma.tech) ([@fadroma/schema 1.1.0](https://www.npmjs.com/package/@fadroma/schema)) from `axone-cognitarium.json` (`72125c91d0c7acd2`)_ +_Rendered by [Fadroma](https://fadroma.tech) ([@fadroma/schema 1.1.0](https://www.npmjs.com/package/@fadroma/schema)) from `axone-cognitarium.json` (`d8d7e78708aa2e5c`)_ diff --git a/contracts/axone-dataverse.md b/contracts/axone-dataverse.md index 6d153997a89..2b81d290654 100644 --- a/contracts/axone-dataverse.md +++ b/contracts/axone-dataverse.md @@ -238,5 +238,5 @@ let b = Uint64::from(70u32); assert_eq!(b.u64(), 70); ``` --- -*Rendered by [Fadroma](https://fadroma.tech) ([@fadroma/schema 1.1.0](https://www.npmjs.com/package/@fadroma/schema)) from `axone-dataverse.json` (`6c036ea055d1bbb8`)* +*Rendered by [Fadroma](https://fadroma.tech) ([@fadroma/schema 1.1.0](https://www.npmjs.com/package/@fadroma/schema)) from `axone-dataverse.json` (`70aa81be19dd58f9`)* ```` diff --git a/contracts/axone-law-stone.md b/contracts/axone-law-stone.md index ef54fc4c46e..5d7c3ae1d07 100644 --- a/contracts/axone-law-stone.md +++ b/contracts/axone-law-stone.md @@ -136,4 +136,4 @@ A string containing Base64-encoded data. --- -_Rendered by [Fadroma](https://fadroma.tech) ([@fadroma/schema 1.1.0](https://www.npmjs.com/package/@fadroma/schema)) from `axone-law-stone.json` (`58a14576c3c1d7fe`)_ +_Rendered by [Fadroma](https://fadroma.tech) ([@fadroma/schema 1.1.0](https://www.npmjs.com/package/@fadroma/schema)) from `axone-law-stone.json` (`f8eb198b23eb9c74`)_ diff --git a/contracts/axone-objectarium.md b/contracts/axone-objectarium.md index c40ad2db192..b156a893ac7 100644 --- a/contracts/axone-objectarium.md +++ b/contracts/axone-objectarium.md @@ -525,4 +525,4 @@ A string containing a 128-bit integer in decimal representation. --- -_Rendered by [Fadroma](https://fadroma.tech) ([@fadroma/schema 1.1.0](https://www.npmjs.com/package/@fadroma/schema)) from `axone-objectarium.json` (`2fd2aff74a052bde`)_ +_Rendered by [Fadroma](https://fadroma.tech) ([@fadroma/schema 1.1.0](https://www.npmjs.com/package/@fadroma/schema)) from `axone-objectarium.json` (`3a53bb06f9b58538`)_ diff --git a/contracts_versioned_docs/version-v6.0.0/axone-cognitarium.md b/contracts_versioned_docs/version-v6.0.0/axone-cognitarium.md new file mode 100644 index 00000000000..22f79d21ab5 --- /dev/null +++ b/contracts_versioned_docs/version-v6.0.0/axone-cognitarium.md @@ -0,0 +1,879 @@ +# Cognitarium + +A [CosmWasm](https://cosmwasm.com/) Smart Contract which enables the storage and querying of Semantic data using [RDF (Resource Description Framework)](https://en.wikipedia.org/wiki/Resource_Description_Framework), which represents information as semantic triples. + +## Purpose + +The Smart Contract operates as a [semantic database](https://en.wikipedia.org/wiki/Triplestore), adept at storing and fetching [RDF triples](https://en.wikipedia.org/wiki/Semantic_triple) via semantic queries. It can be deployed on any blockchain within the [Cosmos blockchains](https://cosmos.network/) network, utilizing the [CosmWasm](https://cosmwasm.com/) framework. + +The key features of the contract include: + +**Insertion of RDF Triples:** +This functionality enables the insertion of new data in the form of [RDF triples](https://en.wikipedia.org/wiki/Semantic_triple) onto the blockchain, ensuring secure and tamper-proof storage. The Smart Contract supports inserting these triples in various serialization formats including [RDF/XML](https://en.wikipedia.org/wiki/RDF/XML), [Turtle](https://www.w3.org/TR/turtle/), [N-Triples](https://www.w3.org/TR/n-triples/) and [N-Quads](https://www.w3.org/TR/n-quads/). + +**Removal of RDF Triples:** +This functionality enables the selective deletion of RDF triples from the on-chain store. Users can specify patterns or criteria that identify the triples to be removed, ensuring precise and targeted removal of data. + +**Querying of RDF Triples:** +The Smart Contract provides powerful on-chain querying capabilities, allowing users to retrieve specific RDF triples stored on the blockchain. This is done using a variation of [SPARQL](https://www.w3.org/TR/sparql11-query/), a specialized query language designed for retrieving and manipulating data stored in RDF format. Users can specify their search criteria in the query, and the Smart Contract will return the matching RDF triples, directly accessing the on-chain data. This feature supports various serialization formats for the output, such as Turtle, N-Triples, N-Quads, and RDF/XML, offering flexibility in how the retrieved data is presented and used. + +**Policies of the Store:** +The Smart Contract includes a straightforward yet effective policies functionality to manage the capacity and usage of the on-chain storage effectively. These policies ensure efficient operation and prevent misuse or overuse of the Smart Contract. For instance: + +- Maximum Triples: Caps the total number of RDF triples the store can hold, preventing database overload. +- Storage Size Limit: Sets an upper bound on the store's data size in bytes, managing blockchain resource use. +- Query Size Limit: Restricts the size or complexity of queries to maintain fast and reliable data retrieval. +- Insert Data Limit: Limits the size of data (in bytes) that can be added in a single transaction, ensuring smooth and efficient data insertion. + +## Rationale + +The data preserved in the blockchain holds significant value due to its derivation from a distributed consensus, rendering it a reliable source for decision-making, applicable to both on-chain and off-chain scenarios. + +To effectively utilize this data, it's essential to adopt representation models that cater to diverse requirements. The Smart Contract Cognitarium provides such a model, facilitating the depiction of intricate and evolving semantic connections within a highly interconnected dataset. This approach transforms the data into a Knowledge Graph, enabling an accurate portrayal of existing facts and fostering the generation of new insights. + +## Play + +### Model your data with RDF + +[RDF](https://www.w3.org/RDF/) encodes information in triple structures. The basic structure of an RDF triple is `subject-predicate-object`, much like a simple sentence in the English language. + +1. **Subject**: The subject is the entity or resource the statement is about. It's typically a URI ([Uniform Resource Identifier](https://en.wikipedia.org/wiki/Uniform_Resource_Identifier)) which uniquely identifies a resource. +2. **Predicate**: The predicate (also called a property) is a specific aspect, characteristic, attribute, or relation that describes the subject. It's also typically a URI. +3. **Object**: The object is the value of the attribute defined by the predicate for the subject. It can be a URI or a literal (such as a string or a number) and may also include additional information such as a language tag or a datatype. + +In RDF, **prefixes** are used as a shorthand notation for long URIs to make the data more readable and less verbose. They're similar to namespaces in programming languages. For instance, instead of writing `http://www.w3.org/2001/XMLSchema#integer`, you could declare a prefix `xsd` to represent the `http://www.w3.org/2001/XMLSchema#` URI and then use `xsd:integer`. + +[Turtle (Terse RDF Triple Language)](https://www.w3.org/TR/turtle/) is a syntax that allows RDF to be completely written in a compact and natural text form, with abbreviations for common usage patterns and datatypes. + +Here's an RDF triple written in Turtle format (`.ttl` file): + +```turtle +@prefix ex: . +@prefix xsd: . + +ex:Alice ex:hasAge "30"^^xsd:integer . +``` + +In this example: + +- **`ex:Alice`** is the subject (using `ex` as a prefix for the `http://example.com/stuff/1.0/` URI). +- **`ex:hasAge`** is the predicate. +- **`"30"^^xsd:integer`** is the object, a literal of datatype integer (using **`xsd`** as a prefix for the XML Schema Datatype namespace). + +In the Turtle syntax, the semicolon (**`;`**) is used as a shorthand to reduce verbosity when multiple predicates and objects have the same subject. It allows you to write multiple predicates and objects for the same subject without having to repeat the subject. +The comma (**`,`**) is used as a shorthand for reducing verbosity when the same subject and predicate have multiple objects. + +Suppose we want to express that Alice is 30 years old person, and her email is `alice@example.com`: + +```turtle +@prefix ex: . +@prefix xsd: . + +ex:Alice a ; + ex:hasAge "30"^^xsd:integer ; + ex:hasEmail "alice@example.com" . +``` + +:::tip +The lowercase "a" is a special abbreviation for the RDF type property, which states that a resource is an instance of a particular class. This is essentially equivalent to **``**, and it's used to indicate the type of a resource. +::: + +The same RDF triple can be expressed in RDF/XML format (`.rdf.xml` file): + +```xml + + + + 30 + alice@example.com + + +``` + +### Instantiate the Smart Contract + +Let's initiate a new instance of Smart Contract and input some RDF triples into it. The `axone-cognitarium` can be set up in the following manner. Please consult the schema for additional details regarding configuration settings. + +```bash +axoned tx wasm instantiate $CODE_ID \ + --from $ADDR \ + --label "my-rdf-storage" \ + --admin $ADMIN_ADDR \ + --gas 1000000 \ + '{}' +``` + +:::tip +You can provide some limitation parameters to restrict usage for both execute and query messages. For instance, you can set a maximum number of triples that can be stored in the smart contract, or a maximum size of data that can be inserted in a single transaction. + +The default values are: + +```json +{ + "limits": { + "max_byte_size": "340282366920938463463374607431768211455", + "max_insert_data_byte_size": "340282366920938463463374607431768211455", + "max_insert_data_triple_count": "340282366920938463463374607431768211455", + "max_query_limit": 30, + "max_query_variable_count": 30, + "max_triple_byte_size": "340282366920938463463374607431768211455", + "max_triple_count": "340282366920938463463374607431768211455" + } +} +``` + +::: + +### Insert RDF triples + +To insert RDF triples, you need to send an `InsertData` message through the `cognitarium` smart contract you've already instantiated. For this operation, your inputs should include the data of the triples, encoded in [base64](https://en.wikipedia.org/wiki/Base64), as well as the format. The format options available are: + +- `turtle` (default) +- `rdf_xml` +- `n_triples` +- `n_quads` + +Let's consider the following example of data in Turtle format, contained within a file named `data.ttl`. It describes a small network of people and their relationships, such as name, title, and whom they know. + +```turtle +@prefix : . +@prefix foaf: . +@prefix schema: . + +:alice a foaf:Person ; + foaf:name "Alice" ; + foaf:knows :bob ; + schema:email "alice@example.org" . + +:bob a foaf:Person ; + foaf:name "Bob" ; + foaf:knows :alice, :carol ; + schema:jobTitle "Software Developer" . + +:carol a foaf:Person ; + foaf:name "Carol" ; + schema:jobTitle "Data Scientist" ; + foaf:knows :bob . +``` + +You can insert this data into the `cognitarium` smart contract with the following command: + +```bash +axoned tx wasm execute $CONTRACT_ADDR \ + --from axone1cu9wzlcyyxpek20jaqfwzu3llzjgx34cqf94yj \ + --gas 10000000 \ + "{\"insert_data\":{\"format\": \"turtle\", \"data\": \"$(cat data.ttl | base64 | tr -d '\n\r')\"}}" +``` + +With the transaction hash we can query the number of triples inserted: + +```bash +axoned query tx $TX_HASH -ojson | + jq -r '.events[] | select(.type == "wasm") | .attributes[] | select(.key == "triple_count") | .value' +``` + +### Query RDF triples + +Now that we've populated the axone-cognitarium with several triples, let's explore how to retrieve this data. We can utilize the Select query message for this purpose. If you're familiar with [SPARQL](https://www.w3.org/TR/rdf-sparql-query/), you'll find the process quite intuitive. + +A `select` query on a `cognitarium` instance enables you to fetch and filter the data. The `select.query` JSON should contain the following: + +- `prefixes` array: to declare a `prefix` and its related `namespace` +- `limit`: the number of elements to return +- `where`: filters and variable declarations +- `select` array: all `variable` names you declared in `where` you want to get + +`where` should be an array of elements specifying triple filterings. You have to specify `subject`, `predicate` and `object` as a `variable`, or, alternatively, a `prefixed` or `full` `named_node`. + +`object` can also be a `simple` `literal`. + +The following query will select all the triples `subject`, `predicate` and `object` from the store: + +```json +{ + "select": { + "query": { + "prefixes": [], + "select": [ + { + "variable": "subject" + }, + { + "variable": "predicate" + }, + { + "variable": "object" + } + ], + "where": [ + { + "simple": { + "triple_pattern": { + "subject": { + "variable": "subject" + }, + "predicate": { + "variable": "predicate" + }, + "object": { + "variable": "object" + } + } + } + } + ], + "limit": null + } + } +} +``` + +It's semantically equivalent to the following SPARQL query: + +```sparql +SELECT ?subject ?predicate ?object +WHERE { + ?subject ?predicate ?object +} +``` + +This query can be executed on the cognitarium smart contract using the command below: + +```bash +axoned query wasm contract-state smart $CONTRACT_ADDR \ + '{"select":{"query":{"prefixes":[],"select":[{"variable":"subject"},{"variable":"predicate"},{"variable":"object"}],"where":[{"simple":{"triple_pattern":{"subject":{"variable":"subject"},"predicate":{"variable":"predicate"},"object":{"variable":"object"}}}}],"limit":null}}}' +``` + +Now, let's try something more interresting. Let's retrieve the names of people and their job titles, but only for those who know at least one other person in the network. This query introduces filtering based on relationships. + +Here's the query: + +```json +{ + "select": { + "query": { + "prefixes": [ + { "foaf": "http://xmlns.com/foaf/0.1/" }, + { "schema": "http://schema.org/" } + ], + "select": [ + { + "variable": "personName" + }, + { + "variable": "jobTitle" + } + ], + "where": [ + { + "simple": { + "triple_pattern": { + "subject": { + "variable": "person" + }, + "predicate": { + "node": { + "named_node": { + "full": "http://www.w3.org/1999/02/22-rdf-syntax-ns#type" + } + } + }, + "object": { + "node": { + "named_node": { + "prefixed": "foaf:Person" + } + } + } + } + } + }, + { + "simple": { + "triple_pattern": { + "subject": { + "variable": "person" + }, + "predicate": { + "node": { + "named_node": { + "prefixed": "foaf:Name" + } + } + }, + "object": { + "variable": "personName" + } + } + } + }, + { + "simple": { + "triple_pattern": { + "subject": { + "variable": "person" + }, + "predicate": { + "node": { + "named_node": { + "prefixed": "schema:jobTitle" + } + } + }, + "object": { + "variable": "jobTitle" + } + } + } + }, + { + "simple": { + "triple_pattern": { + "subject": { + "variable": "person" + }, + "predicate": { + "node": { + "named_node": { + "prefixed": "foaf:knows" + } + } + }, + "object": { + "variable": "knownPerson" + } + } + } + } + ], + "limit": null + } + } +} +``` + +It's semantically equivalent to the following SPARQL query: + +```sparql +PREFIX foaf: +PREFIX schema: + +SELECT ?personName ?jobTitle +WHERE { + ?person a foaf:Person . + ?person foaf:name ?personName . + ?person schema:jobTitle ?jobTitle . + ?person foaf:knows ?knownPerson . +} +``` + +This query can be executed on the cognitarium smart contract using the command below: + +```bash +axoned query wasm contract-state smart $CONTRACT_ADDR \ + '{"select":{"query":{"prefixes":[{"foaf":"http://xmlns.com/foaf/0.1/"},{"schema":"http://schema.org/"}],"select":[{"variable":"personName"},{"variable":"jobTitle"}],"where":[{"simple":{"triple_pattern":{"subject":{"variable":"person"},"predicate":{"node":{"named_node":{"full":"http://www.w3.org/1999/02/22-rdf-syntax-ns#type"}}},"object":{"node":{"named_node":{"prefixed":"foaf:Person"}}}}}},{"simple":{"triple_pattern":{"subject":{"variable":"person"},"predicate":{"node":{"named_node":{"prefixed":"foaf:Name"}}},"object":{"variable":"personName"}}}},{"simple":{"triple_pattern":{"subject":{"variable":"person"},"predicate":{"node":{"named_node":{"prefixed":"schema:jobTitle"}}},"object":{"variable":"jobTitle"}}}},{"simple":{"triple_pattern":{"subject":{"variable":"person"},"predicate":{"node":{"named_node":{"prefixed":"foaf:knows"}}},"object":{"variable":"knownPerson"}}}}],"limit":null}}}' +``` + +## InstantiateMsg + +Instantiate message + +| parameter | description | +| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `limits` | **[StoreLimitsInput](#storelimitsinput)**. Limitations regarding store usage. | +| `limits.max_byte_size` | **[Uint128](#uint128)**. The maximum number of bytes the store can contain. The size of a triple is counted as the sum of the size of its subject, predicate and object, including the size of data types and language tags if any. Default to [Uint128::MAX] if not set, which can be considered as no limit.
**Default:** `"340282366920938463463374607431768211455"` | +| `limits.max_insert_data_byte_size` | **[Uint128](#uint128)**. The maximum number of bytes an insert data query can contain. Default to [Uint128::MAX] if not set, which can be considered as no limit.
**Default:** `"340282366920938463463374607431768211455"` | +| `limits.max_insert_data_triple_count` | **[Uint128](#uint128)**. The maximum number of triples an insert data query can contain (after parsing). Default to [Uint128::MAX] if not set, which can be considered as no limit.
**Default:** `"340282366920938463463374607431768211455"` | +| `limits.max_query_limit` | **integer**. The maximum limit of a query, i.e. the maximum number of triples returned by a select query. Default to 30 if not set.
**Default:** `30` | +| `limits.max_query_variable_count` | **integer**. The maximum number of variables a query can select. Default to 30 if not set.
**Default:** `30` | +| `limits.max_triple_byte_size` | **[Uint128](#uint128)**. The maximum number of bytes the store can contain for a single triple. The size of a triple is counted as the sum of the size of its subject, predicate and object, including the size of data types and language tags if any. The limit is used to prevent storing very large triples, especially literals. Default to [Uint128::MAX] if not set, which can be considered as no limit.
**Default:** `"340282366920938463463374607431768211455"` | +| `limits.max_triple_count` | **[Uint128](#uint128)**. The maximum number of triples the store can contain. Default to [Uint128::MAX] if not set, which can be considered as no limit.
**Default:** `"340282366920938463463374607431768211455"` | + +## ExecuteMsg + +Execute messages + +### ExecuteMsg::InsertData + +Insert the data as RDF triples in the store. For already existing triples it acts as no-op. + +Only the smart contract owner (i.e. the address who instantiated it) is authorized to perform this action. + +| parameter | description | +| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `insert_data` | _(Required.) _ **object**. | +| `insert_data.data` | _(Required.) _ **[Binary](#binary)**. The data to insert. The data must be serialized in the format specified by the `format` field. And the data are subject to the limitations defined by the `limits` specified at contract instantiation. | +| `insert_data.format` | **[DataFormat](#dataformat)\|null**. The data format in which the triples are serialized. If not provided, the default format is [Turtle](https://www.w3.org/TR/turtle/) format. | + +### ExecuteMsg::DeleteData + +Delete the data (RDF triples) from the store matching the patterns defined by the provided query. For non-existing triples it acts as no-op. + +Example: `json { "prefixes": [ { "prefix": "foaf", "namespace": "http://xmlns.com/foaf/0.1/" } ], "delete": [ { "subject": { "variable": "s" }, "predicate": { "variable": "p" }, "object": { "variable": "o" } } ], "where": [ { "simple": { "triplePattern": { "subject": { "variable": "s" }, "predicate": { "namedNode": {"prefixed": "foaf:givenName"} }, "object": { "literal": { "simple": "Myrddin" } } } } }, { "simple": { "triplePattern": { "subject": { "variable": "s" }, "predicate": { "variable": "p" }, "object": { "variable": "o" } } } } ] ` + +Only the smart contract owner (i.e. the address who instantiated it) is authorized to perform this action. + +| parameter | description | +| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `delete_data` | _(Required.) _ **object**. | +| `delete_data.delete` | _(Required.) _ **Array<[TripleDeleteTemplate](#tripledeletetemplate)>**. Specifies the specific triple templates to delete. If nothing is provided, the patterns from the `where` clause are used for deletion. | +| `delete_data.prefixes` | _(Required.) _ **Array<[Prefix](#prefix)>**. The prefixes used in the operation. | +| `delete_data.where` | _(Required.) _ **Array<[WhereCondition](#wherecondition)>**. Defines the patterns that data (RDF triples) should match in order for it to be considered for deletion. | + +## QueryMsg + +Query messages + +### QueryMsg::Store + +Returns information about the triple store. + +| parameter | description | +| --------- | -------------------------- | +| `store` | _(Required.) _ **object**. | + +### QueryMsg::Select + +Returns the resources matching the criteria defined by the provided query. + +| parameter | description | +| -------------- | --------------------------------------------------------------------- | +| `select` | _(Required.) _ **object**. | +| `select.query` | _(Required.) _ **[SelectQuery](#selectquery)**. The query to execute. | + +### QueryMsg::Describe + +Returns a description of the resource identified by the provided IRI as a set of RDF triples serialized in the provided format. + +| parameter | description | +| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `describe` | _(Required.) _ **object**. | +| `describe.format` | **[DataFormat](#dataformat)\|null**. The format in which the triples are serialized. If not provided, the default format is [Turtle](https://www.w3.org/TR/turtle/) format. | +| `describe.query` | _(Required.) _ **[DescribeQuery](#describequery)**. The query to execute. | + +### QueryMsg::Construct + +Returns the resources matching the criteria defined by the provided query as a set of RDF triples serialized in the provided format. + +| parameter | description | +| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `construct` | _(Required.) _ **object**. | +| `construct.format` | **[DataFormat](#dataformat)\|null**. The format in which the triples are serialized. If not provided, the default format is [Turtle](https://www.w3.org/TR/turtle/) format. | +| `construct.query` | _(Required.) _ **[ConstructQuery](#constructquery)**. The query to execute. | + +## Responses + +### construct + +Represents the response of a [QueryMsg::Construct] query. + +| property | description | +| -------- | ---------------------------------------------------------------------------------- | +| `data` | _(Required.) _ **[Binary](#binary)**. The data serialized in the specified format. | +| `format` | _(Required.) _ **[DataFormat](#dataformat)**. The format of the data. | + +### describe + +Represents the response of a [QueryMsg::Describe] query. + +| property | description | +| -------- | ---------------------------------------------------------------------------------- | +| `data` | _(Required.) _ **[Binary](#binary)**. The data serialized in the specified format. | +| `format` | _(Required.) _ **[DataFormat](#dataformat)**. The format of the data. | + +### select + +Represents the response of a [QueryMsg::Select] query. + +| property | description | +| ------------------ | --------------------------------------------------------------------------------------------------------------- | +| `head` | _(Required.) _ **[Head](#head)**. The head of the response, i.e. the set of variables mentioned in the results. | +| `head.vars` | **Array<string>**. The variables selected in the query. | +| `results` | _(Required.) _ **[Results](#results)**. The results of the select query. | +| `results.bindings` | **Array<object>**. The bindings of the results. | + +### store + +Contains information related to triple store. + +| property | description | +| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `limits` | _(Required.) _ **[StoreLimits](#storelimits)**. The store limits. | +| `limits.max_byte_size` | **[Uint128](#uint128)**. The maximum number of bytes the store can contain. The size of a triple is counted as the sum of the size of its subject, predicate and object, including the size of data types and language tags if any. | +| `limits.max_insert_data_byte_size` | **[Uint128](#uint128)**. The maximum number of bytes an insert data query can contain. | +| `limits.max_insert_data_triple_count` | **[Uint128](#uint128)**. The maximum number of triples an insert data query can contain (after parsing). | +| `limits.max_query_limit` | **integer**. The maximum limit of a query, i.e. the maximum number of triples returned by a select query. | +| `limits.max_query_variable_count` | **integer**. The maximum number of variables a query can select. | +| `limits.max_triple_byte_size` | **[Uint128](#uint128)**. The maximum number of bytes the store can contain for a single triple. The size of a triple is counted as the sum of the size of its subject, predicate and object, including the size of data types and language tags if any. The limit is used to prevent storing very large triples, especially literals. | +| `limits.max_triple_count` | **[Uint128](#uint128)**. The maximum number of triples the store can contain. | +| `owner` | _(Required.) _ **string**. The store owner. | +| `stat` | _(Required.) _ **[StoreStat](#storestat)**. The store current usage. | +| `stat.byte_size` | **[Uint128](#uint128)**. The total triple size in the store, in bytes. | +| `stat.namespace_count` | **[Uint128](#uint128)**. The total number of IRI namespace present in the store. | +| `stat.triple_count` | **[Uint128](#uint128)**. The total number of triple present in the store. | + +## Definitions + +### Binary + +A string containing Base64-encoded data. + +| type | +| ----------- | +| **string**. | + +### BlankNode + +An RDF [blank node](https://www.w3.org/TR/rdf11-concepts/#dfn-blank-node). + +| property | description | +| ------------ | -------------------------- | +| `blank_node` | _(Required.) _ **string**. | + +### ConstructQuery + +Represents a CONSTRUCT query over the triple store, allowing to retrieve a set of triples serialized in a specific format. + +| property | description | +| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `construct` | _(Required.) _ **Array<[TripleConstructTemplate](#tripleconstructtemplate)>**. The triples to construct. If nothing is provided, the patterns from the `where` clause are used for construction. | +| `prefixes` | _(Required.) _ **Array<[Prefix](#prefix)>**. The prefixes used in the query. | +| `where` | _(Required.) _ **Array<[WhereCondition](#wherecondition)>**. The WHERE clause. This clause is used to specify the triples to construct using variable bindings. | + +### DataFormat + +Represents the format in which the data are serialized, for example when returned by a query or when inserted in the store. + +| variant | description | +| ----------------------- | --------------------------------------------------------------------------------------------- | +| [RDF XML](#rdf-xml) | **string**: `rdf_xml`. Output in [RDF/XML](https://www.w3.org/TR/rdf-syntax-grammar/) format. | +| [Turtle](#turtle) | **string**: `turtle`. Output in [Turtle](https://www.w3.org/TR/turtle/) format. | +| [N-Triples](#n-triples) | **string**: `n_triples`. Output in [N-Triples](https://www.w3.org/TR/n-triples/) format. | +| [N-Quads](#n-quads) | **string**: `n_quads`. Output in [N-Quads](https://www.w3.org/TR/n-quads/) format. | + +### DescribeQuery + +Represents a DESCRIBE query over the triple store, allowing to retrieve a description of a resource as a set of triples serialized in a specific format. + +| property | description | +| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `prefixes` | _(Required.) _ **Array<[Prefix](#prefix)>**. The prefixes used in the query. | +| `resource` | _(Required.) _ **[VarOrNamedNode](#varornamednode)**. The resource to describe given as a variable or a node. | +| `where` | _(Required.) _ **Array<[WhereCondition](#wherecondition)>**. The WHERE clause. This clause is used to specify the resource identifier to describe using variable bindings. | + +### Full + +A full IRI. + +| property | description | +| -------- | -------------------------- | +| `full` | _(Required.) _ **string**. | + +### Head + +Represents the head of a [SelectResponse]. + +| property | description | +| -------- | ---------------------------------------------------------------------------- | +| `vars` | _(Required.) _ **Array<string>**. The variables selected in the query. | + +### IRI + +Represents an IRI. + +| variant | description | +| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [Prefixed](#prefixed) | **object**. An IRI prefixed with a prefix. The prefixed IRI is expanded to a full IRI using the prefix definition specified in the query. For example, the prefixed IRI `rdf:type` is expanded to `http://www.w3.org/1999/02/22-rdf-syntax-ns#type`. | +| [Full](#full) | **object**. A full IRI. | + +### LanguageTaggedString + +A [language-tagged string](https://www.w3.org/TR/rdf11-concepts/#dfn-language-tagged-string) + +| property | description | +| --------------------------------- | ------------------------------------------------------------------------------------------------------ | +| `language_tagged_string` | _(Required.) _ **object**. | +| `language_tagged_string.language` | _(Required.) _ **string**. The [language tag](https://www.w3.org/TR/rdf11-concepts/#dfn-language-tag). | +| `language_tagged_string.value` | _(Required.) _ **string**. The [lexical form](https://www.w3.org/TR/rdf11-concepts/#dfn-lexical-form). | + +### Literal + +An RDF [literal](https://www.w3.org/TR/rdf11-concepts/#dfn-literal). + +| variant | description | +| --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | +| [Simple](#simple) | **object**. A [simple literal](https://www.w3.org/TR/rdf11-concepts/#dfn-simple-literal) without datatype or language form. | +| [LanguageTaggedString](#languagetaggedstring) | **object**. A [language-tagged string](https://www.w3.org/TR/rdf11-concepts/#dfn-language-tagged-string) | +| [TypedValue](#typedvalue) | **object**. A value with a datatype. | + +### N-Quads + +Output in [N-Quads](https://www.w3.org/TR/n-quads/) format. + +| literal | +| ----------- | +| `"n_quads"` | + +### N-Triples + +Output in [N-Triples](https://www.w3.org/TR/n-triples/) format. + +| literal | +| ------------- | +| `"n_triples"` | + +### NamedNode + +An RDF [IRI](https://www.w3.org/TR/rdf11-concepts/#dfn-iri). + +| property | description | +| ------------ | -------------------------------------------------------- | +| `named_node` | _(Required.) _ **[Prefixed](#prefixed)\|[Full](#full)**. | + +### Node + +Represents either an IRI (named node) or a blank node. + +| variant | description | +| ----------------------- | -------------------------------------------------------------------------------------- | +| [NamedNode](#namednode) | **object**. An RDF [IRI](https://www.w3.org/TR/rdf11-concepts/#dfn-iri). | +| [BlankNode](#blanknode) | **object**. An RDF [blank node](https://www.w3.org/TR/rdf11-concepts/#dfn-blank-node). | + +### Prefix + +Represents a prefix, i.e. a shortcut for a namespace used in a query. + +| property | description | +| ----------- | -------------------------------------------------------------------- | +| `namespace` | _(Required.) _ **string**. The namespace associated with the prefix. | +| `prefix` | _(Required.) _ **string**. The prefix. | + +### Prefixed + +An IRI prefixed with a prefix. The prefixed IRI is expanded to a full IRI using the prefix definition specified in the query. For example, the prefixed IRI `rdf:type` is expanded to `http://www.w3.org/1999/02/22-rdf-syntax-ns#type`. + +| property | description | +| ---------- | -------------------------- | +| `prefixed` | _(Required.) _ **string**. | + +### RDF XML + +Output in [RDF/XML](https://www.w3.org/TR/rdf-syntax-grammar/) format. + +| literal | +| ----------- | +| `"rdf_xml"` | + +### Results + +Represents the results of a [SelectResponse]. + +| property | description | +| ---------- | -------------------------------------------------------------------- | +| `bindings` | _(Required.) _ **Array<object>**. The bindings of the results. | + +### SelectItem + +Represents an item to select in a [SelectQuery]. + +| variant | description | +| --------------------- | ---------------------------------- | +| [Variable](#variable) | **object**. Represents a variable. | + +### SelectQuery + +Represents a SELECT query over the triple store, allowing to select variables to return and to filter the results. + +| property | description | +| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `limit` | **integer\|null**. The maximum number of results to return. If `None`, there is no limit. Note: the value of the limit cannot exceed the maximum query limit defined in the store limitations. | +| `prefixes` | _(Required.) _ **Array<[Prefix](#prefix)>**. The prefixes used in the query. | +| `select` | _(Required.) _ **Array<[SelectItem](#selectitem)>**. The items to select. Note: the number of items to select cannot exceed the maximum query variable count defined in the store limitations. | +| `where` | _(Required.) _ **Array<[WhereCondition](#wherecondition)>**. The WHERE clause. If `None`, there is no WHERE clause, i.e. all triples are returned without filtering. | + +### Simple + +A [simple literal](https://www.w3.org/TR/rdf11-concepts/#dfn-simple-literal) without datatype or language form. + +| property | description | +| -------- | -------------------------- | +| `simple` | _(Required.) _ **string**. | + +### SimpleWhereCondition + +Represents a simple condition in a [WhereCondition]. + +| variant | description | +| ------------------------------- | ----------------------------------------------------------------------------------------------------------------- | +| [TriplePattern](#triplepattern) | **object**. Represents a triple pattern, i.e. a condition on a triple based on its subject, predicate and object. | + +### StoreLimits + +Contains limitations regarding store usages. + +| property | description | +| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `max_byte_size` | _(Required.) _ **[Uint128](#uint128)**. The maximum number of bytes the store can contain. The size of a triple is counted as the sum of the size of its subject, predicate and object, including the size of data types and language tags if any. | +| `max_insert_data_byte_size` | _(Required.) _ **[Uint128](#uint128)**. The maximum number of bytes an insert data query can contain. | +| `max_insert_data_triple_count` | _(Required.) _ **[Uint128](#uint128)**. The maximum number of triples an insert data query can contain (after parsing). | +| `max_query_limit` | _(Required.) _ **integer**. The maximum limit of a query, i.e. the maximum number of triples returned by a select query. | +| `max_query_variable_count` | _(Required.) _ **integer**. The maximum number of variables a query can select. | +| `max_triple_byte_size` | _(Required.) _ **[Uint128](#uint128)**. The maximum number of bytes the store can contain for a single triple. The size of a triple is counted as the sum of the size of its subject, predicate and object, including the size of data types and language tags if any. The limit is used to prevent storing very large triples, especially literals. | +| `max_triple_count` | _(Required.) _ **[Uint128](#uint128)**. The maximum number of triples the store can contain. | + +### StoreLimitsInput + +Contains requested limitations regarding store usages. + +| property | description | +| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `max_byte_size` | **[Uint128](#uint128)**. The maximum number of bytes the store can contain. The size of a triple is counted as the sum of the size of its subject, predicate and object, including the size of data types and language tags if any. Default to [Uint128::MAX] if not set, which can be considered as no limit. | +| `max_insert_data_byte_size` | **[Uint128](#uint128)**. The maximum number of bytes an insert data query can contain. Default to [Uint128::MAX] if not set, which can be considered as no limit. | +| `max_insert_data_triple_count` | **[Uint128](#uint128)**. The maximum number of triples an insert data query can contain (after parsing). Default to [Uint128::MAX] if not set, which can be considered as no limit. | +| `max_query_limit` | **integer**. The maximum limit of a query, i.e. the maximum number of triples returned by a select query. Default to 30 if not set. | +| `max_query_variable_count` | **integer**. The maximum number of variables a query can select. Default to 30 if not set. | +| `max_triple_byte_size` | **[Uint128](#uint128)**. The maximum number of bytes the store can contain for a single triple. The size of a triple is counted as the sum of the size of its subject, predicate and object, including the size of data types and language tags if any. The limit is used to prevent storing very large triples, especially literals. Default to [Uint128::MAX] if not set, which can be considered as no limit. | +| `max_triple_count` | **[Uint128](#uint128)**. The maximum number of triples the store can contain. Default to [Uint128::MAX] if not set, which can be considered as no limit. | + +### StoreStat + +Contains usage information about the triple store. + +| property | description | +| ----------------- | ----------------------------------------------------------------------------------------------- | +| `byte_size` | _(Required.) _ **[Uint128](#uint128)**. The total triple size in the store, in bytes. | +| `namespace_count` | _(Required.) _ **[Uint128](#uint128)**. The total number of IRI namespace present in the store. | +| `triple_count` | _(Required.) _ **[Uint128](#uint128)**. The total number of triple present in the store. | + +### TripleConstructTemplate + +Represents a triple template to be forged for a construct query. + +| property | description | +| ----------- | ----------------------------------------------------------------------------------------------- | +| `object` | _(Required.) _ **[VarOrNodeOrLiteral](#varornodeorliteral)**. The object of the triple pattern. | +| `predicate` | _(Required.) _ **[VarOrNamedNode](#varornamednode)**. The predicate of the triple pattern. | +| `subject` | _(Required.) _ **[VarOrNode](#varornode)**. The subject of the triple pattern. | + +### TripleDeleteTemplate + +Represents a triple template to be deleted. + +| property | description | +| ----------- | --------------------------------------------------------------------------------------------------------- | +| `object` | _(Required.) _ **[VarOrNamedNodeOrLiteral](#varornamednodeorliteral)**. The object of the triple pattern. | +| `predicate` | _(Required.) _ **[VarOrNamedNode](#varornamednode)**. The predicate of the triple pattern. | +| `subject` | _(Required.) _ **[VarOrNamedNode](#varornamednode)**. The subject of the triple pattern. | + +### TriplePattern + +Represents a triple pattern in a [SimpleWhereCondition]. + +| property | description | +| ----------- | ----------------------------------------------------------------------------------------------- | +| `object` | _(Required.) _ **[VarOrNodeOrLiteral](#varornodeorliteral)**. The object of the triple pattern. | +| `predicate` | _(Required.) _ **[VarOrNamedNode](#varornamednode)**. The predicate of the triple pattern. | +| `subject` | _(Required.) _ **[VarOrNode](#varornode)**. The subject of the triple pattern. | + +### Turtle + +Output in [Turtle](https://www.w3.org/TR/turtle/) format. + +| literal | +| ---------- | +| `"turtle"` | + +### TypedValue + +A value with a datatype. + +| property | description | +| ---------------------- | ----------------------------------------------------------------------------------------------------------- | +| `typed_value` | _(Required.) _ **object**. | +| `typed_value.datatype` | _(Required.) _ **[IRI](#iri)**. The [datatype IRI](https://www.w3.org/TR/rdf11-concepts/#dfn-datatype-iri). | +| `typed_value.value` | _(Required.) _ **string**. The [lexical form](https://www.w3.org/TR/rdf11-concepts/#dfn-lexical-form). | + +### URI + +Represents an IRI. + +| property | description | +| -------- | ----------------------------------------------------- | +| `type` | _(Required.) _ **string**. | +| `value` | _(Required.) _ **[IRI](#iri)**. The value of the IRI. | + +### Uint128 + +A string containing a 128-bit integer in decimal representation. + +| type | +| ----------- | +| **string**. | + +### Value + +| variant | description | +| ----------------------- | ---------------------------------------------------------------------------------- | +| [URI](#uri) | **object**. Represents an IRI. | +| [Literal](#literal) | **object**. Represents a literal S with optional language tag L or datatype IRI D. | +| [BlankNode](#blanknode) | **object**. Represents a blank node. | + +### VarOrNamedNode + +Represents either a variable or a named node (IRI). + +| variant | description | +| ----------------------- | ------------------------------------------------------------------------ | +| [Variable](#variable) | **object**. A variable. | +| [NamedNode](#namednode) | **object**. An RDF [IRI](https://www.w3.org/TR/rdf11-concepts/#dfn-iri). | + +### VarOrNamedNodeOrLiteral + +Represents either a variable, a named node or a literal. + +| variant | description | +| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | +| [Variable](#variable) | **object**. A variable. | +| [NamedNode](#namednode) | **object**. An RDF [IRI](https://www.w3.org/TR/rdf11-concepts/#dfn-iri). | +| [Literal](#literal) | **object**. An RDF [literal](https://www.w3.org/TR/rdf11-concepts/#dfn-literal), i.e. a simple literal, a language-tagged string or a typed value. | + +### VarOrNode + +Represents either a variable or a node. + +| variant | description | +| --------------------- | ------------------------------------------------ | +| [Variable](#variable) | **object**. A variable. | +| [Node](#node) | **object**. A node, i.e. an IRI or a blank node. | + +### VarOrNodeOrLiteral + +Represents either a variable, a node or a literal. + +| variant | description | +| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | +| [Variable](#variable) | **object**. A variable. | +| [Node](#node) | **object**. A node, i.e. an IRI or a blank node. | +| [Literal](#literal) | **object**. An RDF [literal](https://www.w3.org/TR/rdf11-concepts/#dfn-literal), i.e. a simple literal, a language-tagged string or a typed value. | + +### Variable + +A variable. + +| property | description | +| ---------- | -------------------------- | +| `variable` | _(Required.) _ **string**. | + +### WhereCondition + +Represents a condition in a [WhereClause]. + +| variant | description | +| ----------------- | ------------------------------------------ | +| [Simple](#simple) | **object**. Represents a simple condition. | + +--- + +_Rendered by [Fadroma](https://fadroma.tech) ([@fadroma/schema 1.1.0](https://www.npmjs.com/package/@fadroma/schema)) from `axone-cognitarium.json` (`d8d7e78708aa2e5c`)_ diff --git a/contracts_versioned_docs/version-v6.0.0/axone-dataverse.md b/contracts_versioned_docs/version-v6.0.0/axone-dataverse.md new file mode 100644 index 00000000000..2b81d290654 --- /dev/null +++ b/contracts_versioned_docs/version-v6.0.0/axone-dataverse.md @@ -0,0 +1,242 @@ +# Dataverse + +## Overview + +The `dataverse` smart contract is responsible for overseeing and managing the Dataverse. + +## Dataverse + +The Dataverse is an ever-expanding universe that encompasses a wide range of digital resources. These include datasets, data processing algorithms, ML algorithm, storage resources, computational resources, identity management solutions, orchestration engines, oracles, and many other resources recorded on the blockchain. + +When the smart contract is instantiated, it creates a Dataverse instance. This instance is separated and isolated from any pre-existing ones, and as many dataverse instances as required can be created. + +## Zones + +Zones within the Dataverse represent distinct areas or domains where specific governance rules and policies are applied. These Zones are conceptual frameworks created to manage and organize resources under a unified set of regulations and permissions. + +Each Zone is defined by its unique identity and set of governing rules, which dictate how resources within it can be accessed, used, and shared. This approach allows for granular control over different segments of the Dataverse, catering to various requirements and use cases. By managing these Zones, the dataverse smart contract ensures that resources are utilized in compliance with the defined policies and consents, thereby maintaining order and integrity within the Dataverse. + +## Resources + +In the context of the Dataverse, Resources refer to a broad category of digital entities, which include Services and Digital Resources. + +- **Digital Resources**: This category extends to various digital entities such as datasets, algorithms, machine learning models, and other digital assets. Like Services, Digital Resources are identified by a URI in conjunction with the Service responsible for their provision. + +- **Services**: These are network-accessible functionalities like REST APIs, gRPC services, and other similar offerings. Each Service in the Dataverse is uniquely identified by its Uniform Resource Identifier (URI) and is associated with a specific Registrar responsible for its registration and management. + +## Decentralized Identifiers (DID) + +Decentralized Identifiers (DID) are a foundational element in the Dataverse, serving as unique, persistent, and globally resolvable identifiers that are fully under the control of the DID subject, which could be an individual, organization, or a any kind of resource (dataset, +algorithm, nft, ML algorithm). + +DIDs play a crucial role in the Dataverse by facilitating a trustable and interoperable identity mechanism. They enable the establishment of a verifiable and self-sovereign identity for resources, services, and entities within the ecosystem. + +## Claims + +Claims in the Dataverse context are assertions or statements made about a Resource identified by a DID. + +Claims play a pivotal role in the governance framework of the Dataverse. By leveraging knowledge derived from verifiable credentials, the governances established by Zones can evaluate the fulfilment of specific rules and compliance. This evaluation is critical in ensuring that the resources within the Dataverse adhere to the established norms, policies, and requirements. + +Claims are submitted in the form of [Verifiable Presentations (VPs)](https://www.w3.org/TR/vc-data-model/#presentations), which are aggregations of one or more [Verifiable Credentials (VCs)](https://www.w3.org/TR/vc-data-model/#what-is-a-verifiable-credential). + +## Dependencies + +Given its role and status, this smart contract serves as the primary access point for the AXONE protocol to manage all on-chain stored resources. To fulfill its tasks, the smart contract relies on other smart contracts within the AXONE ecosystem. Notably, it uses the `Cognitarium` smart contract for persisting the Dataverse representation in an ontological form and the `Law Stone` smart contract to establish governance rules. + +## InstantiateMsg + +`InstantiateMsg` is used to initialize a new instance of the dataverse. + +| parameter | description | +| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `name` | _(Required.) _ **string**. A unique name to identify the dataverse instance. | +| `triplestore_config` | _(Required.) _ **[TripleStoreConfig](#triplestoreconfig)**. The configuration used to instantiate the triple store. | +| `triplestore_config.code_id` | **[Uint64](#uint64)**. The code id that will be used to instantiate the triple store contract in which to store dataverse semantic data. It must implement the cognitarium interface. | +| `triplestore_config.limits` | **[TripleStoreLimitsInput](#triplestorelimitsinput)**. Limitations regarding triple store usage. | + +## ExecuteMsg + +`ExecuteMsg` defines the set of possible actions that can be performed on the dataverse. + +This enum provides variants for registering services, datasets, and other operations related to the dataverse. + +### ExecuteMsg::SubmitClaims + +Submits new claims about a resource to the dataverse. + +The SubmitClaims message is a pivotal component in the dataverse, enabling entities to contribute new claims about various resources. A claim represents a statement made by an entity, referred to as the issuer, which could be a person, organization, or service. These claims pertain to a diverse range of resources, including digital resources, services, zones, or individuals, and are asserted as factual by the issuer. + +#### Format + +Claims are injected into the dataverse through Verifiable Credentials (VCs). + +Primarily, the claims leverage the AXONE ontology, which facilitates articulating assertions about widely acknowledged resources in the dataverse, including digital services, digital resources, zones, governance, and more. + +Additionally, other schemas may also be employed to supplement and enhance the validated knowledge contributed to these resources. + +#### Preconditions + +To maintain integrity and coherence in the dataverse, several preconditions are set for the submission of claims: + +1. **Format Requirement**: Claims must be encapsulated within Verifiable Credentials (VCs). + +2. **Unique Identifier Mandate**: Each Verifiable Credential within the dataverse must possess a unique identifier. + +3. **Issuer Signature**: Claims must bear the issuer's signature. This signature must be verifiable, ensuring authenticity and credibility. + +4. **Content**: The actual implementation supports the submission of a single Verifiable Credential, containing a single claim. + +#### Supported cryptographic proofs + +- `Ed25519Signature2018` + +- `Ed25519Signature2020` + +- `EcdsaSecp256k1Signature2019` + +- `DataIntegrity` with the following cryptosuites: `eddsa-2022`, `eddsa-rdfc-2022`. + +| parameter | description | +| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `submit_claims` | _(Required.) _ **object**. | +| `submit_claims.format` | **[RdfDatasetFormat](#rdfdatasetformat)\|null**. RDF dataset serialization format for the metadata. If not provided, the default format is [N-Quads](https://www.w3.org/TR/n-quads/) format. | +| `submit_claims.metadata` | _(Required.) _ **[Binary](#binary)**. The serialized metadata intended for attachment. This metadata should adhere to the format specified in the `format` field. | + +### ExecuteMsg::RevokeClaims + +Revoke or withdraw a previously submitted claims. + +#### Preconditions: + +1. **Identifier Existance**: The identifier of the claims must exist in the dataverse. + +| parameter | description | +| -------------------------- | ----------------------------------------------------------------------------- | +| `revoke_claims` | _(Required.) _ **object**. | +| `revoke_claims.identifier` | _(Required.) _ **string**. The unique identifier of the claims to be revoked. | + +## QueryMsg + +`QueryMsg` defines the set of possible queries that can be made to retrieve information about the dataverse. + +This enum provides variants for querying the dataverse's details and other related information. + +### QueryMsg::Dataverse + +Retrieves information about the current dataverse instance. + +| parameter | description | +| ----------- | -------------------------- | +| `dataverse` | _(Required.) _ **object**. | + +## Responses + +### dataverse + +DataverseResponse is the response of the Dataverse query. + +| property | description | +| --------------------- | ------------------------------------------------------------------- | +| `name` | _(Required.) _ **string**. The name of the dataverse. | +| `triplestore_address` | _(Required.) _ **[Addr](#addr)**. The cognitarium contract address. | + +## Definitions + +### Addr + +A human readable address. + +In Cosmos, this is typically bech32 encoded. But for multi-chain smart contracts no assumptions should be made other than being UTF-8 encoded and of reasonable length. + +This type represents a validated address. It can be created in the following ways 1. Use `Addr::unchecked(input)` 2. Use `let checked: Addr = deps.api.addr_validate(input)?` 3. Use `let checked: Addr = deps.api.addr_humanize(canonical_addr)?` 4. Deserialize from JSON. This must only be done from JSON that was validated before such as a contract's state. `Addr` must not be used in messages sent by the user because this would result in unvalidated instances. + +This type is immutable. If you really need to mutate it (Really? Are you sure?), create a mutable copy using `let mut mutable = Addr::to_string()` and operate on that `String` instance. + +| type | +| ----------- | +| **string**. | + +### Binary + +A string containing Base64-encoded data. + +| type | +| ----------- | +| **string**. | + +### NQuads + +N-Quads Format + +N-Quads is an extension of N-Triples to support RDF datasets by adding an optional fourth element to represent the graph name. See the [official N-Quads specification](https://www.w3.org/TR/n-quads/). + +| literal | +| ----------- | +| `"n_quads"` | + +### RdfDatasetFormat + +Represents the various serialization formats for an RDF dataset, i.e. a collection of RDF graphs ([RDF Dataset](https://www.w3.org/TR/rdf11-concepts/#section-dataset)). + +| variant | description | +| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [NQuads](#nquads) | **string**: `n_quads`. N-Quads Format

N-Quads is an extension of N-Triples to support RDF datasets by adding an optional fourth element to represent the graph name. See the [official N-Quads specification](https://www.w3.org/TR/n-quads/). | + +### TripleStoreConfig + +`TripleStoreConfig` represents the configuration related to the management of the triple store. + +| property | description | +| ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `code_id` | _(Required.) _ **[Uint64](#uint64)**. The code id that will be used to instantiate the triple store contract in which to store dataverse semantic data. It must implement the cognitarium interface. | +| `limits` | _(Required.) _ **[TripleStoreLimitsInput](#triplestorelimitsinput)**. Limitations regarding triple store usage. | +| `limits.max_byte_size` | **[Uint128](#uint128)\|null**. The maximum number of bytes the store can contain. The size of a triple is counted as the sum of the size of its subject, predicate and object, including the size of data types and language tags if any. Default to [Uint128::MAX] if not set, which can be considered as no limit. | +| `limits.max_insert_data_byte_size` | **[Uint128](#uint128)\|null**. The maximum number of bytes an insert data query can contain. Default to [Uint128::MAX] if not set, which can be considered as no limit. | +| `limits.max_insert_data_triple_count` | **[Uint128](#uint128)\|null**. The maximum number of triples an insert data query can contain (after parsing). Default to [Uint128::MAX] if not set, which can be considered as no limit. | +| `limits.max_query_limit` | **integer\|null**. The maximum limit of a query, i.e. the maximum number of triples returned by a select query. Default to 30 if not set. | +| `limits.max_query_variable_count` | **integer\|null**. The maximum number of variables a query can select. Default to 30 if not set. | +| `limits.max_triple_byte_size` | **[Uint128](#uint128)\|null**. The maximum number of bytes the store can contain for a single triple. The size of a triple is counted as the sum of the size of its subject, predicate and object, including the size of data types and language tags if any. The limit is used to prevent storing very large triples, especially literals. Default to [Uint128::MAX] if not set, which can be considered as no limit. | +| `limits.max_triple_count` | **[Uint128](#uint128)\|null**. The maximum number of triples the store can contain. Default to [Uint128::MAX] if not set, which can be considered as no limit. | + +### TripleStoreLimitsInput + +Contains requested limitations regarding store usages. + +| property | description | +| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `max_byte_size` | **[Uint128](#uint128)\|null**. The maximum number of bytes the store can contain. The size of a triple is counted as the sum of the size of its subject, predicate and object, including the size of data types and language tags if any. Default to [Uint128::MAX] if not set, which can be considered as no limit. | +| `max_insert_data_byte_size` | **[Uint128](#uint128)\|null**. The maximum number of bytes an insert data query can contain. Default to [Uint128::MAX] if not set, which can be considered as no limit. | +| `max_insert_data_triple_count` | **[Uint128](#uint128)\|null**. The maximum number of triples an insert data query can contain (after parsing). Default to [Uint128::MAX] if not set, which can be considered as no limit. | +| `max_query_limit` | **integer\|null**. The maximum limit of a query, i.e. the maximum number of triples returned by a select query. Default to 30 if not set. | +| `max_query_variable_count` | **integer\|null**. The maximum number of variables a query can select. Default to 30 if not set. | +| `max_triple_byte_size` | **[Uint128](#uint128)\|null**. The maximum number of bytes the store can contain for a single triple. The size of a triple is counted as the sum of the size of its subject, predicate and object, including the size of data types and language tags if any. The limit is used to prevent storing very large triples, especially literals. Default to [Uint128::MAX] if not set, which can be considered as no limit. | +| `max_triple_count` | **[Uint128](#uint128)\|null**. The maximum number of triples the store can contain. Default to [Uint128::MAX] if not set, which can be considered as no limit. | + +### Uint128 + +A string containing a 128-bit integer in decimal representation. + +| type | +| ----------- | +| **string**. | + +### Uint64 + +A thin wrapper around u64 that is using strings for JSON encoding/decoding, such that the full u64 range can be used for clients that convert JSON numbers to floats, like JavaScript and jq. + +# Examples + +Use `from` to create instances of this and `u64` to get the value out: + +````# use cosmwasm_std::Uint64; let a = Uint64::from(42u64); assert_eq!(a.u64(), 42); + +let b = Uint64::from(70u32); assert_eq!(b.u64(), 70); ``` + +|type| +|----| +|**string**.| + +--- + +*Rendered by [Fadroma](https://fadroma.tech) ([@fadroma/schema 1.1.0](https://www.npmjs.com/package/@fadroma/schema)) from `axone-dataverse.json` (`70aa81be19dd58f9`)* +```` diff --git a/contracts_versioned_docs/version-v6.0.0/axone-law-stone.md b/contracts_versioned_docs/version-v6.0.0/axone-law-stone.md new file mode 100644 index 00000000000..5d7c3ae1d07 --- /dev/null +++ b/contracts_versioned_docs/version-v6.0.0/axone-law-stone.md @@ -0,0 +1,139 @@ +# Law Stone + +## Overview + +The `axone-law-stone` smart contract aims to provide GaaS (i.e. Governance as a Service) in any [Cosmos blockchains](https://cosmos.network/) using the [CosmWasm](https://cosmwasm.com/) framework and the [Logic](https://docs.axone.xyz/modules/next/logic) AXONE module. + +This contract is built around a Prolog program describing the law by rules and facts. The law stone is immutable, this means it can only be questioned, there are no update mechanisms. + +The `axone-law-stone` responsibility is to guarantee the availability of its rules in order to question them, but not to ensure the rules application. + +To ensure reliability over time, the associated Prolog program is stored and pinned in a `axone-objectarium` contract. Moreover, all the eventual loaded files must be stored in a `axone-objectarium` contract as well, allowing the contract to pin them. + +To be able to free the underlying resources (i.e. objects in `axone-objectarium`) if not used anymore, the contract admin can break the stone. + +➡️ Checkout the [examples](https://github.com/axone-protocol/contracts/tree/main/contracts/axone-law-stone/examples/) for usage information. + +## InstantiateMsg + +Instantiate message + +| parameter | description | +| ----------------- | ------------------------------------------------------------------------------------------------------ | +| `program` | _(Required.) _ **[Binary](#binary)**. The Prolog program carrying law rules and facts. | +| `storage_address` | _(Required.) _ **string**. The `axone-objectarium` contract address on which to store the law program. | + +## ExecuteMsg + +Execute messages + +### ExecuteMsg::BreakStone + +Break the stone making this contract unusable, by clearing all the related resources: - Unpin all the pinned objects on `axone-objectarium` contracts, if any. - Forget the main program (i.e. or at least unpin it). + +Only the creator address (the address that instantiated the contract) is authorized to invoke this message. If already broken, this is a no-op. + +| parameter | description | +| ------------- | -------------------------- | +| `break_stone` | _(Required.) _ **object**. | + +## QueryMsg + +Query messages + +### QueryMsg::Ask + +Submits a Prolog query string to the `Logic` module, evaluating it against the law program associated with this contract. + +If the law stone is broken the query returns a response with the error `error(system_error(broken_law_stone),root)` set in the `answer` field. + +| parameter | description | +| ----------- | -------------------------- | +| `ask` | _(Required.) _ **object**. | +| `ask.query` | _(Required.) _ **string**. | + +### QueryMsg::Program + +Retrieves the location metadata of the law program bound to this contract. + +This includes the contract address of the `objectarium` and the program object ID, where the law program's code can be accessed. + +| parameter | description | +| --------- | -------------------------- | +| `program` | _(Required.) _ **object**. | + +### QueryMsg::ProgramCode + +Fetches the raw code of the law program tied to this contract. + +If the law stone is broken, the query may fail if the program is no longer available in the `Objectarium`. + +| parameter | description | +| -------------- | -------------------------- | +| `program_code` | _(Required.) _ **object**. | + +## Responses + +### ask + +| property | description | +| ------------- | ---------------------------- | +| `answer` | **[Answer](#answer)\|null**. | +| `gas_used` | _(Required.) _ **integer**. | +| `height` | _(Required.) _ **integer**. | +| `user_output` | **string\|null**. | + +### program + +ProgramResponse carry elements to locate the program in a `axone-objectarium` contract. + +| property | description | +| ----------------- | ------------------------------------------------------------------------------------------------------- | +| `object_id` | _(Required.) _ **string**. The program object id in the `axone-objectarium` contract. | +| `storage_address` | _(Required.) _ **string**. The `axone-objectarium` contract address on which the law program is stored. | + +### program_code + +Binary is a wrapper around Vec<u8> to add base64 de/serialization with serde. It also adds some helper methods to help encode inline. + +This is only needed as serde-json-\{core,wasm\} has a horrible encoding for Vec<u8>. See also <https://github.com/CosmWasm/cosmwasm/blob/main/docs/MESSAGE_TYPES.md>. + +| type | +| ----------- | +| **string**. | + +## Definitions + +### Answer + +| property | description | +| ----------- | -------------------------------------------------- | +| `has_more` | _(Required.) _ **boolean**. | +| `results` | _(Required.) _ **Array<[Result](#result)>**. | +| `variables` | _(Required.) _ **Array<string>**. | + +### Binary + +A string containing Base64-encoded data. + +| type | +| ----------- | +| **string**. | + +### Result + +| property | description | +| --------------- | -------------------------------------------------------------- | +| `error` | **string\|null**. | +| `substitutions` | _(Required.) _ **Array<[Substitution](#substitution)>**. | + +### Substitution + +| property | description | +| ------------ | -------------------------- | +| `expression` | _(Required.) _ **string**. | +| `variable` | _(Required.) _ **string**. | + +--- + +_Rendered by [Fadroma](https://fadroma.tech) ([@fadroma/schema 1.1.0](https://www.npmjs.com/package/@fadroma/schema)) from `axone-law-stone.json` (`f8eb198b23eb9c74`)_ diff --git a/contracts_versioned_docs/version-v6.0.0/axone-objectarium.md b/contracts_versioned_docs/version-v6.0.0/axone-objectarium.md new file mode 100644 index 00000000000..b156a893ac7 --- /dev/null +++ b/contracts_versioned_docs/version-v6.0.0/axone-objectarium.md @@ -0,0 +1,528 @@ +# Objectarium + +A [CosmWasm](https://cosmwasm.com/) Smart Contract which enables the storage of arbitrary unstructured [Objects](https://en.wikipedia.org/wiki/Object_storage) in any [Cosmos](https://cosmos.network/) blockchains. + +## Purpose + +The smart contract serves as a robust storage solution, allowing for the storage of arbitrary `objects` on any blockchain within the [Cosmos blockchains](https://cosmos.network/) network, utilizing the [CosmWasm](https://cosmwasm.com/) framework. The key features of the contract include: + +**Versatile Data Storage:** +The contract is designed to accommodate any type of data, be it text, images, or complex data structures. This flexibility makes it an ideal choice for a wide range of decentralized applications (dApps) that require diverse storage needs. + +**On-chain Data:** +By design, the contract stores data on the blockchain, ensuring that it is immutable and publicly accessible. This is particularly useful for applications that require a high level of transparency, and also for any other smart contract that needs to store data on the blockchain. + +**Pinning and Unpinning:** +One unique feature is the ability to 'pin' and 'unpin' objects associated with a specific sender address. Pinning ensures that the object remains stored and accessible, while unpinning releases it from being permanently stored, offering a level of control over data persistence. + +**Object Removal:** +The contract also includes a 'forget' function, allowing for the removal of objects that are no longer pinned. This is particularly useful for managing storage costs and ensuring that only relevant data remains on the blockchain. + +**Cost Management:** +Features like pinning, unpinning, and discarding objects offer a strategic way to control storage costs. Additionally, setting limits on contract size — for instance in terms of object count and their individual sizes — serves as a practical tool to regulate storage costs. + +## Rationale + +In a sense, we can consider blockchains built on the [Cosmos L0](https://docs.cosmos.network/main) layer as decentralized databases, and their nature can be shaped and modeled through the smart contracts or modules. Given this, it provides a great opportunity to address the wide range of data management needs. One such important area is the management of unstructured, immutable data, which is written once but accessed frequently — commonly known as object storage. This is the primary focus of `axone-objectarium`: a specialized smart contract designed to offer a versatile and efficient approach to handling _on-chain_, _unstructured_, _immutable_ data in a _decentralized_ manner. + +## Terminology + +### Object + +In the context of the `axone-objectarium` smart contract, an `object` refers to a piece of data stored on the blockchain. It can represent various types of information, such as documents, binary files, or any other digital content. Objects are immutable once stored and are identified by their cryptographic hash, which can be generated using algorithms like MD5 or SHA256. This ensures the integrity and security of the stored data, as any modification to the object would result in a different hash value. + +### Bucket + +The smart contract is organized around buckets. A bucket represents a logical container within the `axone-objectarium` smart contract instance that groups related Objects together. It acts as a storage unit for Objects and provides a context for managing and organizing them. Each bucket has a unique name and is associated with a set of configurations and limits that define its behaviour and characteristics. + +### Pin + +Pin refers to a mechanism that allows users to mark or "pin" specific objects within a bucket. Pinning an object serves as a way to ensure that the object remains in storage and cannot be removed (this is called "forgotten"). It provides protection and guarantees that the pinned object will persist in the protocol. When an object is pinned, it is associated with the identity (or sender) that performed the pinning action. + +## Usage + +The unstructured nature of the data stored in the chain opens up a plethora of possibilities for decentralized applications that require this type of versatile storage. + +### In the AXONE protocol + +The primary function of this smart contract within the AXONE protocol is to enable the persistence of governance rules, which are encoded in Prolog. These programs are stored in an immutable format within the protocol and can be referenced by their unique identifiers in situations where there is a need to refer to these rules. + +### In the wild world + +A plethora of possibilities opens up for decentralized applications (dApps) that require this kind of versatile storage. However, it's important to consider the following constraints: the data is immutable, the cost of recording the data is proportional to its size, and the data is publicly accessible. + +## Play + +### Instantiation + +The `axone-objectarium` can be instantiated as follows, refer to the schema for more information on configuration, limits and pagination configuration: + +```bash +axoned tx wasm instantiate $CODE_ID \ + --label "my-storage" \ + --from $ADDR \ + --admin $ADMIN_ADDR \ + --gas 1000000 \ + '{"bucket":"my-bucket"}' +``` + +### Execution + +We can store an object by providing its data in base64 encoded, we can pin the stored object to prevent it from being removed: + +```bash +axoned tx wasm execute $CONTRACT_ADDR \ + --from $ADDR \ + --gas 1000000 \ + "{\"store_object\":{\"data\": \"$(cat my-data | base64)\",\"pin\":true}}" +``` + +The object id is stable as it is a hash, we can't store an object twice. + +With the following commands we can pin and unpin existing objects: + +```bash +axoned tx wasm execute $CONTRACT_ADDR \ + --from $ADDR \ + --gas 1000000 \ + "{\"pin_object\":{\"id\": \"$OBJECT_ID\"}}" + +axoned tx wasm execute $CONTRACT_ADDR \ + --from $ADDR \ + --gas 1000000 \ + "{\"unpin_object\":{\"id\": \"$OBJECT_ID\"}}" +``` + +And if an object is not pinned, or pinned by the sender of transaction, we can remove it: + +```bash +axoned tx wasm execute $CONTRACT_ADDR \ + --from $ADDR \ + --gas 1000000 \ + "{\"forget_object\":{\"id\": \"$OBJECT_ID\"}}" +``` + +### Querying + +Query an object by its id: + +```bash +axoned query wasm contract-state smart $CONTRACT_ADDR \ + "{\"object\": {\"id\": \"$OBJECT_ID\"}}" +``` + +Or its data: + +```bash +axoned query wasm contract-state smart $CONTRACT_ADDR \ + "{\"object_data\": {\"id\": \"$OBJECT_ID\"}}" +``` + +We can also list the objects, eventually filtering on the object owner: + +```bash +axoned query wasm contract-state smart $CONTRACT_ADDR \ + "{\"objects\": {\"address\": \"axone1p8u47en82gmzfm259y6z93r9qe63l25d858vqu\"}}" +``` + +And navigate in a cursor based pagination: + +```bash +axoned query wasm contract-state smart $CONTRACT_ADDR \ + "{\"objects\": {\"first\": 5, \"after\": \"23Y5t5DBe7DkPwfJo3Sd26Y8Z9epmtpA1FTpdG7DiG6MD8vPRTzzbQ9TccmyoBcePkPK6atUiqcAzJVo3TfYNBGY\"}}" +``` + +We can also query object pins with the same cursor based pagination: + +```bash +axoned query wasm contract-state smart $CONTRACT_ADDR \ + "{\"object_pins\": {\"id\": \"$OBJECT_ID\", \"first\": 5, \"after\": \"23Y5t5DBe7DkPwfJo3Sd26Y8Z9epmtpA1FTpdG7DiG6MD8vPRTzzbQ9TccmyoBcePkPK6atUiqcAzJVo3TfYNBGY\"}}" +``` + +## InstantiateMsg + +Instantiate messages + +| parameter | description | +| ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `bucket` | _(Required.) _ **string**. The name of the bucket. The name could not be empty or contains whitespaces. If name contains whitespace, they will be removed. | +| `config` | **[BucketConfig](#bucketconfig)**. The configuration of the bucket. | +| `config.accepted_compression_algorithms` | **Array<[CompressionAlgorithm](#compressionalgorithm)>**. The acceptable compression algorithms for the objects in the bucket. If this parameter is not set, then all compression algorithms are accepted. If this parameter is set, then only the compression algorithms in the array are accepted.

When an object is stored in the bucket without a specified compression algorithm, the first algorithm in the array is used. Therefore, the order of the algorithms in the array is significant. Typically, the most efficient compression algorithm, such as the NoCompression algorithm, should be placed first in the array.

Any attempt to store an object using a different compression algorithm than the ones specified here will fail.
**Default:** `["passthrough","snappy","lzma"]` | +| `config.hash_algorithm` | **[HashAlgorithm](#hashalgorithm)**. The algorithm used to hash the content of the objects to generate the id of the objects. The algorithm is optional and if not set, the default algorithm is used.

The default algorithm is Sha256 if not set.
**Default:** `"sha256"` | +| `limits` | **[BucketLimits](#bucketlimits)**. The limits of the bucket. | +| `limits.max_object_pins` | **[Uint128](#uint128)\|null**. The maximum number of pins in the bucket for an object. | +| `limits.max_object_size` | **[Uint128](#uint128)\|null**. The maximum size of the objects in the bucket. | +| `limits.max_objects` | **[Uint128](#uint128)\|null**. The maximum number of objects in the bucket. | +| `limits.max_total_size` | **[Uint128](#uint128)\|null**. The maximum total size of the objects in the bucket. | +| `pagination` | **[PaginationConfig](#paginationconfig)**. The configuration for paginated query. | +| `pagination.default_page_size` | **integer**. The default number of elements in a page.

Shall be less or equal than `max_page_size`. Default to '10' if not set.
**Default:** `10` | +| `pagination.max_page_size` | **integer**. The maximum elements a page can contain.

Shall be less than `u32::MAX - 1`. Default to '30' if not set.
**Default:** `30` | + +## ExecuteMsg + +Execute messages + +### ExecuteMsg::StoreObject + +StoreObject store an object to the bucket and make the sender the owner of the object. The object is referenced by the hash of its content and this value is returned. If the object is already stored, it is a no-op. It may be pinned though. + +The "pin" parameter specifies whether the object should be pinned for the sender. Pinning an object ensures it is protected from being removed from storage, making it persistent and guaranteeing its indefinite accessibility. It’s important to note that pinning is optional; objects can be stored without pinning. However, be aware that non-pinned objects can be removed from the storage by anyone at any time, making them no longer accessible. + +The "compression_algorithm" parameter specifies the algorithm for compressing the object before storing it in the storage, which is optional. If no algorithm is specified, the algorithm used is the first algorithm of the bucket configuration limits. Note that the chosen algorithm can save storage space, but it will increase CPU usage. Depending on the chosen compression algorithm and the achieved compression ratio, the gas cost of the operation will vary, either increasing or decreasing. + +| parameter | description | +| ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `store_object` | _(Required.) _ **object**. | +| `store_object.compression_algorithm` | **[CompressionAlgorithm](#compressionalgorithm)\|null**. Specifies the compression algorithm to use when storing the object. If None, the first algorithm specified in the list of accepted compression algorithms of the bucket is used (see [BucketLimits::accepted_compression_algorithms]). | +| `store_object.data` | _(Required.) _ **[Binary](#binary)**. The content of the object to store. | +| `store_object.pin` | _(Required.) _ **boolean**. Specifies whether the object should be pinned for the sender. Pinning ensures the object remains persistent and cannot be removed from storage by anyone. | + +### ExecuteMsg::ForgetObject + +ForgetObject first unpins the object from the bucket for the sender, then removes it from storage if it is no longer pinned by anyone. If the object is still pinned by other senders, it is not removed from storage and an error is returned. If the object is not pinned for the sender, this operation is a no-op. + +| parameter | description | +| ------------------ | -------------------------- | +| `forget_object` | _(Required.) _ **object**. | +| `forget_object.id` | _(Required.) _ **string**. | + +### ExecuteMsg::PinObject + +PinObject pins the object in the bucket for the sender. If the object is already pinned for the sender, this operation is a no-op. While an object is pinned, it cannot be removed from storage. + +| parameter | description | +| --------------- | -------------------------- | +| `pin_object` | _(Required.) _ **object**. | +| `pin_object.id` | _(Required.) _ **string**. | + +### ExecuteMsg::UnpinObject + +UnpinObject unpins the object in the bucket for the sender. If the object is not pinned for the sender, this operation is a no-op. The object can be removed from storage if it is no longer pinned by anyone. + +| parameter | description | +| ----------------- | -------------------------- | +| `unpin_object` | _(Required.) _ **object**. | +| `unpin_object.id` | _(Required.) _ **string**. | + +## QueryMsg + +Query messages + +### QueryMsg::Bucket + +Bucket returns the bucket information. + +| parameter | description | +| --------- | -------------------------- | +| `bucket` | _(Required.) _ **object**. | + +### QueryMsg::Object + +Object returns the object information with the given id. + +| parameter | description | +| ----------- | ------------------------------------------------------- | +| `object` | _(Required.) _ **object**. | +| `object.id` | _(Required.) _ **string**. The id of the object to get. | + +### QueryMsg::Objects + +Objects returns the list of objects in the bucket with support for pagination. + +| parameter | description | +| ----------------- | ----------------------------------------------------------------------- | +| `objects` | _(Required.) _ **object**. | +| `objects.address` | **string\|null**. The owner of the objects to get. | +| `objects.after` | **string\|null**. The point in the sequence to start returning objects. | +| `objects.first` | **integer\|null**. The number of objects to return. | + +### QueryMsg::ObjectData + +ObjectData returns the content of the object with the given id. + +| parameter | description | +| ---------------- | ------------------------------------------------------- | +| `object_data` | _(Required.) _ **object**. | +| `object_data.id` | _(Required.) _ **string**. The id of the object to get. | + +### QueryMsg::ObjectPins + +ObjectPins returns the list of addresses that pinned the object with the given id with support for pagination. + +| parameter | description | +| ------------------- | -------------------------------------------------------------------- | +| `object_pins` | _(Required.) _ **object**. | +| `object_pins.after` | **string\|null**. The point in the sequence to start returning pins. | +| `object_pins.first` | **integer\|null**. The number of pins to return. | +| `object_pins.id` | _(Required.) _ **string**. The id of the object to get the pins for. | + +## Responses + +### bucket + +BucketResponse is the response of the Bucket query. + +| property | description | +| ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `config` | _(Required.) _ **[BucketConfig](#bucketconfig)**. The configuration of the bucket. | +| `config.accepted_compression_algorithms` | **Array<[CompressionAlgorithm](#compressionalgorithm)>**. The acceptable compression algorithms for the objects in the bucket. If this parameter is not set, then all compression algorithms are accepted. If this parameter is set, then only the compression algorithms in the array are accepted.

When an object is stored in the bucket without a specified compression algorithm, the first algorithm in the array is used. Therefore, the order of the algorithms in the array is significant. Typically, the most efficient compression algorithm, such as the NoCompression algorithm, should be placed first in the array.

Any attempt to store an object using a different compression algorithm than the ones specified here will fail.
**Default:** `["passthrough","snappy","lzma"]` | +| `config.hash_algorithm` | **[HashAlgorithm](#hashalgorithm)**. The algorithm used to hash the content of the objects to generate the id of the objects. The algorithm is optional and if not set, the default algorithm is used.

The default algorithm is Sha256 if not set.
**Default:** `"sha256"` | +| `limits` | _(Required.) _ **[BucketLimits](#bucketlimits)**. The limits of the bucket. | +| `limits.max_object_pins` | **[Uint128](#uint128)\|null**. The maximum number of pins in the bucket for an object. | +| `limits.max_object_size` | **[Uint128](#uint128)\|null**. The maximum size of the objects in the bucket. | +| `limits.max_objects` | **[Uint128](#uint128)\|null**. The maximum number of objects in the bucket. | +| `limits.max_total_size` | **[Uint128](#uint128)\|null**. The maximum total size of the objects in the bucket. | +| `name` | _(Required.) _ **string**. The name of the bucket. | +| `pagination` | _(Required.) _ **[PaginationConfig](#paginationconfig)**. The configuration for paginated query. | +| `pagination.default_page_size` | **integer**. The default number of elements in a page.

Shall be less or equal than `max_page_size`. Default to '10' if not set.
**Default:** `10` | +| `pagination.max_page_size` | **integer**. The maximum elements a page can contain.

Shall be less than `u32::MAX - 1`. Default to '30' if not set.
**Default:** `30` | +| `stat` | _(Required.) _ **[BucketStat](#bucketstat)**. The statistics of the bucket. | +| `stat.compressed_size` | **[Uint128](#uint128)**. The total size of the objects contained in the bucket after compression. | +| `stat.object_count` | **[Uint128](#uint128)**. The number of objects in the bucket. | +| `stat.size` | **[Uint128](#uint128)**. The total size of the objects contained in the bucket. | + +### object + +ObjectResponse is the response of the Object query. + +| property | description | +| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | +| `compressed_size` | _(Required.) _ **[Uint128](#uint128)**. The size of the object when compressed. If the object is not compressed, the value is the same as `size`. | +| `compression_algorithm` | _(Required.) _ **[CompressionAlgorithm](#compressionalgorithm)**. The compression algorithm used to compress the content of the object. | +| `id` | _(Required.) _ **string**. The id of the object. | +| `is_pinned` | _(Required.) _ **boolean**. Tells if the object is pinned by at least one address. | +| `owner` | _(Required.) _ **string**. The owner of the object. | +| `size` | _(Required.) _ **[Uint128](#uint128)**. The size of the object. | + +### object_data + +Binary is a wrapper around Vec<u8> to add base64 de/serialization with serde. It also adds some helper methods to help encode inline. + +This is only needed as serde-json-\{core,wasm\} has a horrible encoding for Vec<u8>. See also <https://github.com/CosmWasm/cosmwasm/blob/main/docs/MESSAGE_TYPES.md>. + +| type | +| ----------- | +| **string**. | + +### object_pins + +ObjectPinsResponse is the response of the GetObjectPins query. + +| property | description | +| ------------------------- | ------------------------------------------------------------------------------------- | +| `data` | _(Required.) _ **Array<string>**. The list of addresses that pinned the object. | +| `page_info` | _(Required.) _ **[PageInfo](#pageinfo)**. The page information. | +| `page_info.cursor` | **string**. The cursor to the next page. | +| `page_info.has_next_page` | **boolean**. Tells if there is a next page. | + +### objects + +ObjectsResponse is the response of the Objects query. + +| property | description | +| ------------------------- | ----------------------------------------------------------------------------------------------------- | +| `data` | _(Required.) _ **Array<[ObjectResponse](#objectresponse)>**. The list of objects in the bucket. | +| `page_info` | _(Required.) _ **[PageInfo](#pageinfo)**. The page information. | +| `page_info.cursor` | **string**. The cursor to the next page. | +| `page_info.has_next_page` | **boolean**. Tells if there is a next page. | + +## Definitions + +### Binary + +A string containing Base64-encoded data. + +| type | +| ----------- | +| **string**. | + +### BucketConfig + +BucketConfig is the type of the configuration of a bucket. + +The configuration is set at the instantiation of the bucket, and is immutable and cannot be changed. The configuration is optional and if not set, the default configuration is used. + +| property | description | +| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `accepted_compression_algorithms` | **Array<[CompressionAlgorithm](#compressionalgorithm)>**. The acceptable compression algorithms for the objects in the bucket. If this parameter is not set, then all compression algorithms are accepted. If this parameter is set, then only the compression algorithms in the array are accepted.

When an object is stored in the bucket without a specified compression algorithm, the first algorithm in the array is used. Therefore, the order of the algorithms in the array is significant. Typically, the most efficient compression algorithm, such as the NoCompression algorithm, should be placed first in the array.

Any attempt to store an object using a different compression algorithm than the ones specified here will fail. | +| `hash_algorithm` | **[HashAlgorithm](#hashalgorithm)**. The algorithm used to hash the content of the objects to generate the id of the objects. The algorithm is optional and if not set, the default algorithm is used.

The default algorithm is Sha256 if not set. | + +### BucketLimits + +BucketLimits is the type of the limits of a bucket. + +The limits are optional and if not set, there is no limit. + +| property | description | +| ----------------- | -------------------------------------------------------------------------------------- | +| `max_object_pins` | **[Uint128](#uint128)\|null**. The maximum number of pins in the bucket for an object. | +| `max_object_size` | **[Uint128](#uint128)\|null**. The maximum size of the objects in the bucket. | +| `max_objects` | **[Uint128](#uint128)\|null**. The maximum number of objects in the bucket. | +| `max_total_size` | **[Uint128](#uint128)\|null**. The maximum total size of the objects in the bucket. | + +### BucketStat + +BucketStat is the type of the statistics of a bucket. + +| property | description | +| ----------------- | ---------------------------------------------------------------------------------------------------------------- | +| `compressed_size` | _(Required.) _ **[Uint128](#uint128)**. The total size of the objects contained in the bucket after compression. | +| `object_count` | _(Required.) _ **[Uint128](#uint128)**. The number of objects in the bucket. | +| `size` | _(Required.) _ **[Uint128](#uint128)**. The total size of the objects contained in the bucket. | + +### CompressionAlgorithm + +CompressionAlgorithm is an enumeration that defines the different compression algorithms supported for compressing the content of objects. The compression algorithm specified here are relevant algorithms for compressing data on-chain, which means that they are fast to compress and decompress, and have a low computational cost. + +The order of the compression algorithms is based on their estimated computational cost (quite opinionated) during both compression and decompression, ranging from the lowest to the highest. This particular order is utilized to establish the default compression algorithm for storing an object. + +| variant | description | +| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [Passthrough](#passthrough) | **string**: `passthrough`. Represents no compression algorithm. The object is stored as is without any compression. | +| [Snappy](#snappy) | **string**: `snappy`. Represents the Snappy algorithm. Snappy is a compression/decompression algorithm that does not aim for maximum compression. Instead, it aims for very high speeds and reasonable compression.

See [the snappy web page](https://google.github.io/snappy/) for more information. | +| [Lzma](#lzma) | **string**: `lzma`. Represents the LZMA algorithm. LZMA is a lossless data compression/decompression algorithm that features a high compression ratio and a variable compression-dictionary size up to 4 GB.

See [the LZMA wiki page](https://en.wikipedia.org/wiki/Lempel%E2%80%93Ziv%E2%80%93Markov_chain_algorithm) for more information. | + +### HashAlgorithm + +HashAlgorithm is an enumeration that defines the different hash algorithms supported for hashing the content of objects. + +| variant | description | +| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [MD5](#md5) | **string**: `m_d5`. Represents the MD5 algorithm. MD5 is a widely used cryptographic hash function that produces a 128-bit hash value. The computational cost of MD5 is relatively low compared to other hash functions, but its short hash length makes it easier to find hash collisions. It is now considered insecure for cryptographic purposes, but can still used in non-security contexts.

MD5 hashes are stored on-chain as 32 hexadecimal characters.

See [the MD5 Wikipedia page](https://en.wikipedia.org/wiki/MD5) for more information. | +| [SHA1](#sha1) | **string**: `sha224`. Represents the SHA-224 algorithm. SHA-224 is a variant of the SHA-2 family of hash functions that produces a 224-bit hash value. It is similar to SHA-256, but with a shorter output size. The computational cost of SHA-224 is moderate, and its relatively short hash length makes it easier to store and transmit.

SHA-224 hashes are stored on-chain as 56 hexadecimal characters.

See [the SHA-2 Wikipedia page](https://en.wikipedia.org/wiki/SHA-2) for more information. | +| [SHA256](#sha256) | **string**: `sha256`. Represents the SHA-256 algorithm. SHA-256 is a member of the SHA-2 family of hash functions that produces a 256-bit hash value. It is widely used in cryptography and other security-related applications. The computational cost of SHA-256 is moderate, and its hash length strikes a good balance between security and convenience.

SHA-256 hashes are stored on-chain as 64 hexadecimal characters.

See [the SHA-2 Wikipedia page](https://en.wikipedia.org/wiki/SHA-2) for more information. | +| [SHA384](#sha384) | **string**: `sha384`. Represents the SHA-384 algorithm. SHA-384 is a variant of the SHA-2 family of hash functions that produces a 384-bit hash value. It is similar to SHA-512, but with a shorter output size. The computational cost of SHA-384 is relatively high, but its longer hash length provides better security against hash collisions.

SHA-384 hashes are stored on-chain as 96 hexadecimal characters.

See [the SHA-2 Wikipedia page](https://en.wikipedia.org/wiki/SHA-2) for more information. | +| [SHA512](#sha512) | **string**: `sha512`. Represents the SHA-512 algorithm. SHA-512 is a member of the SHA-2 family of hash functions that produces a 512-bit hash value. It is widely used in cryptography and other security-related applications. The computational cost of SHA-512 is relatively high, but its longer hash length provides better security against hash collisions.

SHA-512 hashes are stored on-chain as 128 hexadecimal characters.

See [the SHA-2 Wikipedia page](https://en.wikipedia.org/wiki/SHA-2) for more information. | + +### Lzma + +Represents the LZMA algorithm. LZMA is a lossless data compression/decompression algorithm that features a high compression ratio and a variable compression-dictionary size up to 4 GB. + +See [the LZMA wiki page](https://en.wikipedia.org/wiki/Lempel%E2%80%93Ziv%E2%80%93Markov_chain_algorithm) for more information. + +| literal | +| -------- | +| `"lzma"` | + +### MD5 + +Represents the MD5 algorithm. MD5 is a widely used cryptographic hash function that produces a 128-bit hash value. The computational cost of MD5 is relatively low compared to other hash functions, but its short hash length makes it easier to find hash collisions. It is now considered insecure for cryptographic purposes, but can still used in non-security contexts. + +MD5 hashes are stored on-chain as 32 hexadecimal characters. + +See [the MD5 Wikipedia page](https://en.wikipedia.org/wiki/MD5) for more information. + +| literal | +| -------- | +| `"m_d5"` | + +### ObjectResponse + +ObjectResponse is the response of the Object query. + +| property | description | +| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | +| `compressed_size` | _(Required.) _ **[Uint128](#uint128)**. The size of the object when compressed. If the object is not compressed, the value is the same as `size`. | +| `compression_algorithm` | _(Required.) _ **[CompressionAlgorithm](#compressionalgorithm)**. The compression algorithm used to compress the content of the object. | +| `id` | _(Required.) _ **string**. The id of the object. | +| `is_pinned` | _(Required.) _ **boolean**. Tells if the object is pinned by at least one address. | +| `owner` | _(Required.) _ **string**. The owner of the object. | +| `size` | _(Required.) _ **[Uint128](#uint128)**. The size of the object. | + +### PageInfo + +PageInfo is the page information returned for paginated queries. + +| property | description | +| --------------- | ---------------------------------------------------------- | +| `cursor` | _(Required.) _ **string**. The cursor to the next page. | +| `has_next_page` | _(Required.) _ **boolean**. Tells if there is a next page. | + +### PaginationConfig + +PaginationConfig is the type carrying configuration for paginated queries. + +The fields are optional and if not set, there is a default configuration. + +| property | description | +| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | +| `default_page_size` | **integer**. The default number of elements in a page.

Shall be less or equal than `max_page_size`. Default to '10' if not set. | +| `max_page_size` | **integer**. The maximum elements a page can contain.

Shall be less than `u32::MAX - 1`. Default to '30' if not set. | + +### Passthrough + +Represents no compression algorithm. The object is stored as is without any compression. + +| literal | +| --------------- | +| `"passthrough"` | + +### SHA1 + +Represents the SHA-224 algorithm. SHA-224 is a variant of the SHA-2 family of hash functions that produces a 224-bit hash value. It is similar to SHA-256, but with a shorter output size. The computational cost of SHA-224 is moderate, and its relatively short hash length makes it easier to store and transmit. + +SHA-224 hashes are stored on-chain as 56 hexadecimal characters. + +See [the SHA-2 Wikipedia page](https://en.wikipedia.org/wiki/SHA-2) for more information. + +| literal | +| ---------- | +| `"sha224"` | + +### SHA256 + +Represents the SHA-256 algorithm. SHA-256 is a member of the SHA-2 family of hash functions that produces a 256-bit hash value. It is widely used in cryptography and other security-related applications. The computational cost of SHA-256 is moderate, and its hash length strikes a good balance between security and convenience. + +SHA-256 hashes are stored on-chain as 64 hexadecimal characters. + +See [the SHA-2 Wikipedia page](https://en.wikipedia.org/wiki/SHA-2) for more information. + +| literal | +| ---------- | +| `"sha256"` | + +### SHA384 + +Represents the SHA-384 algorithm. SHA-384 is a variant of the SHA-2 family of hash functions that produces a 384-bit hash value. It is similar to SHA-512, but with a shorter output size. The computational cost of SHA-384 is relatively high, but its longer hash length provides better security against hash collisions. + +SHA-384 hashes are stored on-chain as 96 hexadecimal characters. + +See [the SHA-2 Wikipedia page](https://en.wikipedia.org/wiki/SHA-2) for more information. + +| literal | +| ---------- | +| `"sha384"` | + +### SHA512 + +Represents the SHA-512 algorithm. SHA-512 is a member of the SHA-2 family of hash functions that produces a 512-bit hash value. It is widely used in cryptography and other security-related applications. The computational cost of SHA-512 is relatively high, but its longer hash length provides better security against hash collisions. + +SHA-512 hashes are stored on-chain as 128 hexadecimal characters. + +See [the SHA-2 Wikipedia page](https://en.wikipedia.org/wiki/SHA-2) for more information. + +| literal | +| ---------- | +| `"sha512"` | + +### Snappy + +Represents the Snappy algorithm. Snappy is a compression/decompression algorithm that does not aim for maximum compression. Instead, it aims for very high speeds and reasonable compression. + +See [the snappy web page](https://google.github.io/snappy/) for more information. + +| literal | +| ---------- | +| `"snappy"` | + +### Uint128 + +A string containing a 128-bit integer in decimal representation. + +| type | +| ----------- | +| **string**. | + +--- + +_Rendered by [Fadroma](https://fadroma.tech) ([@fadroma/schema 1.1.0](https://www.npmjs.com/package/@fadroma/schema)) from `axone-objectarium.json` (`3a53bb06f9b58538`)_ diff --git a/contracts_versioned_sidebars/version-v6.0.0-sidebars.json b/contracts_versioned_sidebars/version-v6.0.0-sidebars.json new file mode 100644 index 00000000000..cff0c94e170 --- /dev/null +++ b/contracts_versioned_sidebars/version-v6.0.0-sidebars.json @@ -0,0 +1,8 @@ +{ + "defaultSidebar": [ + { + "type": "autogenerated", + "dirName": "." + } + ] +} diff --git a/contracts_versions.json b/contracts_versions.json index 0c2de078135..56add4f8ca6 100644 --- a/contracts_versions.json +++ b/contracts_versions.json @@ -1,4 +1,5 @@ [ + "v6.0.0", "v5.0.0", "v4.1.0", "v4.0.0", From 44fc07770dc9459a0971e67cffb921ef7e546a48 Mon Sep 17 00:00:00 2001 From: Benjamin DENEUX Date: Mon, 5 Aug 2024 11:19:18 +0200 Subject: [PATCH 2/2] fix(contract): broken link with new contract name --- docs/technical-documentation/overview.mdx | 6 +++--- docusaurus.config.js | 2 +- sidebars.js | 2 +- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/technical-documentation/overview.mdx b/docs/technical-documentation/overview.mdx index 9bed4f5e819..3c0ff715a0d 100644 --- a/docs/technical-documentation/overview.mdx +++ b/docs/technical-documentation/overview.mdx @@ -45,7 +45,7 @@ Deepen your understanding of the Axone Protocol's Smart Contracts.
- +

Objectarium

Introducing the immutable on-chain Object Storage.

@@ -53,7 +53,7 @@ Deepen your understanding of the Axone Protocol's Smart Contracts.
- +

Cognitarium

Introducing the on-chain Semantic Storage layer.

@@ -61,7 +61,7 @@ Deepen your understanding of the Axone Protocol's Smart Contracts.
- +

Law Stone

Introducing the Governance Interpreter.

diff --git a/docusaurus.config.js b/docusaurus.config.js index 6c6a5386b1e..6a25393b90b 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -133,7 +133,7 @@ const config = { { type: 'docsVersionDropdown', position: 'right', - dropdownItemsAfter: [{ to: '/contracts/okp4-cognitarium', label: 'Latest version' }], + dropdownItemsAfter: [{ to: '/contracts/axone-cognitarium', label: 'Latest version' }], docsPluginId: 'contracts', dropdownActiveClassDisabled: true }, diff --git a/sidebars.js b/sidebars.js index c55faf393b1..bd4207528e1 100644 --- a/sidebars.js +++ b/sidebars.js @@ -109,7 +109,7 @@ const sidebars = { { type: 'link', label: 'Smart contracts', - href: '/contracts/okp4-cognitarium' + href: '/contracts/axone-cognitarium' }, { type: 'link',