Skip to main content
Version: Next

Tickets

Tezos tickets are authenticated quantities issued by contracts. A ticket of type ticket has three elements:

  • Its ticketer, which is the contract that issued the ticket

  • Its contents, also knowns as the wrapped value or payload, which can be any data type

  • Its amount of type nat, which is an arbitrary number that represents a quantity or value for the ticket

A ticket's ticketer and contents cannot be changed.

Tickets themselves cannot be duplicated, but you can split one ticket into multiple tickets by creating duplicate tickets each with a portion of the original ticket's amount. The new tickets have the same ticketer and contents, and the sum of their amounts is always the amount of the original ticket. Similarly, you can join tickets with matching ticketers and contents into a single ticket with the sum of the joined tickets' amounts.

Creating tickets

To create a ticket, pass the contents and the amount to Tezos.create_ticket function. The function returns an option that contains the ticket or None if the amount of the ticket is zero. The contract's address automatically becomes the ticketer value.

let Tezos.create_ticket: 'value => nat => option<ticket<'value>>

const my_ticket1 = Option.unopt(Tezos.create_ticket(1, 10n));
const my_ticket2 = Option.unopt(Tezos.create_ticket("one", 10n));

Reading tickets

You cannot read the contents of a ticket directly; you must use the Tezos.read_ticket function to access it. This function destroys the ticket and returns the ticketer, contents, amount, and a copy of the original ticket.

Note that reading a ticket with the Tezos.read_ticket function consumes it, destroying the original ticket. To preserve the ticket, you must use the copy that the function returns, or else the ticket is destroyed.

let Tezos.read_ticket: ticket<'value> => <<address, <'value , nat>> , ticket<'value>>

To read the content of a ticket, you need to use tuple destructuring:

const v2 = do {
let [[_addr, [payload, _amt]], _ticket] = Tezos.read_ticket (my_ticket2);
return payload;
}

Splitting tickets

Splitting a ticket creates two tickets that have the same ticketer and contents as the original and have amounts that add up to the amount of the original To split a ticket, pass the ticket and two nats to the Tezos.split_ticket function. It returns an option that is None if the sum of the two nats does not equal the amount of the original ticket. If the sum is equal, it returns Some with two tickets with the two nats as their amounts.

You can split tickets to divide a ticket to send to multiple sources or to consume only part of a ticket's amount.

let Tezos.split_ticket: ticket<'value> => <nat , nat> => option <<ticket<'value>, ticket<'value>>>

const [ta, tb] =
match(Tezos.split_ticket(my_ticket1, [6n, 4n])) {
when(None()): failwith("amt_a + amt_v != amt");
when(Some(split_tickets)): split_tickets
};

Joining tickets

You can join tickets that have identical ticketers and contents. The Tezos.join_tickets function joins tickets and returns an option with Some with a single ticket that has an amount that equals the sum of the amounts of the original tickets. If the ticketer or contents don't match, it returns None.

let Tezos.join_tickets = <ticket<'value>, ticket<'value>> => option <ticket<'value>>

const ta = Option.unopt(Tezos.create_ticket(1, 10n));
const tb = Option.unopt(Tezos.create_ticket(1, 5n));
const tc = Tezos.join_tickets([ta, tb]);

Transferring tickets

You can send tickets to other contracts by passing them with the Tezos.transaction function, just like passing any other value to a contract.