# Zoe Data Types

Zoe introduces and uses several data types.

# Allocation

Allocations represent the Amounts to be paid out to each seat upon exiting a Proposal.

For example, if a seat expected to be paid 5 Quatloos and 3 Widgets after successfully exiting a Proposal, the Allocation would look like:

{
  Quatloos: 5n
  Widgets: 3n
}

# Handle

Handles are Far objects without any methods whose only useful property are their unique identities. They're often created in order to designate some other object, where the Handles can be passed around as reliable designators without giving access to the designated objects.

# Instance

An Instance is a handle that represents an instance of a contract. You can get information about the contract instance via these methods:

# Invitation

An Invitation is a non-fungible asset created by the InvitationIssuer. An Invitation Payment is a Payment holding an Invitation.

# InvitationIssuer

The InvitationIssuer is an Issuer that plays a special role throughout Zoe. Zoe has a single InvitationIssuer for its entire lifetime. All Invitations come from the Mint associated with the Zoe instance's InvitationIssuer.

The issuer is publicly available (via E(Zoe).getInvitationIssuer()), so the ability to validate invitations is widely available.

InvitationIssuer has all the methods of regular Issuers, but the two methods that are most often used are anIssuer.claim() and anIssuer.getAmountOf().

A successful call of anInvitationIssuer.claim() means you are assured the Invitation passed into the method is recognized as valid by the InvitationIssuer. You are also assured the Invitation is exclusively yours and no one else has access to it.

# Keyword

A Keyword is a unique identifier string within a contract for tying together the issuers in its proposals, payments, and payouts. It must be an ASCII-only identifier (opens new window) and start with an upper case letter in order to avoid collisions with JavaScript properties such as toString when used as a property name in a record. (For more detail, see Why do Zoe keywords have to start with a capital letter? #8241 (opens new window).) NaN and Infinity are also not allowed as keywords.

# KeywordRecord

A KeywordRecord is a CopyRecord in which every property name is a Keyword, such as harden({ Asset: moolaIssuer, Bid: simoleanIssuer }). Subtypes further constrain property values (for example, an AmountKeywordRecord is a KeywordRecord in which every value is an Amount and a PaymentPKeywordRecord is a KeywordRecord in which every value is either a Payment or a Promise for a Payment).

Users submit their payments as KeywordRecords:

const aFistfulOfQuatloos = AmountMath.make(quatloosBrand, 1000n);
const paymentKeywordRecord = {
  Asset: quatloosPurse.withdraw(aFistfulOfQuatloos),
};

# MutableQuote

A MutableQuote represents a statement from a PriceAuthority as to the current price level at a particular time. The significant content (prices and time) is packaged in the Amount, and repeated in the Payment for veracity.

MutableQuotes should be used when you expect to make multiple calls, replacing the trigger value. If you just need a single quote, and won't change the trigger level, you should use PriceQuotes.

A MutableQuote is an Amount-Payment pair, where the Amount is also the current balance of the Payment.

# ParsableNumber

A ParsableNumber is defined as a bigint, number, or string.

# PriceQuote

A PriceQuote represents a statement from a PriceAuthority as to the current price level at a particular time. The significant content (prices and time) is packaged in the Amount and repeated in the Payment for veracity. A PriceQuote is an Amount-Payment pair, where the Amount is also the current balance of the Payment.

const { quoteAmount, quotePayment } = priceQuote;

PriceQuotes are returned in two forms:

PriceDescription
- Always includes amountIn, amountOut, the quote's Timestamp, and the TimerService the Timestamp is relative to.
PriceDescription wrapped as a QuoteAuthority issued payment.
- This lets quotes be shared in a format letting others verify the time and values.

# Ratio

Ratios are pass-by-value records that consist of a numerator and a denominator. Both of these consist of a AmountValue and a Brand, just like Amounts. A Ratio cannot have a denominator value of 0.

The most common kind of Ratio is applied to an Amount of a particular Brand and produces results of the same Brand.

Ratios can also have two different Brands, essentially typing them such as miles per hour or US dollars for Swiss francs (i.e., an exchange rate ratio).

# TransferPart

TransferParts are the individual elements of the transfer array passed into the atomicRearrange() function. Each TransferPart represents one or two Allocation changes among existing ZCFSeats. Each TransferPart consists of 4 elements, each of which can be elided in some cases:

fromSeat?: ZCFSeat - The seat from which amounts are being taken.
toSeat?: ZCFSeat - The seat to which amounts are being given.
fromAmounts?: AmountKeywordRecord - The amounts which will be taken from the fromSeat.
toAmounts?: AmountKeywordRecord - The amounts which will be given to the toSeat.

If a fromSeat is specified, then a fromAmounts is required. When you specify a toSeat without specifying a toAmounts, it means that the fromAmount will be taken from fromSeat and given to toSeat.

TransferParts that represent one side of a transfer can be created using the helper functions fromOnly() or toOnly(). Of course, as with any JavaScript datatype, you can also manually create TransferParts. If you manually create a TransferPart and don't include the fromSeat, toSeat, and/or fromAmounts fields, you'll need to set the missing fields to undefined. (Note that if you don't include the toAmounts field, there's no need to set it to undefined; you can simply omit it.)

← Ratio Math Functions