back to Agoric

01 - Introduction to Agoric

Chapter 1 covers the history, stack, and basic concepts of Agoric

Brief motivation & History

Agoric is a smart contract platform aiming to bring developers to the DeFi frontier. It offers a public blockchain in the Cosmos ecosystem, a secure subset of JavaScript for writing smart contracts, and a set of protocols to facilitate DeFi-oriented features, such as Offer Safety.

Agoric is designed with composability in mind, making it easy to use or write reusable smart contracts. Furthermore, thanks to Dynamic IBC, digital assets and services can operate across different blockchains.

Its origins can be traced back to a 1988 paper by Mark S. Miller and K. Eric Drexler by the title Markets and Computation: Agoric Open Systems, which "examines markets as a model for computation and proposes a framework [Agoric systems] for applying the power of market mechanisms to the software domain", all within the context of decentralized models.

For a deeper look into the Agoric platform check out the Agoric Token and Crypto Economy White Paper.

Stack Overview

The Agoric stack is made up of the following systems: Smart Contract Framework, Agoric VM, and Agoric Public Blockchain.

Smart Contract Framework

The Smart Contract Framework consists of two protocols: ERTP, and Zoe. ERTP (Electronic Rights Transfer Protocol) provides a standard way to represent digital assets in a secure manner. Zoe is a framework for writing JavaScript smart contracts, it leverages ERTP to abstract the complexity of digital assets and allow developers to focus on the business logic. Together, they provide offer safety and payout-liveness guarantees, increasing trust in the platform by protecting users against malicious or buggy code, this will be explained in detail in later sections.

Agoric VM

Under the hood, Agoric VMs consist of a secure, distributed JavaScript runtime that enforces Object-capability (OCap) security architecture, in which access to a programming object itself is the authority to use the object. JavaScript's popularity was in part driven by its composability, allowing code components to be published and imported with ease across projects (think NPM). Agoric's Hardened Javascript (SES), among other things, provides a secure way to use such components, mitigating risks involved in using third party code.

Agoric Public Chain

The Agoric VM is consensus agnostic and designed to run on the best available engine. The initial launch will be on the Cosmos Ecosystem, built on the Tendermint consensus engine. Tendermint is a proven Byzantine Fault Tolerant (BFT) consensus engine providing fast throughput and finality. Additionally, Dynamic IBC can handle communication across chains, enabling a wide range of use cases.

In short, Agoric provides a secure and familiar system for creating and exchanging digital assets in a decentralized manner.

Agoric Dapp

A typical Agoric decentralized app is made up of the following stack layers:

  • Smart Contract(s): contains the business logic of the application, written in SES (Secure Ecma Script, also referred to as Hardened JS).
  • Wallet: actors in Agoric are represented by a wallet. Holds and manages digital assets and interactions with smart contracts via Zoe Invitations. Sits between the client and blockchain, providing an extra layer of security by allowing the user to review actions initiated by external applications.
  • Client: framework-agnostic web application, only requirement here is that it can run JS. Tasked with retrieving and displaying contract data, as well as forming requests to interact with the contract layer, much like the client-backend relation in web2.
  • Local Bridge: web-socket connection managing communication between the wallet and client. Allows the client to read information from wallets, and send requests to interact with smart contracts.

ERTP, Zoe, and Offer Safety

Let's dive deeper into Agoric's smart contract layer: Zoe. Tasked with the creation and handling of smart contracts, Zoe plays a big role in enforcing some of the fundamental concepts that make Agoric unique. Along with ERTP, Zoe allows users to define what they expect to give and/or receive on a transaction-basis and ensures those conditions are met, reverting to the original state otherwise. This is known as Offer Safety, and becoming familiar with the concept and how to implement it will allow you to get the most out of Agoric contracts/dapps.

Imagine a smart contract that sells NFTs accepting IST (Agoric's stable token) as payment. A user wanting to purchase an NFT using this contract can form an offer defining the NFT they expect to receive, and the amount of IST they are willing to pay for it. Zoe will then escrow the asset(s) you're willing to give, and guarantees the offer will resolve in one of two ways:

  • All parties get their specified "want": everything went as expected and the payouts are executed accordingly. In the above scenario: the contract is willing to sell the NFT for the IST amount the user stated in the proposed offer, offer is accepted and the user’s IST is transferred to the contract, while the NFT goes to the user.
  • All parties get their specified "give": something went wrong or the offer was canceled before completion and the escrowed assets return to the owners. In the above scenario: the contract wants to sell the NFT for more than the IST amount the user stated in the proposed offer, offer is rejected by the contract, the user receives the IST they escrowed, and the contract keeps the NFT.

Furthermore, exit conditions can be set to customize the logic under which offers can be exited such as time-based expiration, or disallowing users from backing out of accepted offers.

Offer Safety allows users to send assets without the need to understand or trust the contract code that handles it, knowing Zoe will guarantee the proposed offer will be fulfilled or reverted. As for developers, it mitigates risk by limiting the impact of bugs in the code.

Note that while Offer Safety is always enforced, it is limited to Offers (contract calls involving assets), which isn't the only way to interact with smart contracts. Furthermore, users can simply disregard the want and/or give properties of an offer, effectively bypassing Offer Safety checks. Design patterns aimed at making the most of this feature will be discussed in detail in later sections of this guide.

Digital assets are fundamental to the decentralized financial market that Agoric envisions, and the Electronic Rights Transfer Protocol (ERTP) defines how they operate in Agoric. Chapter 3 will showcase how to design and implement NFT solutions in detail.


Secure Ecma Script is a subset of Javascript designed to make JS secure and it's required for developing Agoric smart contracts and web interfaces meant to interact with them. Its main features include:

  • Compartments: Compartments are separate execution contexts: each one has its own global object and global lexical scope.
  • Frozen realm: Compartments share their intrinsics to avoid identity discontinuity. By freezing the intrinsics, SES protects programs from each other. By sharing the intrinsics, programs from separate compartments can recognize each other's arrays, data objects, and so on.
  • Strict mode SES: Enforces JavaScript strict mode that enhances security, for example by changing some silent failures into thrown errors.
  • POLA (Principle of Least Authority): By default, Compartments receive no ambient authority. They are created without host-provided APIs, (for example no fetch). Compartments can be selectively endowed with powerful arguments, globals, or modules.

SES safely executes third-party JavaScript 'strict' mode programs in compartments that have no excess authority in their global scope. SES runs atop an ES6-compliant platform, enabling safe interaction of mutually-suspicious code, using object-capability -style programming.

Additional Resources

Explore the following resources for further details about Agoric and it's features:

  • Agoric Documentation Guide: The Agoric documentation is the obvious choice for learning more about the platform. Follow this link for a summary of the current docs' content and how to use it.
  • Youtube: their Youtube channel includes tutorials, conference talks, and community calls. You'll find a great deal of lerning content here, from very broad concept presentations to feature specific development tutorials. A word of caution: some of the tutorials presented, though still useful, may showcase outdated code (upgrades have been made to some services of the SDK).
  • Papers: A comprehensive list of Papers detailing the efforts that lead to the creation of Agoric.
  • Glossary: Quick reference for any Agoric specific term.
  • Source code: For hard implementation details you may want to keep the source code handy. The packages/ directory contains the code for most SDK features, helpful comments can be found in the code, as well as types.