Ticket Balance Transparency

• Ticket Balance Transparency
  • Milestone
  • Scope and Design
  • 1. Ticket ownership updates to transaction receipts
    • Examples
    • Notes
    • Alternative solution
  • 2. RPC for retrieving ticket ownership for originated contracts
  • 3. RPC for the ticket balance of a ticket-token and account

Milestone

https://gitlab.com/tezos/tezos/-/milestones/118

Scope and Design

The goal of this project is to provide more transparency for indexers with regards to ticket ownership. More specifically, we propose to:

1. Add ticket ownership updates to transaction receipts
2. Provide an RPC for retrieving ticket ownership for originated contracts
3. Provide an RPC for retrieving the ticket balance of a specific ticket-token and account/rollup address

(1) makes it easier for indexers to scan blocks and traverse the transaction receipts in order to update their ticket balance tables. (2) can be used on originated contracts to retrieve the current ticket balance for an originated contract. (3) can be used for checking balances for a specific ticket type and contracts, and also works for implicit accounts and rollup addresses.

Once we have (1) and (2) it would be possible for indexers to reconstruct a "global ticket table" that keeps track of all ticket ownership (Note: let us know if this is not the case). This can be done by:

1. Calling the API from (2) to retrieve the current ticket ownership of all contracts.
   • This is only needs to be done once to bootstrap the global ticket table.
   • We only need the balance for contracts (and not implicit accounts) since implicit accounts cannot own tickets at this point (until milestone/92 is implemented).
2. Scanning the ticket balance updates in the receipts (from (1)) of all transactions to update the global ticket table.

(3) is meant to only be used as a double-check/validate ticket ownership.

1. Ticket ownership updates to transaction receipts

The idea is to make changes to ticket ownership part of the transaction (and internal origination) receipts, similar to balance updates. Ticket updates consist of a list of ticket-tokens and account updates.

A ticket-token is the combination of a ticketer (the creator of the ticket) and ticket content (a value of some comparable Michelson type).

For each ticket-token, we provide a list of account and balance update pairs, which we call ticket balance updates, as in:

Updated tickets:
    Ticketer: KT1WuPpnvefGFqKMDHWHEXz7FpnTc5JfYCB7
    Content type: string
    Content: "blue"
    Account updates:
        KT1LPnsqkZnddGUWZWFE5GtGBFtq6bT6EB7Q ... +3

Ticket balance updates represent increase/decrease of tickets in the storage. They are included in receipts whenever:

• A new ticket is minted and added to the contract's storage.
• A new ticket is sent from another account and stored in the contract's storage.
• An existing ticket is deleted from a contract’s storage.

Examples

Example 1: Contract mints a ticket and stores it

Suppose that:

• tz_a calls KT_A.
• KT_A mints a ticket and stores it in it's storage.

tz_a -> KT_A
        (mints one ticket and stores it to storage)

A single ticket should be added to KT_A's storage, which is reflected in the receipt as:

Manager signed operations:
    ...
    Transaction:
      From: tz_a
      To: KT_A
      Parameter: 0
      ...

    Ticket updates: 
        Ticketer: KT_A
        Content: "blue"
        Content type: string
        Account updates:
            KT_A ... +1

Example 2: Contract reads one ticket from storage and sends it to another contract

Suppose:

• tz_a calls KT_A.
• KT_A reads one ticket from storage and sends it to KT_B.
• KT_B stores the received ticket.

            one ticket -> KT_B
           /              (stores ticket)
tz_a -> KT_A 
        (read one ticket) 

One ticket is removed from KT_A's storage by the initial transaction and one ticket is added to KT_B's storage by the internal transaction:

Manager signed operations:
    ...
    Transaction:
      From: tz_a
      To: KT_A
      ...
    Ticket updates: 
        Ticketer: KT_T
        Content: "blue"
        Content type: string
        Account updates:
            KT_A ... -1
    Internal Transaction:
        ...
        From: KT_A
        To: KT_B
        Parameter: (Pair T (Pair "blue" 1))
        ...
        Ticket updates: 
            Ticketer: KT_T
            Content: "blue"
            Content type: string
            Account updates:
               KT_B ... +1    

Example 3: Contract mints a ticket and sends it to another contract

Suppose:

