Skip to main content

Claims Key/Value Storage System

Claims in Coinweb​

Claims in Coinweb are key/value storage objects that are fundamental to the operation of smart contracts. They are similar to UTXOs in Bitcoin, in that they store value and have specific rules for access. Claims consist of an issuer (owner), a key, a body, and some amount of CWEB (Coinweb's native token).

Structure of a Claim​

Claims have a three-level key structure:

  1. Issuer: The creator of the claim, typically a smart contract.
  2. First Key: Often used as the "table name" in the context of the claim.
  3. Second Key: Used as the "key in table", providing an additional level of organization within the claim.

This structure allows a smart contract to have multiple key-value tables, with the table name as the first key and the keys within those tables as the second key. The first key acts as the table or group identifier, allowing for a manageable set of possible values. For example, if an arbitrary value such as a transaction ID becomes the first key that groups the claims, it will lead to each transaction ID having its own isolated table, which is not ideal.

Claims-Storage Design

When designing claims keys, it is recommended to follow these rules:

  1. Both the first key and the second key MUST NOT be null.
  2. The first key MUST NOT be unique.

Justification for the Rules​

  • Efficient Querying:

    • If the first key has a limited set of possible values, it allows for efficient grouping and querying of related claims. For instance, if the first key represents transaction types, it’s easy to query all claims related to a specific transaction type.
    • If the second key is used for more granular identifiers, such as specific transaction IDs, range queries within these groups become feasible and efficient.

  • Scalability and Management:

    • A fixed or limited number of possible first keys ensures the system remains scalable and manageable. Having a bound on the number of unique first keys helps in organizing and indexing the claims efficiently.
    • On the other hand, the second key can have a larger domain, allowing detailed and fine-grained organization within each group defined by the first key.

Example Scenarios​

  1. Correct Usage:
 {
   "first_key": "transaction_type_A",
   "second_key": "txid_123"
 }
 {
   "first_key": "transaction_type_A",
   "second_key": "txid_124"
 }

Here, transaction_type_A is the first key and is not unique. It groups all claims of this type, and txid_123 and txid_124 are second keys that allow for fine-grained identification within this group.

  1. Incorrect Usage:
{
  "first_key": "txid_123",
  "second_key": "detail_1"
}
{
  "first_key": "txid_124",
  "second_key": "detail_2"
}

Here, the first key txid_123 and txid_124 are unique. This results in each transaction ID acting as an isolated table, preventing efficient range queries and grouping.

Considerations​

  • If the user does not need range queries, the impact of violating the first key rule might be less significant. However, adhering to the rule is generally recommended to maintain a scalable and efficient system.
  • The (value) domain of the first key should be small and manageable, while the (value) domain of the second key can be large to allow detailed organization within each group.

By following these guidelines, the system will be better organized, scalable, and efficient for querying and managing claims.

Operations on Claims​

Smart contracts interact with claims through various operations:

  • TakeOp: Allows the issuer of a claim to retrieve the stored CWEB, effectively transferring value into the currently executing transaction.
  • StoreOp: Enables the storage of claims in the database, which can also include CWEB from the current transaction.
  • ReadOp: Permits reading the data of a claim without transferring value.

Queries on Claims​

While it is not possible to fetch all claims for a given contract_id in a single query, range queries on the second key are supported. These queries are limited in scope to ensure efficient use of I/O, time, and CPU resources.

Transactions and Claims​

A transaction in Coinweb is a list of operations that can include TakeOp, StoreOp, ReadOp, BlockOp, DataOp, and CallOp. Transactions can invoke smart contracts, pass on CWEB, and store or retrieve data as needed. Smart contracts use these transactions to manage their state and interact with other contracts and the blockchain.

Integration with Smart Contracts​

Claims are integral to the functioning of smart contracts in Coinweb. They provide a flexible and powerful way to store and manage state, transfer value, and interact with the blockchain. Whether you are building a new smart contract or integrating an existing one, understanding claims is essential for effective development on the Coinweb platform.

For more detailed examples and use cases, refer to the specific documentation on smart contract operations and the data-hasher contract.