# Glossary

This page lists words, expressions, or concepts used by the Agoric technology stack.

# Agoric CLI

A command line interface for installing dependencies and initializing, deploying, and starting Agoric projects. See the Agoric CLI Guide.

# AllegedName

Human-readable name of a type of assets. The alleged name should not be trusted as an accurate depiction, since it is provided by the maker of the mint and could be deceptive, but is useful for debugging and double-checking.

The AllegedName must be a string.

# Allocation

Allocations represent the amounts to be paid out to each seat on exit from a contract instance. Possible exit causes are exercising an exit condition, the contract's explicit choice, or a crash or freeze. There are several methods for getting the amounts currently allocated.

In more detail, Zoe's guarantee is each seat will either get what it asked for in its offer, or the return of what was escrowed. The contract can reallocate fairly arbitrarily to achieve that. As contract code is visible to its clients, users can see what the contract intends to do.

Zoe enforces those terms by keeping track of a current allocation for each seat. The initial allocation is the deposit. The contract can modify a seat's allocation as long as it never violates offer safety or rights conservation. i.e. it can't assign assets that weren't already in some allocation and it can't assign them to more than one seat. Also, goods can't disappear from the total allocation.

# AmountMath

The AmountMath library executes the logic of how amounts are changed when digital assets are merged, separated, or otherwise manipulated. For example, a deposit of 3 Quatloos into a purse that already has 7 Quatloos updates its balance to 10 Quatloos. But a deposit of a non-fungible theater ticket into a purse that already holds five tickets is performed by set union rather than by arithmetic.