• tz_a calls KT_A.
• KT_A mints a ticket and sends it to KT_B.
• KT_B stores the ticket it received.

            one ticket -> KT_B
           /              (stores ticket)
tz_a -> KT_A 
        (mints one ticket) 

This transaction will not change the tickets in storage of KT_A and will increase the ticket in storage KT_B by one:

Manager signed operations:
    ...
    Transaction:
      From: tz_a
      To: KT_A
      ...
    Internal Transaction:
        ...
        From: KT_A
        To: KT_B
        Parameter: (Pair T (Pair "blue" 1))
        ...
        Ticket updates: 
            Ticketer: KT_T
            Content: "blue"
            Content type: string
            Account updates:
               KT_B ... +1    

Example 4: Contract receives ticket from implicit account and stores it

Suppose:

• tz_a calls KT_A with one ticket in the parameter
  • This will be possible once milestone/92 is done.
• KT_A stores the received ticket.

tz_a -(one ticket)-> KT_A
                    (stores ticket in storage)

A ticket is removed from tz_a and added to the storage of KT_A via subsequent internal operation:

Manager signed operations:
    ...
    Transfer Ticket:
      From: tz_a
      ...

      Ticket updates: 
          Ticketer: KT_T
          Content: "blue"
          Content type: string
          Account updates:
              tz_a ... -1
    Internal Transaction:
        ...
        From: tz_a
        To: KT_A
        Parameter: (Pair T (Pair "blue" 1))
        ...
        Ticket updates: 
            Ticketer: KT_T
            Content: "blue"
            Content type: string
            Account updates:
               KT_A ... +1

Example 5: A more complex case

Suppose:

• tz_a sends one ticket to KT_A
• KT_A reads one additional ticket from storage and sends one ticket each to KT_B and KT_C.
• KT_B stores the ticket.
• KT_C does not store the ticket (i.e. throws it away)

                       transfer blue ticket -> KT_B 
                       /                     (stores ticket in storage)
tz_a -(one ticket)-> KT_A (read one ticket)
                       \
                       transfer blue ticket -> KT_C
                                              (does not store ticket in storage)

The resulting receipt will look like:

Manager signed operations:
    ...
    Transaction:
      From: tz_a
      To: KT_A
      Parameter: 0
      ...
      Ticket updates: 
        Ticketer: KT_T
        Content: "blue"
        Content type: string
        Account updates:
           tz_a ... -1
           KT_A ... -1
      Internal operations:
        Internal Transaction:
          ...
          From: KT_A
          To: KT_B
          Parameter: (Pair KT_T (Pair "blue" 1))
          Ticket updates:
              KT_B ... +1
        Internal Transaction:
          ...
          From: KT_A
          To: KT_C
          Parameter: (Pair KT_T (Pair "blue" 1))
          ...
          ...(no ticket updates)...

Note that you can get the net-ticket balance update of the a ticket for any transaction by adding up the corresponding Ticket updates in the receipts:

Account updates:
   tz_a ... -1
   KT_A ... -1
   KT_B ... +1

For reference, here is what the full receipt would look like in JSON:

[
  {
    "kind": "transaction",
    "source": tz_a,
    "destination": KT_A,
    ....
    "metadata": {
      "operation_result": {
        "status": "applied",
        "storage": [],
        "balance_updates": [...],
        "ticket_updates": [
          {
            "ticketer": T
            "content": "blue",
            "content_type": "string",
            "account_updates": [
              {
                "contract": tz_a
                "change": "-1"
              },
              {
                "contract": KT_A
                "change": "-1"
              }
            ]
          }
        ],
        ...
      },
      "internal_operation_results": [
        {
          "kind": "transaction",
          "source": KT_A,
          "destination": KT_B,
          "parameters": {
            "entrypoint": "default",
            "value": {
              "prim": "Pair",
              "args": [
                {
                  "bytes": "01014fb3291ad73087c75cba9ed0885141c6412f7400"
                },
                {
                  "prim": "Pair",
                  "args": [
                    {
                      "string": "blue"
                    },
                    {
                      "int": "1"
                    }
                  ]
                }
              ]
            }
          },
          "result": {
            "status": "applied",
            "balance_updates": [...],
             ...
            "ticket_updates": [{
              "ticketer": T
              "content": "blue",
              "content_type": "string",
              "account_updates": [{
                  "contract": KT_B
                  "change": "+1"
                }]
            }]
          }
        },
        {
          "kind": "transaction",
          "source": A,
          "destination": C,
          "parameters": {
            "entrypoint": "default",
            "value": {
              "prim": "Pair",
              "args": [
                {
                  "bytes": "01014fb3291ad73087c75cba9ed0885141c6412f7400"
                },
                {
                  "prim": "Pair",
                  "args": [
                    {
                      "string": "blue"
                    },
                    {
                      "int": "1"
                    }
                  ]
                }
              ]
            }
          }
        }
      ]
    }
  }
]

