The Vx is a postgres based API. You connect with any client that implements the postgres wire format. You will be given two connection-strings (reader and writer). The writer can read and write. The reader can only read. Only use the writer if you need to actually write (i.e. the game server) and it will be given higher priority. Use the reader account for stuff like auditing/exploring.

Core Tables

commitments

This is the commitments the game server has made to a particular seed

 
CREATE TABLE commitments(
  id              UUID              PRIMARY KEY DEFAULT uuid_generate_v7(), -- as a uuidv7 this encodes the time it was created
  commitment      bytea             NOT NULL, -- what the game server is commiting to
  context         bytea             NOT NULL, -- The protocol buffers encoded metadata. See: https://github.com/actuallyfair/verifier/blob/master/protobuf/commitment-context.proto
  vx_pubkey       bytea             NOT NULL DEFAULT bls_pubkey_set_by_vx()
);
CREATE INDEX commitments_commitment_idx ON commitments(commitment, id);

Only the writer user account will be allowed to insert into this table. It is an error to use your own id or vx_pubkey. Let us do that for you. You would typically insert with something like: INSERT INTO commitments(commitment, context) VALUES($1, $2) RETURNING id, vx_pubkey to insert and retrieve what you need in one query

messages

The real work horse. This is either bets, games or sub-bets


CREATE TABLE messages(
  id                  UUID             PRIMARY KEY DEFAULT uuid_generate_v7(), -- as a uuidv7 this encodes the time it was created
  commitment          bytea            NOT NULL, -- should reference commitments.commitment (but isn't enforced)
  message             bytea            NOT NULL, -- the message that is being signed
  index               bigint           NOT NULL, -- this is basically a nonce, but it can be reused if the sub_index gets incrementd
  sub_index           int              NOT NULL DEFAULT 0, -- (index, sub_index) form a nonce and should be unique
  context             bytea            NOT NULL, -- protocol buffers encoded metadata. See: https://github.com/actuallyfair/verifier/blob/master/protobuf/message-context.proto
  vx_signature        bytea            NOT NULL  DEFAULT bls_signature_set_by_vx() -- the result of vx signing "message" with the corresponding "commitments.vx_pubkey"
);
CREATE INDEX messages_commitment_idx ON messages(commitment, id);
CREATE INDEX messages_commitment_index_idx ON messages(commitment, index);

Only the writer user account will be allowed to insert into this table. It is an error to use your own id or vx_signature. Let us do that for you. You would typically insert with something like: INSERT INTO messages(commitment, message, index, context) VALUES($1, $2, $3, $4) RETURNING id, vx_signature to insert and retrieve what you need in one query

reveals

After the game server wants to reveal what it committed to


CREATE TABLE reveals(
  id             UUID             PRIMARY KEY DEFAULT uuid_generate_v7(), -- as a uuidv7 this encodes the time it was created
  commitment     bytea            NOT NULL, -- should reference commitments (but not enforced)
  reveal         bytea            NOT NULL, -- what is being revealed
  context        bytea            NOT NULL, -- protocol buffer metadata. See: https://github.com/actuallyfair/verifier/blob/master/protobuf/reveal-context.proto
  vx_private_key bytea            NOT NULL DEFAULT bls_private_key_set_by_vx()-- the private key vx used to sign messages
);
CREATE INDEX reveals_commitment_idx ON reveals(commitment, id);

Only the writer user account will be allowed to insert into this table. It is an error to use your own id or vx_private_key. Let us do that for you. You would typically insert with something like: INSERT INTO reveals(commitment, reveal, context) VALUES($1, $2, $3) RETURNING id, vx_private_key to insert and retrieve what you need in one query

Premade Views

It can be a bit of a pain to query binary data, so here's some handy pre-made views to help explore the data. This is just for debugging, don't rely on it. It may change or be removed at any time.

commitments_view


        CREATE VIEW commitments_view AS (
          SELECT
             encode(commitment, 'hex') AS commitment_hex,
             encode(vx_pubkey, 'hex') AS vx_pubkey_hex,
             uuid_v7_to_timestamptz(id) as created,
            *
           FROM commitments
       );

messages_view


        CREATE VIEW messages_view AS (
          SELECT
            encode(commitment, 'hex') as commitment_hex,
            encode(message, 'hex') as message_hex,
            encode(vx_signature, 'hex') as vx_signature_hex,
            uuid_v7_to_timestamptz(id) as created,
            *
          FROM messages
        );

reveals_view


        CREATE VIEW reveals_view AS (
          SELECT
             encode(commitment, 'hex') AS commitment_hex,
             encode(reveal, 'hex') AS reveal_hex,
             uuid_v7_to_timestamptz(id) as created,
            *
           FROM reveals
       );

Writer API

This can only be accessed by the "writer" user account. The reader will get permission denied attempting this.Note: This is now obselete. Simply insert into the tables.

make_commitment

This function appends a new row to the `commitments` table and returns the resultant row (with the vx_pubkey you will need)


CREATE FUNCTION make_commitment(_commitment BYTEA, _context BYTEA) RETURNS commitments

make_message

This function appends a new row to the `messages` table and returns the resultant row (with the vx_signature you will need)


CREATE FUNCTION make_message(_commitment BYTEA, _message BYTEA, _index bigint, _context bytea) RETURNS messages

make_reveal

This function appends a new row to the `reveals` table and returns the reveal'd row


 CREATE FUNCTION make_reveal(_commitment BYTEA, _reveal BYTEA, _context BYTEA) RETURNS reveals

ActuallyFair.com