AmountMath has a single set of polymorphic methods that deal with different asset kinds:

  • AssetKind.NAT: Used with fungible assets. Each amount value is a natural number (non-negative integer). This is the default AssetKind.
  • AssetKind.SET: Used with non-fungible assets; deprecated in favor of AssetKind.COPY_SET but still in wide use. Each amount value is an array of Key values subject to the same constraints as those of AssetKind.COPY_SET.
  • AssetKind.COPY_SET: Used with non-fungible assets. Each amount value is a set of Key values (strings, numbers, objects, etc.). Values cannot include promises (they aren't keys), and should not include privileged objects such as payments and purses.
  • AssetKind.COPY_BAG: Used with semi-fungible assets. Each amount value is a multiset (opens new window) of Key values subject to the same constraints as those of AssetKind.COPY_SET but allowed to be present more than once.

For more information, see the ERTP Guide's AmountMath section and the ERTP API's AmountMath section.

# Amount

Amounts are the canonical descriptions of tradable goods. They are manipulated by issuers and mints, and represent the goods and currency carried by purses and payments. They represent things like currency, stock, and the abstract right to participate in a particular exchange.

An amount is comprised of a brand with a value. For example, "4 Quatloos" is an amount with a value of "4" and a brand of the imaginary currency "Quatloos".

Important: Amounts are descriptions of digital assets, not the actual assets. They have no economic scarcity or intrinsic value. For example, to make you an offer to buy a magic sword in a game, a party sends you an amount describing the asset of 5 Quatloos they're willing to trade for your sword. They don't send you the actual 5 Quatloos; that only happens when there is agreement on the trade terms and they send you a payment, not an amount, of 5 Quatloos, the actual asset. Creating a new amount does not create new assets.

For more information, see the ERTP Guide's Amounts section and the ERTP API's AmountMath section.

# AssetHolder

Purses and payments are AssetHolders. These are objects that contain digital assets in the quantity specified by an amount.

# BigInt

In ERTP AmountMath, we use the JavaScript BigInt (opens new window) type for the value of fungible amounts in order to avoid overflow risks from using the usual JavaScript Number type.

Timer Services also use BigInt for absolute and relative times.

BigInts are written with an n suffix: 0n, 1n, 2n, ... or created with BigInt("123") or BigInt(123).

# Board (Agoric Board)

The Board is a shared, on-chain location where users can post a value and make it accessible to others. When a user posts a value, they receive a unique ID for the value. Others can get the value just by knowing the ID. You can make an ID known by any communication method—a DM or email or other private message, a phone call/voicemail, an email blast to a mailing list, publishing it on a website, etc.

Note: Publishing an object to the board makes it publicly accessible. If this is not appropriate for an object, do not use the board to communicate access to it.

# Brand

Identifies the type of issuer, such as "Quatloos", "Moola", etc. Brands are one of the two elements that make up an amount. For more information, see the ERTP Guide's Brand section and the ERTP API's Brand section.

# Bundle

Before a contract can be installed on Zoe, its source code must be bundled. This is done by:

import bundleSource from '@endo/bundle-source';
const atomicSwapBundle = await bundleSource(
    require.resolve('@agoric/zoe/src/contracts/atomicSwap'),
);

The installation operation returns an installation, which is an object with a single getBundle() method for accessing an installed contract's source code. In most cases, the bundle contains a base64-encoded zip file that you can extract for review.

const { endoZipBase64 } = await E(installation).getBundle();
echo "$endoZipBase64" | base64 -d > bundle.zip
unzip bundle.zip

# Burn

Destroy digital assets. Burning a payment additionally makes it unavailable for later use. See issuer.burn(payment, optAmount).

# Comparable

Comparable is a deprecated synonym of Key.

# Contract Installation and Contract Instance

In Agoric documentation, contract usually refers to a contract's source code that defines how the contract works. A contract's source code is installed on Zoe. A contract is instantiated to create contract instances, which are the active execution of a contract's code running on Zoe.

For example, a realtor has a standard house selling agreement. The contract is the code defining how that agreement works. When the realtor has a new house to sell, they instantiate a new instance of their standard contract for that specific property. If they have ten houses for sale, they have ten different contract instances.

# Creator Invitation

An invitation optionally returned by startInstance() that the contract instance creator can use. It is usually used in contracts where the creator immediately sells something (auctions, swaps, etc.).

# Deposit Facet

A facet of a purse. Anyone with a reference to its deposit facet object can add appropriately branded assets to the purse, but cannot withdraw assets from the purse or find out its balance.

# dIBC

Dynamic version of the Inter-Blockchain Communication protocol. See here (opens new window) for more details.

# E()

(Also referred to as eventual send) E() is a local "bridge" function that asynchronously invokes methods on local or remote objects, for example those in another vat, machine, or blockchain. It takes as its argument either a local object or a presence for a remote object or a promise for a local or remote object, and sends messages to the object using normal message-sending syntax. The local proxy forwards all messages to the remote object to deal with. All E() calls return a promise for the eventual result. For more detail, see the E() section in the Distributed JavaScript page.

# Endo

What Node.js does for JavaScript, Endo does for Hardened JavaScript. Endo guest programs run in Hardened JavaScript and communicate with their host and other guests through hardened interfaces and object-to-object message-passing. For example, an Agoric smart contract is an Endo program that runs in an Endo host. Endo is responsible for linking and isolating Node.js packages and modules in Hardened JavaScript compartments and providing limited access to host resources. The scope of vision for the Endo project includes the creation of other Endo host programs like an Endo browser, an Endo browser extension, and endo command line tools, as well allowing programs to limit the powers they delegate to dependencies, to limit exposure to supply-chain attacks. For more information, see the Endo and Hardened JavaScript Programming Guide (opens new window)

# ERTP

Electronic Rights Transfer Protocol is a uniform way of transferring tokens and other digital assets, both fungible and non-fungible, in JavaScript. All kinds of digital assets can easily be created and they can be all be transferred in exactly the same ways, with exactly the same security properties.

It uses object capabilities to enforce access control. Instead of having to prove ownership of a corresponding private key, if your program has a reference to an object, it can call methods on that object. If it doesn't have a reference, it can't. For more on object capabilities, see this post (opens new window).

Key ERTP concepts include Issuers, Mints, Purses, Payments, Brands, and Amounts. Also see the ERTP Introduction, ERTP Guide, and ERTP API.

# Escrow

To give assets for a possible transaction to an impartial third party, who keeps them until specified conditions are satisfied. For example, Alice wants to sell Bob a ticket for $100. Alice escrows the ticket, and Bob escrows the $100, with Zoe. Zoe does not give Alice the $100 or Bob the ticket until it has both items. Since neither Alice nor Bob ever holds both items at once, they don't have to trust each other to do the transaction. Zoe automatically escrows payments for transaction offers.

# Eventual Send

See E() above.

# Exit Rule

Part of an offer specifying how the offer can be cancelled/exited. There are three values:

  • onDemand: null: (Default) The offering party can cancel on demand.
  • waived: null: The offering party can't cancel and relies entirely on the smart contract to promptly finish their offer.
  • afterDeadline: {…}: The offer is automatically cancelled after a deadline, as determined by its timer and deadline properties. See Proposals and payments.

# Facet

A facet is an object that exposes an API or particular view of some larger entity, which may be an object itself. You can make any number of facets of an entity. In JavaScript, you often make a facet by selecting methods from the entity, either directly or by destructuring:

const facet = {
  myMethod: oldObject.method,
}

Two Agoric uses are:

  • Deposit Facet: A facet of a purse. Anyone with a reference to its deposit facet object can add appropriately branded assets to the purse, but cannot withdraw assets from the purse or find out its balance.
  • Public Facet: A set of methods and properties for an object that a developer chooses to be publicly visible and usable.

# Fungible

A fungible asset is one where all exemplars of the asset are interchangeable. For example, if you have 100 one dollar bills and need to pay someone five dollars, it does not matter which five one dollar bills you use. Also see non-fungible.

# Handle

A handle is a unique identifier implemented as a JavaScript object. Only its identity is meaningful, so handles do not have properties. Unlike number or string identifiers, handles are unforgeable. This means the only way to know a handle identity is being given an object reference, and no identity can be guessed and no fake identity will succeed.

# Harden

A hardened object’s properties cannot be changed, so the only way to interact with a hardened object is through its methods. harden() is similar to Object.freeze() but more powerful. For more about harden(), see its section in the JavaScript Distributed Programming Guide (opens new window)

# Hardened JavaScript (SES)

Hardened JavaScript is a standards-track extension to the JavaScript standard. Hardening JavaScript turns the sandbox into firm ground, where you can code run you don't completely trust, without being vulnerable to their bugs or bad intentions. See the Endo and Hardened JavaScript Programming Guide (opens new window) for more details.

# IBC

The Inter-Blockchain Communication protocol, used by blockchains to communicate with each other. A short article about IBC is available here (opens new window).

# Invitation

A payment whose amount represents (and is required for) participation in a contract instance. Contracts often return a creator invitation on their instantiation, in case the contract instantiator wants to immediately participate. Otherwise, the contract instance must create any additional invitations. Every offer to participate in a contract instance must include an invitation to that instance in the first argument to E(Zoe).offer(), and any wallet receiving one will validate it via the InvitationIssuer.

An invitation's amount includes the following properties:

  • The contract's installation in Zoe, including access to its source code.
  • The contract instance this invitation is for.
  • A handle used to refer to this invitation.
  • A description of this invitation's purpose.

# InvitationIssuer

Since invitations are payments, invitations must have a dedicated issuer, which is the InvitationIssuer.

Zoe has a single InvitationIssuer for its entire lifetime. By having a reference to Zoe, a user can get the InvitationIssuer. This lets them claim any invitation they receive from someone else by calling E(invitationIssuer).claim() with the untrusted invitation as the argument. During the claiming process, the invitationIssuer validates the invitation. A successful claim also means that invitation is exclusively yours.

Note: Depositing into an invitation-branded purse also validates an invitation. This is what the wallet does.

# Issuer

Issuers are a one-to-one relationship with both a mint and a brand, so each issuer works with one and only one asset type, such as only working with Quatloos or only working with Moola. This association cannot change to another type.

Issuers can create empty purses for their asset type, but cannot mint new amounts. Issuers can also transform payments of their asset type (splitting, combining, burning, and exclusively claiming payments). An issuer from a trusted source can determine if an untrusted payment of its asset type is valid.

For more information, see the ERTP Guide's Issuer section and the ERTP API's Issuer section.

# Key

A Key is a passable containing no promises or errors, and can thus be synchronously compared for structural equivalence with another piece of data. If either side of the comparison contains promises and/or errors, equality is indeterminable. If both are fulfilled down to presences and local state, then either they're the same all the way down, or they represent different objects.

Keys can be used as elements of CopySets and CopyBags and as keys of CopyMaps (see AmountMath). Values must be Keys.

# Keyword

A keyword is a property name string that is a valid identifier (opens new window), starts with an upper case letter, and contains no non-ASCII characters. A KeywordRecord is a CopyRecord in which every property name is a keyword.

# Mint

ERTP has a mint object, which creates digital assets. ZCF provides a different interface to an ERTP mint, called a ZCFMint. Assets and AssetHolders created using ZCFMints can be used in all the same ways as assets created by other ERTP Mints. They interact with Purses, Payments, Brands, and Issuers in the same ways.

  • ERTP mints create digital assets and are the only ERTP objects with the authority to do so. Access to an ERTP mint gives you the power to create more digital assets of its type at will. Mints can only create one type of asset and cannot change to create a different type.

    There is a one-to-one relationship between an issuer and its mint, and a mint is an administrative facet of its issuer. ERTP mints are also in a one-to-one relationship with that issuer's associated brand.

  • ZCFMints give contract code a simpler interface to interact with an ERTP mint from inside a contract. Because ZCFMints encapsulate an internal ERTP mint, they have the same one-to-one relationships with an issuer and its associated brand. A ZCFMint can mint assets and assign them to a seat without having to escrow payments, and burn seat-associated assets without corresponding payout.

ZCFMints and ERTP mints do not have the same methods. Do not try to use ERTP methods on a ZCFMint or vice versa. However, issuers and brands associated with either an ERTP mint or a ZCFMint are the same concepts and have the same methods.

For more information on ERTP mints, see the ERTP Guide's Mint section and the ERTP API's Mint section. For more information about ZCFMints, see the ZCF API zcf.makeZCFMint().

# Moola

An imaginary currency Agoric documentation uses in examples.

# Non-fungible

A non-fungible asset is one where each incidence of the asset has unique individual properties and is not interchangeable with another incidence. For example, if your asset is theater tickets, it matters to the buyer what the date and time of the show is, which row the seat is in, and where in the row the seat is (and likely other factors as well). You can't just give them any ticket in your supply, as they are not interchangeable (and may have different prices). See also fungible.

# Notifier

A notifier provides a stream of updates describing changes to the state of an offer or other object. For more information, see Notifiers and Subscriptions.

# Object Capabilities

Objects have state, behavior, and references. Let's say Object A has references to Objects B and C, while B and C do not have references to each other. Thus, A can communicate with B and C, and B and C cannot communicate with each other. There is an effective zero-cost firewall between B and C.

An object capability system constrains how references are obtained. You can't get one just by knowing the name of a global variable or a public class. You can only get a reference via:

  • Creation: Functions that create objects get a reference to them.
  • Construction: Constructors can endow their constructed objects with references, including inherited references.
  • Introduction:
    • A has references to B and C.
    • B and C do not have references to each other
    • A sends B a reference to C.
      • B now has a reference to C and can communicate with C.

If references can only be obtained by creation, construction, or introduction, you may have a safe system. If they can be obtained in any other way, your system is unsafe.

For more information, see Douglas Crockford on Object Capabilities (opens new window).

# Offer

Users interact with contract instances by making offers. In Zoe, an offer consists of a proposal (what the offer making party is willing to give up and what they want in exchange) and payments corresponding to the amount in the proposal they're willing to give. The payments are automatically escrowed by Zoe, and reallocated according to the contract code. An offer gets a payout of some combination of what the party originally contributed and what others have contributed. The specific payout is determined by the contract code.

See E(Zoe).offer(invitation, proposal, paymentKeywordRecord, offerArgs).

# Offer Safety

Zoe guarantees offer safety. When a user makes an offer and its payments are escrowed with Zoe, Zoe guarantees that the user either gets what they said they wanted, or gets back what they originally offered and escrowed (a refund). One reason this is possible is if a proposal doesn't match what the contract expects to do, it can immediately cause the seat to exit, getting back the amount it offered.

# Passable

A passable is something that can be marshalled (see the Marshaling section in the JavaScript Distributed Programming Guide) and sent to and from remote objects.

# Payment

Payments hold assets created by mints, specifically assets intended for transfer from one party to another. All assets of a payment are of the same brand.

For more information, see the ERTP Guide's Payments section and the ERTP API's Payments section.

# Payout

The assets paid out to a user when an seat exits, either successfully or not. The payout is always what the seat's current allocation is.

If there was a previous reallocation, the payout is different than what the user escrowed. If there is no reallocation before the seat exits, the payout is the same as what they escrowed.

# Petname

Petnames are your personal names for objects. No one else can see or modify a petname without your permission. Think of them as similar to a phone's contacts list. The actual phone number is what a phone uses to call someone, but to more easily tell who a number is associated with, it's assigned a petname, such as Mom, Grandpa, Kate S., etc. In the Agoric platform, petnames are used in wallets.

# Presence

A local version of a remote object that serves as the remote object's proxy. If obj is a presence of a remote object, you can send messages to the remote object by using E() on obj. For more information, see the JavaScript Distributed Programming Guide.

# Proposal

Proposals are records with give, want, and exit properties. Offers must include a proposal, which states what asset you want, what asset you will give for it, and how/when the offer maker can cancel the offer (see Exit Rule for details on the last). For example:

const myProposal = harden({
  give: { Asset: AmountMath.make(quatloosBrand, 4)},
  want: { Price: AmountMath.make(moolaBrand, 15) },
  exit: { onDemand: null }
})

give and want use keywords defined by the contract. Each specifies via an amount a description of what they are willing to give or want to get.

# Purse

A purse holds amounts of assets issued by a particular mint that are all of the same brand, often for arbitrarily long periods of time. When transfer is desired, a purse can move part of its held balance to a payment.

For more information, see the ERTP Guide's Purses section and the ERTP API's Purses section.

# Quatloos

An imaginary currency Agoric documentation uses in examples. For its origins, see the Wikipedia entry for the Star Trek episode The Gamesters of Triskelion (opens new window).

# Reallocation

A transfer of amounts between seats within Zoe; i.e. a change in their allocations. When a seat exits, it gets its current allocation as a payout.

# Seat

Zoe uses a seat to represent an offer in progress, and has two seat facets representing two views of the same seat; a ZCFSeat and a UserSeat. The UserSeat is returned to the user who made an offer, and can check payout status or retrieve their results. The ZCFSeat is the argument passed to the offerHandler in the contract code. It is used within contracts and with zcf methods.

The two seat facets have slightly different methods but represent the same seat and offer in progress. The term comes from the expression "having a seat at the table" with regards to participating in a negotiation.

For more details, see the ZCFSeat documentation and the UserSeat documentation.

# Semi-fungible

A semi-fungible asset is one that has distinct forms which are not interchangeable with each other, but in which instances of a single form may interchangeable with other instances of the same form. As a variation on the non-fungible theater ticket example, tickets might specify only a section, where the holder may sit in any seat of that section. For each section, the number of theater tickets minted should not exceed the number of seats in that section.

# SES

Secure ECMAScript has been renamed to Hardened JavaScript.

# Simoleons

An imaginary currency Agoric documentation uses in examples.

# Terms

Contract instances have associated terms, gotten via E(zoe).getTerms(instance), which include the instance's associated issuers, brands, and any custom terms. For example, you might have a general auction contract. When someone instantiates it, they provide terms applicable only to that instance. For some instances of the auction, they want the minimum bid set at $1000. At other instances, they'd like it set at $10. They can specify the instance's minimum bid amount in its terms.

# Value

Values are the part of an amount that describe the value of something that can be owned or shared: How much, how many, or a description of a unique asset, such as Pixel(3,2), $3, or “Seat J12 for the show September 27th at 9:00pm”. Fungible values are usually represented by natural numbers. Other values may be represented as a CopySet of strings naming particular rights or arbitrary objects representing the rights directly (usually non-fungible assets). Values must be Keys.

For more information, see the ERTP Guide's Value section.

# Vat

A vat is a unit of isolation. Objects and functions in a JavaScript vat can communicate synchronously with one another. Vats and their contents can communicate with other vats and their objects and functions, but can only communicate asynchronously.

For more information, see the Vat section in the Distributed JS Programming Guide

# Wallet

The overall place a party keeps their assets of all brands. For example, your wallet might contain 5 Quatloos purses, 8 Moola purses, and 2 Simoleons purses. A wallet can distinguish between issuers. Dapps can propose offers to a wallet. If a user accepts the offer proposal, the wallet makes an offer on the user's behalf and deposits the payout in the user's purses. See the Wallet Guide and API.

# ZCF

ZCF (Zoe Contract Facet) is the facet of Zoe exposed to contract code. The Zoe Contract Facet methods can be called synchronously by contract code.

See the ZCF API.

# ZCFMint

See Mint.

# Zoe Helpers

A set of API helper methods for writing contracts. These methods extract common contract code and patterns into reusable helpers. See the Zoe Helpers API.

# Zoe Service

A set of API methods for deploying and working with smart contracts. See Zoe Service API.