04-backend-protocol.md

COOP Backend protocol

This document contains information on the back-end operations needed to serve the Frontend protocol.

Publishing a Fact Statement

The successful result of this operation is a Fact Statement Publishing transaction.

The COOP Publisher gRPC service starts off by looking up the requests Fact Statement IDs in the COOP FactStatementStore gRPC service. This service provides the PlutusData encoding of the requested Fact Statements, and this representation format is what gets included in the [Fact Statement UTxOs](Fact Statement UTxOs) directly, which makes it possible for Consumer dApps to reference and intepret the information held within. We provide a JSON Fact Statement Store implementation of the COOP FactStatementStore gRPC service which can serve as a convenient low-scale backend that maintains JSON encoded Fact Statements. This service uses a Plutus Json canonical mapping library between the JSON and PlutusData data representation formats.

sequenceDiagram
  title Successfully service a Fact Statement Publishing request
  actor publisher as COOP Publisher gRPC
  actor fsStore as COOP FactStatementStore gRPC
  actor pab as COOP TxBuilder gRPC
  actor cardano as Cardano
  actor authenticator as Authenticator wallet

  note right of publisher: Servicing createMintFsTx request with (fs_id, submitter_pkh)
  publisher ->>+ fsStore: FactStatementStore.getFactStatement(fs_id)
  note right of fsStore: Looks for Fact Statements managed by an Oracle
  fsStore -->>- publisher: fact_statement_pd

  publisher ->>+ pab: TxBuilder.createMintFsTx(fact_statement_pd, fs_id, submitter_pkh)
    pab ->>+ cardano: Get information about the Submitter, existing Fact Statements, Certificates and Authentication tokens
    cardano -->>- pab: (Submitter Collateral and Fee UTxOs, Authenticator and Certificate UTxOs)
    pab ->>+ authenticator: sign(signed_mint_fs_tx)
    authenticator -->>- pab: signed_mint_fs_tx
  pab -->>- publisher: signed_mint_fs_tx

  
  note right of publisher: Replying with signed_mint_fs_tx

Loading

The COOP TxBuilder gRPC service is the only component that talks to the Cardano network. It does so exclusively to discover information necessary to build a transaction:

• Fact Statement UTxOs for asserting which of the Fact Statements have already been published,
• Collateral UTxOs at the Submitter wallet,
• Fee UTxOs at the Submitter wallet,
• Authentication UTxOs at the Authenticator wallet,
• Certificate UTxOs for asserting the validity of the provided Authentication tokens.

Authenticator wallets provide their own signatures to the Fact Statement Publishing transaction to authenticate the spending of the Authentication tokens.

Garbage collecting obsolete Fact Statements

The successful result of this operation is a Fact Statement Garbage Collecting transaction.

sequenceDiagram
  title Successfully service a Fact Statement Garbage Collection request
  actor publisher as COOP Publisher gRPC
  actor pab as TxBuilder gRPC
  actor cardano as Cardano
  note right of publisher: Servicing createGcFsTx request with (fs_id, submitter_pkh)
  
  publisher ->>+ pab: TxBuilder.createGcFsTx(fs_id, submitter_pkh)
  pab ->>+ cardano: Get information about the Submitter and Fact Statements
  cardano -->>- pab: (Submitter Collateral and Fact Statement UTxOs)
  pab -->>- publisher: gc_fs_tx

  
  note right of publisher: Replying with gc_fs_tx

Loading

The COOP TxBuilder gRPC service is the only component that talks to the Cardano network. It does so exclusively to discover information necessary to build a transaction:

• Fact Statement UTxOs for asserting which of the Fact Statements are indeed obsolete and can be garbage collected,
• Collateral UTxOs at the Submitter wallet.