How the GEO Protocol’s trustline-related database is organized
In our previous article, we briefly introduced the basic concept of trustlines. Now we’re going to dive back into the subject for more details. But first things first — in this article, we will discuss GEO Protocol’s trustline database structure; and the following article will deal with the GEO trustline mechanics.
So, let’s get started!
Trustline DB Structure
As we’ve already discussed, all the information about a node’s connections and operations, as well as its current state, is only stored on that very node itself (locally, in an SQLite relational database).
Technically there is no separate trustline database, but a portion of the complete node’s relational database is dedicated to trustlines and operations with them. So, here we will describe the part of the node’s database relevant to the storage of trustline information. This is how the overall structure looks schematically:
Please note that this is currently under active development, so some details are subject to change. For the most current version, you can always refer to the documentation on GEO Protocol GitHub. We’ll outline here the current status, which is more than sufficient to dive deeper into the trustline logic.
So, as you can see, we have several tables here. Let’s have a closer look at each of these tables and the fields they contain.
Trustlines table
The first table is the trust_lines table, and it consists of the following fields:
- id
- contractor_id
- state
- equivalent
id field contains a unique positive integer that consists of 4 bytes. It is used to identify the trustline by the node. Every node uses its own identification order for its trustlines that doesn’t synchronize with other nodes. This means that the same trustline between two nodes could, and most likely will, have different ID numbers on each side of the trustline, i.e. in each of the nodes’ databases. Trustline id is used to link all the trustline data that could be stored in different tables of the relational database.
contractor_id field contains a unique positive integer that consists of 4 bytes. It is used to identify a node with which the current node has opened a trustline. We call such a node a Contractor. This field is used to link the trust_lines table to the contractors table.
state field contains a positive integer that consists of 1 byte. It defines the state of the trustline and can have one of the following values: Init (1), Active (2), AuditPending (3), Archived (4), Conflict (5), ConflictResolving (6). The meaning of the states will be described in the next article.
equivalent field contains a positive integer that consists of 4 bytes. It identifies an equivalent in which the trustline is opened.
Contractors table
The next one is the contractors table that consists of the following fields:
- id
- id_on_contractor_side
- crypto_key
id field here is the same identifier that is located in the contractor_id field of the trust_lines table and is used to relate a trustline to a particular contractor.
id_on_contractor_side field contains a unique positive integer that consists of 4 bytes. It is used to identify the current node by the contractor node (since, as was mentioned above, every node has its own identification order of its contractors).
crypto_key field contains cryptographic data that is used to encrypt and decrypt all types of trustline-related communication messages, as well as for some payment-related messages between the two nodes.
Addresses table
Next, we come to the addresses table, consisting of the following fields:
- contractor_id
- address_type
- address
As a node can have several addresses of different types, all of that information is stored in this table and is linked to a particular node by its contractor_id.
Keys tables (own_keys, contractor_keys)
Every trustline operation requires that both participants agree on it. This agreement is reached by signing with Lamport signatures of both sides, so there are two tables for storing them: own_keys and contractor_keys.
These tables have a similar field structure, but the own_keys table has one additional field — private_key. And here are the fields that these two tables have in common:
- hash
- trust_line_id
- public_key
- number
- is_valid
hash field contains a 32-byte hash value of the public key in the same table. It is used to link the public key with other entities in the database.
trust_line_id field contains the trustline identifier that is located in the id field of the trust_lines table and is used to relate a key to a particular trustline.
public_key field contains a 16-kilobyte public key (own or contractor’s, depending on which table this field is) of the Lamport key pair.
number field contains a sequence number of a key in the node’s key pool (see the Trustline Mechanics article — ADD LINK) and consists of 4 bytes.
is_valid field contains a byte field with a value of either 1 or 0, which indicates whether the key was already used or not.
private_key field is present only in the own_keys table. It contains a 16-kilobyte private key of the Lamport key pair.
Audits table
This table stores the current state of every trustline, which we call the “audits”, signed by both parties. The audit is conducted after every change to the trustline (such as opening, setting, or closing a trustline), as well as when triggered by an audit rule.
So, the audits table contains the following fields:
- number
- trust_line_id
- own_key_hash
- own_signature
- contractor_key_hash
- contractor_signature
- balance
- incoming_trust_amount
- outgoing_trust_amount
number field contains a positive integer that consists of 4 bytes and defines the sequence number of an audit. The sequence number is needed to prevent various possible manipulations with audits order.
trust_line_id field contains the same identifier of a trustline as that found in the id field of the trust_lines table and is used to relate an audit to particular trustline.
own_key_hash field contains a 32-byte hash value of the public key from the pair with which the node has signed the current audit. It is the same value that the field hash from the own_keys table contains, and it is used to relate this key to a particular audit.
own_signature field contains an 8-kilobyte signature of the current audit performed by the node.
contractor_key_hash field contains a 32-byte hash value of the public key from the pair with which the contractor has signed the current audit. It is the same value that the field hash from the contractor_keys table contains, and it is used to relate this key to a particular audit.
contractor_signature field contains an 8-kilobyte signature of the current audit performed by the contractor.
The fields balance, incoming_trust_amount, and outgoing_trust_amount contain the values of Current Balance (CB), Incoming (ITA), and Outgoing Trust Amounts (OTA). We described these trustline properties in our previous article [ADD LINK]. Here we will just mention that CB is a 33-byte integer, and ITA and OTA are 32-byte integers.
Payment receipts tables
In a course of payment transactions, a node can receive or send a particular amount, from or to its neighbours. These amounts are stored in two tables: incoming_payment_receipts and outgoing_payment_receipts.
These tables have a similar field structure, except that the incoming_payment_receipts table has one additional field — the signature. And here are the fields that these two tables have in common:
- trust_line_id
- audit_number
- transaction_uuid
- key_hash
- amount
trust_line_id field contains the same identifier of a trustline as that which is located in the id field of the trust_lines table and is used to relate a receipt to particular trustline.
audit_number field contains the same identifier of an audit as that which is used in the number field of the audit table. This field defines that the current receipt belongs to a particular audit.
transaction_uuid field contains 16 bytes of a universally unique identifier of a payment transaction that this receipt belongs to.
key_hash field contains a 32-byte hash value of a public key: the contractor’s (if this field is in the incoming_payment_receipts table) or the node’s own (if this field is in the outgoing_payment_receipts table).
amount field contains a 32-byte integer that quantifies a sum that was transferred.
signature is the field that is present only in the incoming_payment_receipts table and contains an 8-kilobyte signature of the current incoming receipt.
Registry of Equivalents
The features table isn’t solely a part of the trustline database structure (since it is also used for other things), but a part of this table definitely is. And that’s the following field in particular:
- equivalents_register_address
The equivalents_register_address field contains an address of the Registry of Equivalents that the node uses (currently, Ethereum Contract Address). This network-wide registry contains the list of all equivalents (like BTC, USD, etc) that are used in the GEO network, as well as their identifiers. All trustlines and transactions of all nodes in the network should use the same registry, so the node can be sure that given identifiers correspond to their appropriate equivalents.
However, it is technically possible that a particular node (or a group of nodes) can use a different registry of equivalents (their own, for instance). So, to avoid confusion (when one node thinks that it sends, for example, BTC, and another node thinks it gets, let’s say, ETH on the very same trustline) it is not possible for the two nodes to open a trustline between them if these nodes have different Registry of Equivalents. Moreover, if a node opens a trustline with another, using a particular registry address, all other trustlines of this node must be opened using the same address.
The check necessary to ensure this is performed, during the trustline opening procedure, is described in the “How do trustlines operate in GEO Protocol” article.
So that’s how the GEO Protocol’s trustline database structure connects to the GEO node’s relational database.
In the next article, we’ll explore the GEO trustline mechanics, i.e. how trustlines operate in GEO Protocol.
For those of you who like watching more than reading, Dima Chizhevsky is explaining trustline database structure in this video on our youtube channel:
