# Glossary

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

# AllegedName

Human-readable name of a kind of rights. 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.

# AmountMath

AmountMath executes the logic of how amounts are changed when digital assets are merged, separated, or otherwise manipulated. For example, a deposit of 2 bucks into a purse that already has 3 bucks gives a new balance of 5 bucks. An empty purse has 0 bucks. AmountMath relies heavily on polymorphic MathHelpers, which manipulate an amount's value or unbranded portion. Standard natural number operations cannot be used on values, since they can be an array or object. See the ERTP Guide's AmountMath section and the ERTP API's AmountMath section for more information.

# Amounts

Amounts are the canonical description 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 an value. For example, "4 quatloos" is an amount with a value of "4" and a brand of the imaginary currency "quatloos".

See the ERTP Guide's Amounts section and the ERTP API's AmountMath section for more information.

# AssetHolder

Purses and payments are AssetHolders. These are objects that contain amounts.

# Brand

Identifies the kind of issuer, such as "quatloos", "moola", etc. Brands are one of the two elements that make up an amount. See the ERTP Guide's Brand section and the ERTP API's Brand section for more information.

# Comparable

A passable is something that can be marshalled. A comparable is a passable whose leaves contain no promises. Two comparables can be synchronously compared for structural equivalence.

A comparable is a JavaScript object containing no promises, and can thus be locally compared for equality with another object. If either object contains promises, equality is indeterminable. If both are fullfilled down to Presences and local state, then either they're the same all the way down, or they represent different objects.

# Contract and Contract Instance

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

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.

# 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.

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

# 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 ‘Right to occupy on Tuesdays’. Fungible values are usually represented by natural numbers. Other values may be represented as strings naming a particular right, or an arbitrary object representing the rights at issue. The latter two examples are usually non-fungible assets. Values must be Comparable.

See the ERTP Guide's Value section for more information.

# Fungible

A fungible asset is one where all exemplars of the asset are interchangable. 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.

For example, Zoe often uses offerHandle to refer to offers. Zoe contracts can use an offer's offerHandle as the key for requesting the current allocation of an offer or reallocating the offer's assets.

# Issuer

Issuers are linked to a single mint and vice versa, so each issuer works with one and only one asset type, such as only working with quatloos or only working with moola. They can create empty purses and payments 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.

See the ERTP Guide's Issuer section and the ERTP API's Issuer section for more information.

# MathHelpers

MathHelpers are methods for performing arithmetic operations on an amount's value. AmountMath uses MathHelpers to do value arithmetic, after which it brands the result to create a new amount. For more information, see the MathHelpers ERTP Guide section and the MathHelpers ERTP API section.

# Mint

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

Mints are issuer's admin facets, and there is a one-to-one relationship between an issuer and its mint.

See the ERTP Guide's Mint section and the ERTP API's Mint section for more information.

# Non-fungible

A non-fungible asset is one where each incidence of the asset has unique individual properties and is not interchangable with another incidence. For example, if your asset is show 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 interchangable (and may even have different prices). See also fungible.

# Notifier

You can track updates to contract state using a notifier. The notifier provides a stream of updates describing changes to the state of an offer.

See more: Notifier

# Object Capabilities

Objects have state, behavior, and references. Lets 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 commuicate 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 get a reference in only three ways.

  • Creation: Functions that create objects get a reference to them.
  • Construction: Constuctors 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.

# Payment

Payments hold amounts of certain assets issued by Mints. Specifically amounts that are in transit from one party to another. Amounts from payments can be deposited in purses, but otherwise, the entire amount is available when the payment is transferred. Payments can be converted to Purses. All contents of a purse must be of the same brand.

See the ERTP Guide's Payments section and the ERTP API's Payments section for more information.

# Presence

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

# Purse

Purses hold amounts of certain mint issued assets. Specifically amounts that are stationary. Purses can transfer part of their held balance to a payment, which is usually used to transfer value. A purse's contents are all of the same brand.

See the ERTP Guide's Purses section and the ERTP API's Purses section for more information.

# Vat

A vat is a unit of synchrony. This means that within a JavaScript vat, objects and functions can communicate with one another synchronously.

A vat runs a single event loop.

A physical machine can run one or several vats. A blockchain can run one or several communicating vats.

Different vats can communicate by sending asynchronous messages to other vats.

A vat is the moral equivalent of a Unix Process.