Smart contracts
1. Meet with the Smart Contracts
Once you reach this stage, you are starting to develop a solid understanding of governance in the OKP4 protocol and an idea of how it is implemented, mainly through its powerful Prolog logical interpreter.
In the upcoming chapters, I will delve more concretely into the different building blocks that shape the on-chain governance implementation, unveiling the architectural and technical specifics of the OKP4 protocol.
1.1 CosmWasm
CosmWasm is the smart contract platform used by the OKP4 protocol. It offers a secure and efficient environment for executing smart contracts in multiple programming languages. One language in particular, Rust, stands out for its emphasis on safety, performance, and concurrency. We utilize Rust to build secure and efficient smart contracts within the OKP4 ecosystem, leveraging its benefits.
1.2 Storage-oriented Smart Contracts
Ensuring proper mechanisms for storing and querying information in the blockchain is of utmost importance. Due to the diverse nature of information, it becomes necessary to have different types of storage to address specific requirements.
Within the OKP4 protocol, we have introduced a class of smart contracts called "storage-oriented smart contracts." These contracts act as reliable repositories, offering secure, efficient, and auditable storage and retrieval of various data types on the blockchain.
We have specifically focused on two classes of smart contracts: object storage and semantic storage. These smart contracts act as a foundational support layer for implementing governance, making them vital for its existence.
1.2.1 The Objectarium
The Objectarium smart contract enables the storage of arbitrary unstructured Objects in any Cosmos blockchain. It provides a flexible solution for storing data without imposing strict schemas or predefined structures, accommodating various data formats and types.
Key concepts
Object: In the context of the 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 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.
Instantiation
The Objectarium smart contract should be instantiated before being used, and an instance creates a bucket. The instantiation of the Objectarium smart contract allows the definition of usage policies, including limits on the maximum total size, object size, and number of objects, as well as the configuration of a hash algorithm for generating unique identifiers.
Mutations
Store Object: Allows the user to store an object in the bucket. The sender becomes the object's owner, referenced by the hash of its content. If the object is already stored, an error is returned. The user can pin the object, preventing its removal from storage. Additionally, the user can specify a compression algorithm to reduce storage space, although it may increase CPU usage and gas cost.
Forget Object
Unpins the object from the bucket for the sender and removes it from storage if it is no longer pinned. However, if other senders pin the object, it remains in storage, and an error is returned.
Pin Object: The user can pin an object in the bucket for the sender. While an object is pinned, it cannot be removed from storage.
Unpin Object: Allows the user to unpin an object from the bucket for the sender. Once unpinned, the object can be removed from storage if there are no other pins.
Queries
Bucket: Retrieves information about the bucket, including its name, configuration, limits…
Object: Retrieves information about a specific object given its identifier, including the owner, pin status, size, compressed size, and compression algorithm.
Objects: Retrieves a list of objects in the bucket with support for pagination. It allows filtering by the owner's address, limiting the number of objects returned and starting at a specific point in the sequence.
Object Data: Retrieves the content of a specific object based on its identifier.
Object Pins: Retrieves a list of addresses that have pinned a specific object with support for pagination.
The Objectarium smart contract enables the storage of arbitrary unstructured Objects in any Cosmos blockchain. It provides a flexible solution for storing data without imposing strict schemas or predefined structures, accommodating various data formats and types.
Key concepts
Object: In the context of the 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 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.
Instantiation
The Objectarium smart contract should be instantiated before being used, and an instance creates a bucket. The instantiation of the Objectarium smart contract allows the definition of usage policies, including limits on the maximum total size, object size, and number of objects, as well as the configuration of a hash algorithm for generating unique identifiers.
Mutations
Store Object: Allows the user to store an object in the bucket. The sender becomes the object's owner, referenced by the hash of its content. If the object is already stored, an error is returned. The user can pin the object, preventing its removal from storage. Additionally, the user can specify a compression algorithm to reduce storage space, although it may increase CPU usage and gas cost.
Forget Object
Unpins the object from the bucket for the sender and removes it from storage if it is no longer pinned. However, if other senders pin the object, it remains in storage, and an error is returned.
Pin Object: The user can pin an object in the bucket for the sender. While an object is pinned, it cannot be removed from storage.
Unpin Object: Allows the user to unpin an object from the bucket for the sender. Once unpinned, the object can be removed from storage if there are no other pins.
Queries
Bucket: Retrieves information about the bucket, including its name, configuration, limits…
Object: Retrieves information about a specific object given its identifier, including the owner, pin status, size, compressed size, and compression algorithm.
Objects: Retrieves a list of objects in the bucket with support for pagination. It allows filtering by the owner's address, limiting the number of objects returned and starting at a specific point in the sequence.
Object Data: Retrieves the content of a specific object based on its identifier.
Object Pins: Retrieves a list of addresses that have pinned a specific object with support for pagination.
1.2.2 The Cognitarium
The Cognitarium smart contract facilitates the storage and querying of semantic data using RDF (Resource Description Framework), which represents information as semantic triples. In essence, it serves as a repository for knowledge, providing a dedicated space for storing and retrieving semantic information within any Cosmos blockchains.
Key concepts
Semantic Triples: The Cognitarium smart contract implements a variant of a triple store (https://en.wikipedia.org/wiki/Triplestore), a data structure used to store and query RDF (Resource Description Framework) triples. RDF triples consist of subject-predicate-object statements that represent relationships between entities.
Data Formats: The Cognitarium smart contract supports multiple data formats for serializing/de-serializing RDF triples, such as RDF/XML, Turtle, N-Triples, and N-Quads. The data format can be specified where relevant, allowing users to interact with the smart contract using their preferred format.
Contract Owner Authorization: Only the smart contract owner, i.e., the address that instantiated the contract, can perform mutations (inserting and deleting data) on the Cognitarium. This authorization mechanism ensures that only trusted entities can modify the smart contract's state.
Instantiation:
The Cognitarium smart contract should be instantiated before being used, and an instance creates a logical container where triples are stored. By instantiating the smart contract, you can define limitations on the use of storage. These limitations include the maximum number of triples, the maximum byte size, the maximum triple size, the maximum query limit, the maximum number of query variables, the maximum insert data byte size and the maximum number of insert data triples, … Configuring these limitations is crucial to ensure the security and performance of the contract instance. It is important to adjust them according to the desired contract policy.
Mutations:
Insert Data: Inserts RDF triples into the store. It allows to specification the data format (e.g. RDF XML, Turtle, NTriples, NQuads), which specifies how the triples are de-serialized, and the data itself in binary format.
Delete Data: Deletes RDF triples from the store based on specified patterns defined by a query.
The previous mutations can only be performed by the smart contract owner, which refers to the address that instantiated the contract.
Queries: Queries provide a means to access knowledge. However, it is essential to note that due to the constrained environment in which smart contracts execute, the Cognitarium may offer different query flexibility than a traditional database. However, it still provides a functional range that allows targeted access to knowledge in a suitable representation, ensuring access to the desired information.
Select: The Select query allows users to retrieve semantic resources that meet specific criteria defined in the query. By executing a Select query, the Cognitarium returns a result set of resources that match the specified conditions. Users can define the query parameters, such as prefixes, select items (variables to be replaced), a WHERE clause for filtering, and an optional limit on the number of results. The Select query provides a flexible way to retrieve specific data from the semantic store.
Describe: The Describe query is used to obtain a detailed description of a specific resource identified by an IRI (Internationalized Resource Identifier). The Describe query enables users to retrieve a comprehensive representation of a resource's attributes and relationships in a format that suits their needs. By executing a Describe query, the smart contract returns a set of RDF triples that describe the resource in question. Users can specify the resource to describe using its IRI and the desired format for the serialized triples (e.g., RDF/XML, Turtle, N-Triples, N-Quads).
It should be noted that these two query forms are subject to the limitations set in the contract instance. These limitations are in place to ensure security, performance, and resource management within the smart contract environment. They define constraints such as the maximum number of triples returned by a Select query, the maximum number of variables that can be selected, and the maximum size of an insert data query.
1.3 Sovereignty-oriented Smart Contracts
1.3.1 The "sovereignty" class
As you already know, smart contracts are self-executing agreements with terms directly written in code, stored and executed on a blockchain. Among these contracts, the OKP4 protocol recognizes a specific class: sovereignty-oriented smart contracts. These contracts are designed to prioritize the sovereignty of the involved parties by allowing them to define and enforce their own rules and regulations. For further information on this topic, please refer to Part I of this saga.
The implementation of on-chain governance in the OKP4 protocol relies on this specific class of smart contracts, with the first one being responsible for the legislative aspects of governance: The Law Stone.
1.3.2 The Law Stone
The Law-Stone is a highly versatile smart contract designed to apply and enforce legislative rules, including Zone rules, Consents, and Agreements. It offers extraordinary adaptability and can be utilized in any blockchain within the Cosmos ecosystem that seeks to establish robust and flexible on-chain governance systems. With its exceptional proficiency in evaluating logical rules, Law-Stone can be applied across various use cases.
The smart contract has two sides:
The side of the "Law": Indeed, the smart contract interprets the law, i.e. makes a judgement on what is legal, permissible or prohibited according to the result of execution of the rules of governance informed by the knowledge available at the time of this interpretation.
The side of the "Stone": The instantiation of the smart contract engraves in stone the rules to be interpreted, and these are immutable, irrevocable, and indisputable unless the stone is broken.
Key concepts
Prolog: Yes, you know it already; the well-known Logic Programming Language is used to encode the law rules and facts in the OKP4 protocol. The Prolog program, which carries the immutable Laws, is provided during the contract's instantiation, symbolically engraving them into a Stone.
The Stone: Similar to the laws engraved on stone tablets, the Law Stone represents an intangible and unalterable foundation of legal principles within the contract. Once carved in the stone, which occurs during the instantiation of the smart contract, the laws become indisputable, ensuring their strength, effects, and application.
One instance — one stone — one law: This principle implies that each instance of the Law-Stone smart contract represents a distinct Law (i.e. governance), ensuring the separation and independence of the laws. Each instance's unique power, effects, and scope define its specific governance.
Objectarium storage: In the Law-Stone smart contract, the responsibility for storing logical programs is delegated to the Objectarium smart contract. By separating the storage functionality from the Objectarium, the Law-Stone contract can focus on interpreting the Prolog programs. At the same time, the Objectarium handles the secure and efficient storage of Prolog programs. This design choice aligns with the principle of Single Responsibility, ensuring that each contract focuses on its specific task.
Law Composability: The principle of "Law Composability" allows for the reusability and composition of the Prolog code. By leveraging the "consult/1" predicate, logical Prolog code can be imported from the Objectarium, enabling the construction of new logic programs by combining existing pieces of rules. This flexibility promotes modularity and code composition, facilitating the creation of intricate and tailored legal logic within the Law Stone contract.
Break the Stone: Refers to the specific and irreversible action that renders the contract null and unusable. This metaphorical term symbolizes the act of terminating the agreement by breaking the stone on which its words are inscribed. By breaking the rock, the contract is effectively rendered inoperable, preventing any further execution of queries, actions, or interactions. Due to its irreversible consequences and the potential effects it could generate, the authorization to break the stone is typically restricted to the contract administrator.
Instantiation:
The Law-Stone smart contract requires instantiation before it can be used, creating a new Stone where the law is engraved. By instantiating the smart contract, you provide the Prolog program containing the law rules and facts, along with the address of the Objectarium contract where the logical program will be stored.
Mutation:
Break the Stone: As its name suggests, this operation breaks the stone, making the contract unusable. It clears all the related resources, such as unpinning pinned objects on the Objectarium contract and forgetting the Prolog program. Only the contract admin, if any, can execute this message.
Query:
Ask: Enables users to seek the interpretation of the law, obtaining judgments on what is deemed legal, permissible, or prohibited. This interpretation of the law is intricately tied to the context at hand, which encompasses a set of accepted facts such as the state of the blockchain or the available knowledge. Questioning the law is the foundational process that gives birth to governance, as it yields answers that establish the rules and boundaries in a specific context.
1.3.3 The Pactum
The Pactum smart contract is designed to streamline and automate the execution of agreements involving multiple parties. In contrast to the Law-Stone, which primarily focuses on expressing or stating the law, the Pactum's core function is to actively execute the law by the predefined terms outlined in the agreement. By leveraging the power of Prolog provided by the Law-Stone smart contract, the Pactum facilitates the seamless implementation of agreed-upon terms and ensures the proper enforcement of contractual obligations.
This smart contract is essential in the governance framework implemented in the OKP4 protocol, particularly in regulating the orchestration of digital resources, which involves many parties.
Key concepts
Agreement: An agreement between two or more parties that outlines the terms, conditions, and obligations each party agrees to abide by. This agreement is represented by a Prolog program engraved in a Law-Stone instance.
Sealing Conditions: This segment of the agreement delineates the prerequisites that must be fulfilled for the contract to be deemed complete and unmodifiable, ensuring its readiness for execution. For instance:
The Cognitarium smart contract facilitates the storage and querying of semantic data using RDF (Resource Description Framework), which represents information as semantic triples. In essence, it serves as a repository for knowledge, providing a dedicated space for storing and retrieving semantic information within any Cosmos blockchains.
Key concepts
Semantic Triples: The Cognitarium smart contract implements a variant of a triple store (https://en.wikipedia.org/wiki/Triplestore), a data structure used to store and query RDF (Resource Description Framework) triples. RDF triples consist of subject-predicate-object statements that represent relationships between entities.
Data Formats: The Cognitarium smart contract supports multiple data formats for serializing/de-serializing RDF triples, such as RDF/XML, Turtle, N-Triples, and N-Quads. The data format can be specified where relevant, allowing users to interact with the smart contract using their preferred format.
Contract Owner Authorization: Only the smart contract owner, i.e., the address that instantiated the contract, can perform mutations (inserting and deleting data) on the Cognitarium. This authorization mechanism ensures that only trusted entities can modify the smart contract's state.
Instantiation:
The Cognitarium smart contract should be instantiated before being used, and an instance creates a logical container where triples are stored. By instantiating the smart contract, you can define limitations on the use of storage. These limitations include the maximum number of triples, the maximum byte size, the maximum triple size, the maximum query limit, the maximum number of query variables, the maximum insert data byte size and the maximum number of insert data triples, … Configuring these limitations is crucial to ensure the security and performance of the contract instance. It is important to adjust them according to the desired contract policy.
Mutations:
Insert Data: Inserts RDF triples into the store. It allows to specification the data format (e.g. RDF XML, Turtle, NTriples, NQuads), which specifies how the triples are de-serialized, and the data itself in binary format.
Delete Data: Deletes RDF triples from the store based on specified patterns defined by a query.
The previous mutations can only be performed by the smart contract owner, which refers to the address that instantiated the contract.
Queries: Queries provide a means to access knowledge. However, it is essential to note that due to the constrained environment in which smart contracts execute, the Cognitarium may offer different query flexibility than a traditional database. However, it still provides a functional range that allows targeted access to knowledge in a suitable representation, ensuring access to the desired information.
Select: The Select query allows users to retrieve semantic resources that meet specific criteria defined in the query. By executing a Select query, the Cognitarium returns a result set of resources that match the specified conditions. Users can define the query parameters, such as prefixes, select items (variables to be replaced), a WHERE clause for filtering, and an optional limit on the number of results. The Select query provides a flexible way to retrieve specific data from the semantic store.
Describe: The Describe query is used to obtain a detailed description of a specific resource identified by an IRI (Internationalized Resource Identifier). The Describe query enables users to retrieve a comprehensive representation of a resource's attributes and relationships in a format that suits their needs. By executing a Describe query, the smart contract returns a set of RDF triples that describe the resource in question. Users can specify the resource to describe using its IRI and the desired format for the serialized triples (e.g., RDF/XML, Turtle, N-Triples, N-Quads).
It should be noted that these two query forms are subject to the limitations set in the contract instance. These limitations are in place to ensure security, performance, and resource management within the smart contract environment. They define constraints such as the maximum number of triples returned by a Select query, the maximum number of variables that can be selected, and the maximum size of an insert data query.
1.3 Sovereignty-oriented Smart Contracts
1.3.1 The "sovereignty" class
As you already know, smart contracts are self-executing agreements with terms directly written in code, stored and executed on a blockchain. Among these contracts, the OKP4 protocol recognizes a specific class: sovereignty-oriented smart contracts. These contracts are designed to prioritize the sovereignty of the involved parties by allowing them to define and enforce their own rules and regulations. For further information on this topic, please refer to Part I of this saga.
The implementation of on-chain governance in the OKP4 protocol relies on this specific class of smart contracts, with the first one being responsible for the legislative aspects of governance: The Law Stone.
1.3.2 The Law Stone
The Law-Stone is a highly versatile smart contract designed to apply and enforce legislative rules, including Zone rules, Consents, and Agreements. It offers extraordinary adaptability and can be utilized in any blockchain within the Cosmos ecosystem that seeks to establish robust and flexible on-chain governance systems. With its exceptional proficiency in evaluating logical rules, Law-Stone can be applied across various use cases.
The smart contract has two sides:
The side of the "Law": Indeed, the smart contract interprets the law, i.e. makes a judgement on what is legal, permissible or prohibited according to the result of execution of the rules of governance informed by the knowledge available at the time of this interpretation.
The side of the "Stone": The instantiation of the smart contract engraves in stone the rules to be interpreted, and these are immutable, irrevocable, and indisputable unless the stone is broken.
Key concepts
Prolog: Yes, you know it already; the well-known Logic Programming Language is used to encode the law rules and facts in the OKP4 protocol. The Prolog program, which carries the immutable Laws, is provided during the contract's instantiation, symbolically engraving them into a Stone.
The Stone: Similar to the laws engraved on stone tablets, the Law Stone represents an intangible and unalterable foundation of legal principles within the contract. Once carved in the stone, which occurs during the instantiation of the smart contract, the laws become indisputable, ensuring their strength, effects, and application.
One instance — one stone — one law: This principle implies that each instance of the Law-Stone smart contract represents a distinct Law (i.e. governance), ensuring the separation and independence of the laws. Each instance's unique power, effects, and scope define its specific governance.
Objectarium storage: In the Law-Stone smart contract, the responsibility for storing logical programs is delegated to the Objectarium smart contract. By separating the storage functionality from the Objectarium, the Law-Stone contract can focus on interpreting the Prolog programs. At the same time, the Objectarium handles the secure and efficient storage of Prolog programs. This design choice aligns with the principle of Single Responsibility, ensuring that each contract focuses on its specific task.
Law Composability: The principle of "Law Composability" allows for the reusability and composition of the Prolog code. By leveraging the "consult/1" predicate, logical Prolog code can be imported from the Objectarium, enabling the construction of new logic programs by combining existing pieces of rules. This flexibility promotes modularity and code composition, facilitating the creation of intricate and tailored legal logic within the Law Stone contract.
Break the Stone: Refers to the specific and irreversible action that renders the contract null and unusable. This metaphorical term symbolizes the act of terminating the agreement by breaking the stone on which its words are inscribed. By breaking the rock, the contract is effectively rendered inoperable, preventing any further execution of queries, actions, or interactions. Due to its irreversible consequences and the potential effects it could generate, the authorization to break the stone is typically restricted to the contract administrator.
Instantiation:
The Law-Stone smart contract requires instantiation before it can be used, creating a new Stone where the law is engraved. By instantiating the smart contract, you provide the Prolog program containing the law rules and facts, along with the address of the Objectarium contract where the logical program will be stored.
Mutation:
Break the Stone: As its name suggests, this operation breaks the stone, making the contract unusable. It clears all the related resources, such as unpinning pinned objects on the Objectarium contract and forgetting the Prolog program. Only the contract admin, if any, can execute this message.
Query:
Ask: Enables users to seek the interpretation of the law, obtaining judgments on what is deemed legal, permissible, or prohibited. This interpretation of the law is intricately tied to the context at hand, which encompasses a set of accepted facts such as the state of the blockchain or the available knowledge. Questioning the law is the foundational process that gives birth to governance, as it yields answers that establish the rules and boundaries in a specific context.
1.3.3 The Pactum
The Pactum smart contract is designed to streamline and automate the execution of agreements involving multiple parties. In contrast to the Law-Stone, which primarily focuses on expressing or stating the law, the Pactum's core function is to actively execute the law by the predefined terms outlined in the agreement. By leveraging the power of Prolog provided by the Law-Stone smart contract, the Pactum facilitates the seamless implementation of agreed-upon terms and ensures the proper enforcement of contractual obligations.
This smart contract is essential in the governance framework implemented in the OKP4 protocol, particularly in regulating the orchestration of digital resources, which involves many parties.
Key concepts
Agreement: An agreement between two or more parties that outlines the terms, conditions, and obligations each party agrees to abide by. This agreement is represented by a Prolog program engraved in a Law-Stone instance.
Sealing Conditions: This segment of the agreement delineates the prerequisites that must be fulfilled for the contract to be deemed complete and unmodifiable, ensuring its readiness for execution. For instance:
- Required Approvals / Signatures: These conditions ascertain when all parties consider the agreement approved or accepted.
- Token Holdings: These conditions verify if the token quantities held by each party align with the agreed-upon requirements.
Contract Effect: This segment of the agreement outlines the anticipated results or actions expected to occur upon the successful execution of the contract, encompassing activities such as fund transfers or other specified effects.
In the forthcoming articles delving into the OKP4 protocol, there will be a detailed exploration of the Pactum smart contract, specifically within the context of Orchestration.
In the forthcoming articles delving into the OKP4 protocol, there will be a detailed exploration of the Pactum smart contract, specifically within the context of Orchestration.