---
tags: protocol
---

# Ticket Balance Transparency

[toc]

## 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](https://gitlab.com/tezos/tezos/-/milestones/92#tab-issues) 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](https://gitlab.com/tezos/tezos/-/milestones/92#tab-issues) 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 a`POST` 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