Notes

• No receipt is provided for the following scenarios:

  • A ticket is minted but not saved.
  • Two tickets existing in a contract’s storage are joined together and saved in the storage.
  • One ticket existing in a contract’s storage is split and both tickets are saved.

• We will support receipts for all combinations of transactions between:

  • Implicit accounts
  • Originated accounts
  • Rollups (SCORU and TORU)

Alternative solution

An alternative way of displaying the ticket updates is to have a single net-balance update at the top level of the receipt. For the "Example 5" it would look like:

Manager signed operations:
    ...

    Ticket updates:
        Ticketer: KT_T
        Content: "blue"
        Content type: string
        Account updates:
           tz_a ... -1
           KT_A ... -1
           KT_B ... +1
    Transaction:
      From: tz_a
      To: KT_A
      Parameter: 0
      ...
      Internal operations:
        Internal Transaction:
          ...
          From: KT_A
          To: KT_B
          Parameter: (Pair KT_T (Pair "blue" 1))
          ...
        Internal Transaction:
          ...
          From: KT_A
          To: KT_C
          Parameter: (Pair KT_T (Pair "blue" 1))
          ...

2. RPC for retrieving ticket ownership for originated contracts

All tickets owned by originated contracts exist in the respective contract’s storage. We can provide an RPC that scans the contract storage for tickets and returns a list of ticket balances.

The API will look like this:

tezos-client rpc get /chains/main/blocks/genesis/context/contracts/<contract_id>/ticket_balance

For example:

tezos-client rpc get /chains/main/blocks/genesis/context/contracts/KT1WuPpnvefGFqKMDHWHEXz7FpnTc5JfYCB7/ticket_balance

Would return a breakdown of the tickets owned by KT1WuPpnvefGFqKMDHWHEXz7FpnTc5JfYCB7 like this:

{
  "ticket_balance": [
    {
      "ticketer": "KT1WuPpnvefGFqKMDHWHEXz7FpnTc5JfYCB7",
      "content": "blue",
      "content_type": "string",
      "balance": 7
    },
    {
      "ticketer": "KT1WvzYHCNBvDSdwafTHv7nJ1dWmZ8GCYuuC",
      "content": "red",
      "content_type": "string",
      "balance": 2
    }
  ]
}

3. RPC for the ticket balance of a ticket-token and account

Implicit accounts and rollup addresses may hold tickets but the tickets are not contained in any storage why it is not possible to retrieve them by using the RPC above.

Ticket ownership is tracked by the protocol as a table that maps a triple of owner x ticketer x content to balance. However, the keys are hashed so it’s also not possible to iterate over the table and collect all ticket for a given contract. Instead what we can do is to provide an RPC that returns the balance of specific combination of owner x ticketer x content, by looking up the balance from the ticket balance table in the context.

This RPC would need to receive four things:

1. The address of the contract or rollup that we target
2. The ticketer of the ticket-token we are interested in
3. The content of the ticket-token we are interested in
4. The type of the content we are interested in (that is beacuse

The API will be aPOST endpoint which can be called like:

tezos-client rpc post /chains/main/blocks/genesis/context/contracts/tz1KqTpEZ7Yob7QbPE4Hy4Wo8fHG8LhKxZSx/ticket_balance_with/

With a request body that looks like:

{
  "ticketer": "KT1WuPpnvefGFqKMDHWHEXz7FpnTc5JfYCB7",
  "content_type": "string",
  "content": "blue",
}

And would return a single number representing the amount of ticket-tokens with the given ticketer and content held by the contract:

3