Skip to content

Understanding Golem Base entities

A golem base entity is data that you can store inside a custom fork of op-geth called Golem-base Op-geth that extends the Ethereum Trie (informally known as the store) to support structured data entities.

An entity consists of raw data (called the payload), which can be any data you like, whether it’s text, such as a document, or binary data, such as an image, along with any number of key-value pairs (called annotations) that you choose to accompany the payload. The key-value pairs can hold either strings or numbers for the values; the keys are always strings. Additionally, you can specify for how many blocks the data should live (called Blocks to Live, or BTL).

Because this data lives in the state trie, it will get replicated across all nodes participating in the same chain, as long as they are syncing state normally. (Nodes on the same chain that aren’t running golem-base op-geth will still replicate the data; they just won’t know recognize the structure, meaning they won’t be able to respond to requests to read or modify the data.)

Creating Entities

To create an entity, you must provide:

  • A data value
  • Number of blocks to live

Optionally you can provide:

  • StringAnnotations: Any number of key-value pairs where the values are string
  • NumericAnnotations: Any number of key-value pairs where the values are numbers

Note: The keys don't have to be unique; you can provide two separate string annotations that share the same key, such as (Name: "Fred"), (Name: "Frederick"). A good application of this is if you're storing users, and you want them to be able to have multiple phone numbers or multiple email addresses. For example, you might have one annotation for "email" and then several entries for "email_alternate":

[("email", "fred@example.com"), ("email_alternate", "fred@sample.com"), ("email_alternate", "fred@another.com")]

Updating and Extening Entities

Querying Entities

Understanding entity transactions

To store an entity, we send a transaction listing for the “to” recipient a specific address that we’ve allocated. The transaction contains a 0 for the value, along with any number of create, update, and delete instructions for entities.

When a create instruction is included in the transaction, the golem-base op-geth node that receives the transaction will store the entity in its trie, and return a unique hash identifying the entity. Update and delete instructions can then reference this hash.

We support two types of update instructions; one for updating the payload, annotations, and/or blocks to live; and another specifically for updating only blocks to live by extending it by the given number of blocks.

Transactions are sent through JSON RPC. However, while we could do that ourselves, instead we rely on a helper function in Web3 called SendRawTransaction. This function encodes the transaction and signs it, and then sends it out by calling the JSON RPC method eth_sendRawTransaction.

The Python SDK supplies functions for creating multiple entities at once, updating multiple entities, deleting multiple entities, and extending multiple entities. Internally these functions call a send_transaction function that’s also available to the SDK user in case they want to combine instructions across multiple creates, deletes, updates, and extends.

Todo: Find out what happens if any individual operation (CREATE, UPDATE, DELETE, EXTEND) fails. (Either check code or ask Dragan)

Todo: Find out more info about gas, maxFeePerGas, maxPriorityFeePerGas