Agoric Documentation

Appearance

Glossary ​

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

Agoric CLI ​

A command line interface for initializing, deploying, and starting Agoric projects, as well as installing dependencies. See the Agoric CLI documentation for more information.

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.

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 documentation's Amounts section and the ERTP API's AmountMath section.

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.). Amount 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 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 documentation's AmountMath section and the ERTP API's AmountMath section.

AmountValue ​

An AmountValue is the part of an Amount that describes the value of something that can be owned or shared: how much, how many, or a description of a unique asset, such as $3, Pixel(3,2), or “Seat J12 for the show September 27th at 9:00pm”. For a fungible Amount, the AmountValue is usually a non-negative BigInt such as 10n or 137n. For a non-fungible Amount, the AmountValue might be a CopySet containing strings naming particular rights or objects representing the rights directly.

For more information, see the ERTP documentation's AmountValue section.

AssetHolder ​

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

Baggage ​

baggage is a MapStore that provides a way to preserve state and behavior of objects between smart contract upgrades in a way that preserves identity of objects as seen from other vats.

BigInt ​

In ERTP AmountMath, we use the JavaScript BigInt 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 documentation'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:

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

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

Burn ​

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

Comparable ​

Comparable is a deprecated synonym of Key.

Continuing Invitation Pattern ​

A continuing invitation presumes a previous offer whose result includes capabilities to make further invitations. See source: 'continuing' in Specifying Offers for details.

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.

CopyArray ​

A hardened acyclic array in which each element is passable, such as harden(['foo', 'bar']). For more information, see the Marshaling section in the JavaScript Distributed Programming Guide.

CopyRecord ​

A hardened acyclic plain object dictionary in which each key is a string and each value is passable, such as harden({ keys: [0, 1], values: ['foo', 'bar'] }). For more information, see the Marshaling section in the JavaScript Distributed Programming Guide.

Creator Invitation ​

An invitation optionally returned by E(zoe).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. For more details, see the agoric-sdk network package.

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

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 documentation and ERTP API documentation.

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 ​

An object specifying how an offer can be cancelled, such as on demand or by a deadline. For details, see E(zoe).offer(...).

Exo ​

An Exo object is an exposed Remotable object with methods (aka a Far object) which is normally defined with an InterfaceGuard as a protective outer layer, providing the first layer of defensiveness.

This @endo/exo package defines the APIs for making Exo objects, and for defining ExoClasses and ExoClassKits for making Exo objects.

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 that forwards method calls:

js
import { Far } from '@endo/far';
const facet = Far('FacetName', {
  myMethod: (...args) => oldObject.method(...args),
});

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

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 run code you don't completely trust, without being vulnerable to their bugs or bad intentions. See the Endo and Hardened JavaScript Programming Guide for more details.

IBC ​

The Inter-Blockchain Communication protocol, used by blockchains to communicate with each other. For more details, see What developers need to know about inter-blockchain communication.

Intercahin Account (ICA) ​

Interchain Accounts are an IBC feature used in Agoric's Orchestration API to enable an Agoric smart contract to control an account on another blockchain within the Cosmos ecosystem. This feature leverages the Inter-Blockchain Communication (IBC) protocol to facilitate interactions and transactions across different blockchains seamlessly.

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 documentation'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). AmountValues must be Keys.

Keyword ​

A Keyword is a string that is an ASCII-only identifier, starts with an upper case letter, and is not equal to "NaN" or "Infinity". See Zoe Data Types.

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 documentation'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.

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

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.

Orchestration ​

Orchestration API is a tool to help developers build seamless applications out of disparate interoperable chains and services. This composability allows for the development of user-centric applications that leverage the unique strengths of different blockchain ecosystems. Orchestration integrates with existing Agoric components (SwingSet, Cosmos modules) and introduces vat-orchestration. This vat manages Inter-Chain Account (ICA) identities and connections to host chains, ensuring proper transaction authorization. For more information, see the Orchestration API.

Passable ​

A passable is something that can be sent to and from remote objects. Passables include pass-by-copy primitive values such as numbers and strings and pass-by-reference values such as Remotables and Promises. Passables also include CopyArrays and CopyRecords, which are hardened acyclic pass-by-copy containers that recursively terminate in non-container passables.

For more information, see the Marshaling section in the JavaScript Distributed Programming Guide.

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 documentation'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 reallocation, the payout may be different than what the user escrowed (but still constrained by offer safety). Otherwise, 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/or exit properties respectively expressing offer conditions regarding what assets will be given, what is desired in exchange (protected by offer safety), and an exit rule defining how/when the offer can be canceled. For example:

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

give and want each associate Keywords defined by the contract with corresponding Amounts describing respectively what will be given and what is being requested in exchange.

See Offers.

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 documentation'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.

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.

For example, see starting the offer-up contract.

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

The concept of a vat is metaphorically inspired by the philosophical experiment known as “Brain in a Vat.” This thought experiment, explored in philosophy, posits a scenario in which a brain is sustained in a vat and connected to a computer that simulates reality, raising questions about knowledge, reality, and perception. Similarly, in the context of distributed systems, a vat isolates and encapsulates its contents, maintaining strict boundaries on synchronous and asynchronous communication, much like the hypothetical brain’s isolated and controlled environment. For more details, see the Wikipedia page on Brain in a Vat.

Vow ​

Vows are objects that represent promises that can be stored durably. Native promises are not compatible with Agoric's durable stores, which means that on the Agoric platform, such promises disconnect their clients when their creator vat is upgraded.

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.

Zone ​

Each Zone provides an API that allows the allocation of Exo objects and Stores (object collections) which use the same underlying persistence mechanism. This allows library code to be agnostic to whether its objects are backed purely by the JS heap (ephemeral), pageable out to disk (virtual) or can be revived after a vat upgrade (durable).

See SwingSet vat upgrade documentation for more example use of the zone API.

© 2024 Agoric Systems Operating Company. All Rights Reserved.