agoric-sdk

[Edit section]

[Copy link]

• • •

The Agoric SDK is a monorepo that provides a comprehensive platform for building secure and scalable decentralized applications (dApps) on top of the Agoric blockchain. At the core of the Agoric SDK is the Swingset runtime, which is responsible for executing smart contracts and managing the overall state of the Agoric platform.

The most important components of the Agoric SDK include:

• Swingset Kernel: The central runtime and execution environment for the Agoric platform, handling tasks such as message passing, promise resolution, device management, and garbage collection. The kernel is implemented in the …/SwingSet directory.

• Zoe Contract Framework: A secure and flexible platform for building and executing smart contracts, with a focus on offer safety, rights conservation, and contract upgradability. The Zoe framework is implemented in the …/zoe directory.

• Cosmic Proto: The protocol buffer (protobuf) definitions and generated code for interacting with the Cosmos ecosystem, including modules for Amino, Cosmos, IBC, ICQ, and Tendermint. This is located in the …/cosmic-proto directory.

• Inter-Protocol: The implementation of the Agoric Inter-Protocol system, which includes an auction system, price oracle, vault factory, and Parity Stability Module. This is found in the …/inter-protocol directory.

• Swingset Runner: A tool for managing the execution of the Agoric Swingset, including state management, performance analysis, and benchmarking. This is located in the …/swingset-runner directory.

• Vats: The core functionality for bootstrapping, managing, and upgrading various aspects of the Agoric platform, such as client provisioning, chain configuration, and IBC communication. This is implemented in the …/vats directory.

• ERTP: The implementation of the Agoric ERTP (Electronic Rights Transfer Protocol) system for managing the transfer and representation of digital assets. This is found in the …/ERTP directory.

• Orchestration: The core functionality for the orchestration system in the Agoric SDK, enabling the management of assets and services across different blockchain networks. This is located in the …/orchestration directory.

• Smart Wallet: The implementation of the Agoric Smart Wallet system, including wallet state management, offer handling, and wallet factory upgrades. This is found in the …/smart-wallet directory.

The Agoric SDK relies on several key technologies and design choices, including:

• Swingset Kernel: The Swingset kernel is responsible for managing the overall state of the Agoric platform, including message passing, promise resolution, and device management. It uses a vat-based architecture to isolate the execution of untrusted code. Swingset Kernel

• Zoe Contract Framework: Zoe provides a secure and flexible platform for building and executing smart contracts, with a focus on offer safety, rights conservation, and contract upgradability. It uses a contract facet and contract support system to separate the core contract logic from the supporting functionality. Zoe Contract Framework

• Cosmos Integration: The Agoric SDK integrates with the Cosmos ecosystem through the use of protocol buffers (protobuf) and the Cosmos SDK. This allows the Agoric platform to leverage the existing Cosmos infrastructure and interoperability features. Cosmic Proto

• Inter-Protocol: The Inter-Protocol system provides a set of core financial primitives, such as an auction system, price oracle, and vault factory, that can be used to build decentralized finance (DeFi) applications on top of the Agoric platform. Inter-Protocol

• Orchestration: The orchestration system in the Agoric SDK enables the management of assets and services across different blockchain networks, allowing for cross-chain interoperability and coordination. Orchestration

Swingset Kernel

[Edit section]

[Copy link]

References: packages/SwingSet

• • •

The Agoric SwingSet is the core runtime and execution environment for the Agoric platform. It provides a secure and extensible framework for building and running distributed applications. The SwingSet kernel is responsible for managing the lifecycle of isolated JavaScript environments called "vats", handling communication between vats, and providing access to external devices and resources.

Vat Loader

[Edit section]

[Copy link]

References: packages/SwingSet/src/kernel/vat-loader

• • •

The Vat Loader is responsible for instantiating new vats and loading test vats. It provides the makeVatLoader() function, which returns an object with two methods: create() and loadTestVat().

Kernel Syscall Handler

[Edit section]

[Copy link]

References: packages/SwingSet/src/kernel/kernelSyscall.js

The Kernel Syscall Handler provides core functionality for managing the kernel's system calls, including:

Kernel Queue

[Edit section]

[Copy link]

References: packages/SwingSet/src/kernel/kernelQueue.js

• • •

The Kernel Queue manages the kernel's message queue and promise resolution, including sending messages to kernel objects, subscribing to and resolving kernel promises, and queueing messages with configurable resolution policies.

Vat Translator

[Edit section]

[Copy link]

References: packages/SwingSet/src/kernel/vatTranslator.js

• • •

The Vat Translator provides functions for translating between kernel-centric and vat-centric representations of various objects and messages. It defines several translator functions that allow the kernel to communicate with individual vats in a consistent manner.

Device Manager

[Edit section]

[Copy link]

References: packages/SwingSet/src/kernel/deviceManager.js

• • •

The makeDeviceManager function in …/deviceManager.js sets up the device manager and provides the invoke function for interacting with devices.

Device Slots

[Edit section]

[Copy link]

References: packages/SwingSet/src/kernel/deviceSlots.js

• • •

The Device Slots sets up the necessary infrastructure for device code to interact with the SwingSet kernel. The main functionality is provided by the makeDeviceSlots function, which is responsible for creating the necessary components for device code to communicate with the SwingSet kernel.

Device Translator

[Edit section]

[Copy link]

References: packages/SwingSet/src/kernel/deviceTranslator.js

• • •

The Device Translator provides functions for translating between kernel-level and device-level invocations and syscalls. It defines several key functions that act as translators, converting between the different representations used by the kernel and the devices.

Garbage Collection

[Edit section]

[Copy link]

References: packages/SwingSet/src/kernel/gc-actions.js

• • •

The Garbage Collection module processes the set of Garbage Collection (GC) actions stored in the kernel keeper and determines which actions should be executed.

Vat Termination Notification

[Edit section]

[Copy link]

References: packages/SwingSet/src/kernel/notifyTermination.js

• • •

The Vat Termination Notification module is responsible for notifying the vatAdmin (a component responsible for managing vats, which are isolated JavaScript execution environments) when a vat has terminated. The main functionality is provided by the notifyTermination() function, which is defined in the …/notifyTermination.js file.

Metrics

[Edit section]

[Copy link]

References: packages/SwingSet/src/kernel/metrics.js

• • •

The Metrics module defines the metrics that the SwingSet kernel collects and reports. This module exports two arrays of metric definitions:

Logging

[Edit section]

[Copy link]

References: packages/SwingSet/src/kernel/slogger.js

• • •

The Logging module provides functionality for logging and tracking the execution of vats within the SwingSet kernel. The main components of this module are:

Vat Administration

[Edit section]

[Copy link]

References: packages/SwingSet/src/kernel/vat-admin-hooks.js

• • •

The Vat Administration module provides functions that allow for the creation, upgrade, and termination of "vats" (isolated JavaScript execution environments) within the Agoric platform.

Vat Warehouse

[Edit section]

[Copy link]

References: packages/SwingSet/src/kernel/vat-warehouse.js

• • •

The Vat Warehouse manages the lifecycle of vats, including creating, starting, stopping, and evicting vats, as well as managing their transcripts and snapshots.

Zoe Contract Facet

[Edit section]

[Copy link]

References: packages/zoe/src/contractFacet

• • •

The Zoe Contract Facet (ZCF) is the core component responsible for managing the lifecycle of Zoe contract instances, including offer processing, asset allocation, and other contract-specific logic. The primary functionality is provided by the makeZCFZygote function, which sets up the necessary infrastructure and returns a ZCFZygote object that can be used to start and restart contract instances.

Zoe Contract Support

[Edit section]

[Copy link]

References: packages/zoe/src/contractSupport

• • •

The …/contractSupport directory provides a rich set of utility functions and modules that support the development of Zoe contracts. These utilities cover a wide range of functionalities, including:

Zoe Contract Implementations

[Edit section]

[Copy link]

References: packages/zoe/src/contracts

The …/contracts directory in the Agoric SDK contains a variety of smart contract implementations that leverage the Zoe contract framework. These contracts provide a wide range of functionality, including:

Zoe Service

[Edit section]

[Copy link]

References: packages/zoe/src/zoeService

• • •

The core functionality of the Zoe Service is to manage the execution of Zoe contracts, including handling offers, creating and managing invitations, and providing storage and access to various components used by the Zoe service.

Swingset Core

[Edit section]

[Copy link]

References: packages/cosmic-proto/src/codegen/agoric/swingset

• • •

The Swingset Core provides the fundamental functionality of the Agoric SwingSet, which is a key component of the Agoric blockchain platform. This subsection covers the core data structures, message types, query methods, and genesis state of the SwingSet.

Virtual Bank (VBank)

[Edit section]

[Copy link]

References: packages/cosmic-proto/src/codegen/agoric/vbank

• • •

The Agoric Virtual Bank (VBank) module is responsible for managing the reward pool and distribution of rewards to the fee collector module on a per-block basis. The key functionality of this module is defined in the following files:

Virtual Storage (vStorage)

[Edit section]

[Copy link]

References: packages/cosmic-proto/src/codegen/agoric/vstorage

• • •

The Agoric Virtual Storage (vStorage) system is a core component of the Agoric SDK, responsible for managing the persistent storage of data within the Agoric blockchain platform. The vStorage system is defined in the …/vstorage directory, which contains the following key components:

Cosmos Authentication

[Edit section]

[Copy link]

References: packages/cosmic-proto/src/codegen/cosmos/auth

• • •

The Cosmos SDK's authentication module is responsible for managing user accounts and their associated data, such as public keys, account numbers, and sequence numbers. The key components of this module are:

Cosmos Bank

[Edit section]

[Copy link]

References: packages/cosmic-proto/src/codegen/cosmos/bank

• • •

The Cosmos SDK's bank module is responsible for managing the token balances and total supply of the network. The key functionality provided by this module includes:

Cosmos Base

[Edit section]

[Copy link]

References: packages/cosmic-proto/src/codegen/cosmos/base

• • •

The Cosmos SDK's base components provide core functionality for building blockchain applications, including:

Cosmos Cryptography

[Edit section]

[Copy link]

References: packages/cosmic-proto/src/codegen/cosmos/crypto

• • •

The Cosmos SDK ecosystem utilizes several cryptographic primitives, including ed25519, secp256k1, secp256r1, and multi-signature keys, as well as hierarchical deterministic (HD) wallet parameters.

Cosmos Distribution

[Edit section]

[Copy link]

References: packages/cosmic-proto/src/codegen/cosmos/distribution

• • •

The Cosmos SDK's distribution module is responsible for handling the distribution of rewards and fees within the Cosmos ecosystem. This module provides functionality for managing various aspects of the distribution process, including:

Cosmos Governance

[Edit section]

[Copy link]

References: packages/cosmic-proto/src/codegen/cosmos/gov

• • •

The Cosmos SDK's governance module provides functionality for managing proposals, votes, and deposits within the Cosmos ecosystem. This subsection will cover the key components and design choices of this module.

Cosmos Minting

[Edit section]

[Copy link]

References: packages/cosmic-proto/src/codegen/cosmos/mint

• • •

The Cosmos SDK's mint module is responsible for managing the minting of new tokens and the inflation rate. The main functionality of this module is defined in the following files and types:

Cosmos Parameters

[Edit section]

[Copy link]

References: packages/cosmic-proto/src/codegen/cosmos/params

• • •

The Cosmos SDK's parameter management system is defined in the …/v1beta1 directory. This subsection covers the functionality related to defining parameter change proposals and querying parameter values.

Cosmos Staking

[Edit section]

[Copy link]

References: packages/cosmic-proto/src/codegen/cosmos/staking

• • •

The Cosmos SDK's staking module is responsible for managing validators, delegations, unbonding delegations, and redelegations within the Cosmos ecosystem. The core functionality of this module is defined in the following files and directories:

Cosmos Transactions

[Edit section]

[Copy link]

References: packages/cosmic-proto/src/codegen/cosmos/tx

• • •

The …/v1beta1 directory contains the core data structures and functionality related to Cosmos SDK transactions. This includes the definition of the standard transaction type (Tx), the raw transaction type (TxRaw), and various supporting types for signing, authorization, and fee information.

Cosmos Upgrades

[Edit section]

[Copy link]

References: packages/cosmic-proto/src/codegen/cosmos/upgrade

• • •

The Cosmos SDK's software upgrade functionality is managed through the …/v1beta1 directory. This subsection covers the key components and their responsibilities:

Cosmos Vesting

[Edit section]

[Copy link]

References: packages/cosmic-proto/src/codegen/cosmos/vesting

• • •

The Cosmos SDK provides various types of vesting accounts to manage the gradual release of tokens over time, with different vesting schedules and locking mechanisms. These vesting account types are defined in the …/vesting.ts file.

IBC Applications: Interchain Accounts

[Edit section]

[Copy link]

References: packages/cosmic-proto/src/codegen/ibc/applications/interchain_accounts

• • •

The Interchain Accounts (ICA) application in the Cosmos SDK is responsible for managing the communication and execution of transactions between a controller chain and its associated host chains. The implementation of this application is divided into two main submodules: the ICA Controller and the ICA Host.

IBC Applications: Token Transfer

[Edit section]

[Copy link]

References: packages/cosmic-proto/src/codegen/ibc/applications/transfer

• • •

The IBC token transfer application allows for the transfer of fungible tokens between ICS20-enabled chains. The core functionality is implemented in the …/transfer directory.

IBC Core: Channels

[Edit section]

[Copy link]

References: packages/cosmic-proto/src/codegen/ibc/core/channel

• • •

The …/v1 directory contains the definitions and functionality related to the Inter-Blockchain Communication (IBC) channel protocol. The key components in this directory are:

IBC Core: Clients

[Edit section]

[Copy link]

References: packages/cosmic-proto/src/codegen/ibc/core/client

• • •

The …/v1 directory contains the core functionality related to the IBC (Inter-Blockchain Communication) client in the Cosmos SDK. It defines the data structures and utility functions for managing IBC clients, including their client states, consensus states, and various governance proposals for updating and upgrading clients.

IBC Core: Commitment

[Edit section]

[Copy link]

References: packages/cosmic-proto/src/codegen/ibc/core/commitment

• • •

The …/v1 directory contains code related to Merkle proofs and commitment roots in the context of the Interblockchain Communication (IBC) protocol. The main components defined in this directory are:

IBC Core: Connections

[Edit section]

[Copy link]

References: packages/cosmic-proto/src/codegen/ibc/core/connection

• • •

The IBC (Inter-Blockchain Communication) connection layer is responsible for managing the lifecycle of connections between two blockchains. The core functionality is implemented in the …/connection directory.

Auction System

[Edit section]

[Copy link]

References: packages/inter-protocol/src/auction

• • •

The Auction System in the Agoric Inter-Protocol is a critical component that manages the collateral-specific state of ongoing auctions. It consists of the following key elements:

Vault Factory

[Edit section]

[Copy link]

References: packages/inter-protocol/src/vaultFactory

• • •

The core functionality of the Vault Factory is to allow users to deposit collateral and borrow "Minted" tokens. The main components and functionality are:

Parity Stability Module (PSM)

[Edit section]

[Copy link]

References: packages/inter-protocol/src/psm

The Parity Stability Module (PSM) is a component within the Agoric SDK's inter-protocol package that supports efficiently minting and burning a stable token at a fixed ratio to a reference stable token. The key functionality and design choices in the implementation are:

Proposals

[Edit section]

[Copy link]

References: packages/inter-protocol/src/proposals

The …/proposals directory contains various scripts and utilities related to proposals and governance in the Agoric SDK. These scripts are used to manage the deployment and configuration of key components of the Inter Protocol, such as the Vault Factory, Auctioneer, Reserve, and Economic Committee.

Client Support

[Edit section]

[Copy link]

References: packages/inter-protocol/src/clientSupport.js

• • •

The clientSupport.js file located at …/clientSupport.js provides utility functions and data structures for creating and managing various types of offers in the Agoric platform.

Fee Distributor

[Edit section]

[Copy link]

References: packages/inter-protocol/src/feeDistributor.js

• • •

The …/feeDistributor.js file implements the core functionality of the Fee Distributor contract in the Agoric platform. The Fee Distributor is responsible for collecting and distributing fees within the Agoric ecosystem.

Interest Calculations

[Edit section]

[Copy link]

References: packages/inter-protocol/src/interest-math.js, packages/inter-protocol/src/interest.js

• • •

The interest.js file located at …/interest.js provides the core functionality for calculating and applying interest on debt within the Agoric platform.

Provision Pool

[Edit section]

[Copy link]

References: packages/inter-protocol/src/provisionPool.js, packages/inter-protocol/src/provisionPoolKit.js

• • •

The important functionality in the file …/provisionPool.js can be summarized as follows:

Tokens

[Edit section]

[Copy link]

References: packages/inter-protocol/src/tokens.js

• • •

The tokens.js file in the …/tokens.js directory exports two named exports: Stable and Stake. These appear to be references to functionality related to tokens, but the file itself does not contain any additional implementation details.

Swingset Runner Execution and Management

[Edit section]

[Copy link]

References: packages/swingset-runner/src/main.js, packages/swingset-runner/src/runner-debug-entrypoint.js, packages/swingset-runner/src/runner-entrypoint.js

• • •

The Swingset Runner is the primary tool for managing the execution of the Agoric Swingset, the core runtime and execution environment for the Agoric platform. The Swingset Runner provides the following key functionality:

Swingset State Management

[Edit section]

[Copy link]

References: packages/swingset-runner/src/auditstore.js, packages/swingset-runner/src/dumpstore.js

• • •

The auditRefCounts() function in …/auditstore.js is responsible for auditing the reference counts of objects stored in the persistent store. This function performs the following key tasks:

Swingset Performance Analysis

[Edit section]

[Copy link]

References: packages/swingset-runner/src/dataGraphApp.js, packages/swingset-runner/src/graphDisk.js, packages/swingset-runner/src/graphMem.js, packages/swingset-runner/src/graphStats.js, packages/swingset-runner/src/graphTime.js

• • •

This subsection covers the tools and functionality for generating data graphs and visualizations to analyze the performance of the Swingset, including metrics related to disk usage, memory usage, and block statistics.

Swingset Logging and Debugging

[Edit section]

[Copy link]

References: packages/swingset-runner/src/slogulator.js, packages/swingset-runner/src/slogulator-debug-entrypoint.js, packages/swingset-runner/src/slogulator-entrypoint.js

• • •

The Slogulator is a powerful tool in the Agoric SDK that processes and analyzes the logs (referred to as "slogs") generated by the Agoric Swingset runtime. The Slogulator provides valuable insights and debugging capabilities, helping developers understand the execution of the Swingset and identify potential issues.

Swingset Utilities

[Edit section]

[Copy link]

References: packages/swingset-runner/src/chain.js, packages/swingset-runner/src/printStats.js

• • •

The chain.js file provides utility functions for managing the chain storage in the Swingset Runner. The exportStorage function exports and clears data from the chain storage, while the initEmulatedChain function initializes the emulated chain.

Bootstrapping and Management

[Edit section]

[Copy link]

References: packages/vats/src/core

• • •

The core functionality for bootstrapping the Agoric platform is primarily implemented in the …/core directory. This directory contains several key files that work together to set up the initial state, manage client bundles and provisioning, and configure the chain storage and communication.

Upgrading and Proposals

[Edit section]

[Copy link]

References: packages/vats/src/proposals

• • •

The …/proposals directory contains functionality for managing and upgrading different components of the Agoric platform. This includes repairing and reviving subscriptions, managing the local blockchain, upgrading the provisioning vat, and more.

Utilities and Testing

[Edit section]

[Copy link]

References: packages/vats/test, packages/vats/tools

• • •

The …/test directory contains a collection of utility functions and mocks that can be used to facilitate testing and development of the Agoric platform, particularly for working with the bank, board, and IBC components.

Mathematical Helpers

[Edit section]

[Copy link]

References: packages/ERTP/src/mathHelpers

• • •

The …/mathHelpers directory contains a set of utility functions and data structures that support the management of digital assets within the Agoric ERTP (Electronic Rights Transfer Protocol) system.

Amount Management

[Edit section]

[Copy link]

References: packages/ERTP/src/amountMath.js, packages/ERTP/src/amountStore.js

• • •

The amountMath.js file in the …/amountMath.js provides a comprehensive set of utilities and functions for working with digital assets represented as "amounts". The AmountMath module defines the AssetKind constants, which represent the different types of assets supported, and provides functions for creating, coercing, and performing operations on these asset amounts.

Issuer Kits

[Edit section]

[Copy link]

References: packages/ERTP/src/issuerKit.js

• • •

The main functionality in the file …/issuerKit.js is as follows:

Payments and Purses

[Edit section]

[Copy link]

References: packages/ERTP/src/payment.js, packages/ERTP/src/purse.js

• • •

The preparePaymentKind() function in the …/payment.js file is responsible for creating a new Payment object, which is a type of AssetKind used in the Agoric platform to represent digital assets in transit.

Transient Notifiers

[Edit section]

[Copy link]

References: packages/ERTP/src/transientNotifier.js

• • •

The makeTransientNotifierKit() function creates notifiers that can be associated with specific keys (e.g., Purse instances) and updated as needed. This function is part of the …/transientNotifier.js file.

Type Guards

[Edit section]

[Copy link]

References: packages/ERTP/src/typeGuards.js

• • •

The typeGuards.js file in the …/typeGuards.js directory defines a set of type guards and interface definitions that ensure type safety and consistency throughout the ERTP (Electronic Rights Transfer Protocol) codebase.

Orchestration Accounts

[Edit section]

[Copy link]

References: packages/orchestration/src/exos

• • •

The IcaAccountKit in the …/ica-account-kit.js file provides the core functionality for managing Inter-Chain Accounts (ICAs), which are accounts on a remote chain. This kit is crucial for enabling cross-chain interactions within the Agoric SDK's orchestration system.

Orchestration Flows

[Edit section]

[Copy link]

References: packages/orchestration/src/examples

• • •

The …/examples directory contains several example contracts and utilities that demonstrate the use of the Orchestration API in the Agoric SDK. These examples cover a range of functionality, including:

Orchestration Setup and Management

[Edit section]

[Copy link]

References: packages/orchestration/src/proposals

• • •

The …/proposals directory contains the core functionality for setting up and managing the various components of the Agoric SDK's orchestration system.

Orchestration Utilities

[Edit section]

[Copy link]

References: packages/orchestration/src/utils

The …/utils directory provides a rich set of utility functions and helpers that support the orchestration functionality in the Agoric SDK. These utilities cover various aspects such as:

Wallet State Management

[Edit section]

[Copy link]

References: packages/smart-wallet/src/smartWallet.js, packages/smart-wallet/src/utils.js

The SmartWallet class, located in …/smartWallet.js, is responsible for managing the state of a user's digital wallet. This includes handling deposits, withdrawals, and balance updates.

Offer Handling

[Edit section]

[Copy link]

References: packages/smart-wallet/src/offers.js, packages/smart-wallet/src/offerWatcher.js, packages/smart-wallet/src/invitations.js

• • •

The core functionality for creating, executing, and monitoring offers made by users within the Agoric smart wallet system is located in the following files:

Wallet Factory Upgrades

[Edit section]

[Copy link]

References: packages/smart-wallet/src/walletFactory.js, packages/smart-wallet/src/proposals/upgrade-wallet-factory2-proposal.js, packages/smart-wallet/src/proposals/upgrade-walletFactory-proposal.js

• • •

The walletFactory.js file in the …/src directory provides the core functionality for creating and managing smart wallets in the Agoric platform. A key aspect of this file is the handling of upgrades from the first incarnation of the smart wallet to the second incarnation.

Ansible Roles

[Edit section]

[Copy link]

References: packages/deployment/ansible/roles

• • •

The …/roles directory contains Ansible roles and related files for deploying and configuring a Cosmos-based blockchain network. The main functionality provided by this directory includes:

Docker Deployment

[Edit section]

[Copy link]

References: packages/deployment/docker

• • •

The …/docker directory contains scripts and configuration files for setting up and running Docker-based deployments of the Agoric SDK. The main functionality includes:

Terraform Configurations

[Edit section]

[Copy link]

References: packages/deployment/terraform

• • •

The Terraform configuration files for deploying the Agoric platform on various cloud providers are located in the …/terraform directory. These configurations provide a flexible and customizable way to deploy the Agoric platform on different cloud platforms, including DigitalOcean, Docker, and Heroku.

Deployment Scripts

[Edit section]

[Copy link]

References: packages/deployment/scripts

• • •

The …/scripts directory contains a collection of scripts that are used to manage the deployment and integration testing of the Agoric SDK. These scripts handle various tasks, such as capturing integration test results, generating Docker deployment configurations, installing dependencies, running integration tests, and testing the Docker build process.

Deployment Source Code

[Edit section]

[Copy link]

References: packages/deployment/src

• • •

The …/src directory contains the source code for the Agoric deployment tool, which is responsible for setting up and managing the deployment of an Agoric Cosmos chain. The main functionality of this directory includes:

Big Dipper Deployment

[Edit section]

[Copy link]

References: packages/deployment/bigdipper

• • •

The …/bigdipper directory contains the setup guide and deployment script for the Agoric Big Dipper, a tool used in the Agoric blockchain ecosystem.

Changelogs

[Edit section]

[Copy link]

References: packages/deployment/changelogs

• • •

The …/changelogs directory contains files that provide instructions and configurations for setting up Prometheus monitoring on Agoric testnet nodes, as well as guidelines for maintaining changelogs for the Agoric SDK project.

CLI Commands

[Edit section]

[Copy link]

References: packages/agoric-cli/src/commands

• • •

The Agoric CLI tool provides a wide range of command-line interface (CLI) commands for interacting with the Agoric blockchain and ecosystem. These commands cover various functionalities, including:

Utility Functions

[Edit section]

[Copy link]

References: packages/agoric-cli/src/lib

The …/lib directory contains several key modules that provide utility functions for interacting with the Agoric blockchain, virtual storage, and other components.

CLI Entry Point

[Edit section]

[Copy link]

References: packages/agoric-cli/src/bin-agops.js

• • •

The bin-agops.js file serves as the entry point for the Agoric CLI (Command-Line Interface) tool. It sets up the command-line interface using the commander library and configures various sub-commands that handle different aspects of the Agoric ecosystem.

Deployment and Publishing

[Edit section]

[Copy link]

References: packages/agoric-cli/src/deploy.js, packages/agoric-cli/src/main-publish.js, packages/agoric-cli/src/publish.js

• • •

The Agoric CLI provides functionality for deploying scripts and publishing bundles to the Agoric network, as well as publishing bundles to Cosmos SDK-based chains.

Script Loading and Execution

[Edit section]

[Copy link]

References: packages/agoric-cli/src/scripts.js

• • •

The makeLookup function in …/scripts.js is a higher-order function that takes a bootstrap promise (bootP) as an argument and returns a lookup function. This lookup function allows you to recursively look up names in the context of the bootstrap promise.

Configuration Management

[Edit section]

[Copy link]

References: packages/agoric-cli/src/chain-config.js, packages/agoric-cli/src/cosmos.js

• • •

The …/chain-config.js file contains various constants and functions related to the configuration of the Agoric blockchain. This includes:

Wallet and Offer Management

[Edit section]

[Copy link]

References: packages/agoric-cli/src/open.js

• • •

The walletMain() function in …/open.js is responsible for interacting with the Agoric wallet. It performs the following key tasks:

Project Initialization and Installation

[Edit section]

[Copy link]

References: packages/agoric-cli/src/init.js, packages/agoric-cli/src/install.js

• • •

The main functionality for initializing new Agoric dapp projects and installing dependencies is provided in the …/init.js and …/install.js files.

Development Environment Management

[Edit section]

[Copy link]

References: packages/agoric-cli/src/start.js

• • •

The startMain() function in …/start.js serves as the entry point for the Agoric CLI's start command, which is responsible for managing various Agoric development environments.

Heap Zone

[Edit section]

[Copy link]

References: packages/base-zone/src/heap.js

• • •

The core functionality for creating and managing "heap zones" in the Agoric SDK is provided by the makeHeapZone() function in the …/heap.js file. Heap zones are in-memory execution environments that provide a secure and isolated environment for running Agoric SDK components.

Detached Heap Stores

[Edit section]

[Copy link]

References: packages/base-zone/src/heap.js

• • •

The base zone provides a set of default store implementations (set, map, weak map, weak set) that can be used within the zone. These detached heap stores are defined in the detachedHeapStores object within the …/heap.js file.

Exo-related Functionality

[Edit section]

[Copy link]

References: packages/base-zone/src/heap.js

• • •

The base zone provides APIs for creating and managing "exo" objects, which are a type of object used in the Agoric SDK. The makeHeapZone() function, which creates an in-memory "heap zone", includes the following exo-related functionality:

Subzone Creation

[Edit section]

[Copy link]

References: packages/base-zone/src/heap.js

• • •

The base zone provides functionality for creating new "subzones" that are isolated from the parent zone. This is achieved through the subZone property of the makeHeapZone() function, which allows creating new subzones within the heap zone.

XSnap Runtime

[Edit section]

[Copy link]

References: packages/xsnap/src

• • •

The XSnap (Extensible Secure Snapshots) runtime is a secure JavaScript runtime that allows for the execution and testing of Agoric SDK components in a sandboxed environment. The core functionality of the XSnap runtime is provided by the xsnap() function, which is responsible for managing the lifecycle of an XSnap worker process.

XSnap Testing Framework

[Edit section]

[Copy link]

References: packages/xsnap/test

The XSnap Testing Framework is a comprehensive suite of tests that verify the functionality and behavior of the XSnap runtime, which is a key component of the Agoric SDK. The tests cover a wide range of aspects, including:

XSnap Utility Scripts

[Edit section]

[Copy link]

References: packages/xsnap/scripts

• • •

The …/scripts directory contains two Bash scripts that are used to manage and test the xsnap package in the Agoric SDK:

XSnap Documentation

[Edit section]

[Copy link]

References: packages/xsnap/doc

• • •

The additional documentation for the XS Metering and XS Snapshots features of the Agoric SDK is provided in the following files:

Launching and Initializing the Agoric Swingset

[Edit section]

[Copy link]

References: packages/cosmic-swingset/src/chain-main.js, packages/cosmic-swingset/src/launch-chain.js

• • •

The core functionality for launching and initializing the Agoric Swingset is implemented in the …/launch-chain.js file. This file is responsible for setting up the necessary components and storage layers to execute the Swingset kernel.

State Synchronization

[Edit section]

[Copy link]

References: packages/cosmic-swingset/src/export-kernel-db.js, packages/cosmic-swingset/src/import-kernel-db.js

• • •

The export-kernel-db.js file provides functionality for exporting the state of the Agoric Swingset kernel. The main entry point is the initiateSwingStoreExport function, which takes various options such as the state directory, export directory, block height, artifact mode, and export data mode, and returns an object that can be used to control the export process.

Logging and Metrics

[Edit section]

[Copy link]

References: packages/cosmic-swingset/src/anylogger-agoric.js, packages/cosmic-swingset/src/kernel-stats.js

• • •

The anylogger-agoric.js file is responsible for configuring and customizing the behavior of the anylogger library, which is used for logging in the Agoric SDK. The file sets up the logging levels based on the DEBUG environment variable, and provides a custom extension to the anylogger library that adds additional functionality, such as prefixing log messages with timestamps and controlling the logging output based on the selected logging level and the name of the logger.

Simulating the Agoric Cosmos Chain

[Edit section]

[Copy link]

References: packages/cosmic-swingset/src/sim-chain.js, packages/cosmic-swingset/src/sim-params.js

• • •

The main functionality in the file …/sim-chain.js can be summarized as follows:

Zoe Contract Framework

[Edit section]

[Copy link]

References: packages/zoe

• • •

The Zoe contract framework is a secure and flexible platform for building and executing smart contracts within the Agoric SDK. The core functionality of the Zoe contract framework is provided in the …/src directory, which includes the following key components:

Contract Facet API

[Edit section]

[Copy link]

References: packages/zoe/src/contractFacet/types-ambient.d.ts

The Zoe Contract Facet API, accessed via the ZCF interface, is the primary means for smart contract developers to interact with the Zoe state specific to their contract instance. It provides a suite of methods and types that facilitate the creation, management, and execution of smart contracts on the Agoric platform.

Contract Support Tools

[Edit section]

[Copy link]

References: packages/zoe/src/contractSupport/ratio.js, packages/zoe/src/contractSupport/topics.js

• • •

Zoe provides a set of tools within …/contractSupport to assist developers in creating robust smart contracts. One such utility is the manipulation of ratios, which are essential in financial calculations such as scaling amounts or determining exchange rates. Ratios are handled through a Ratio type, which is a record with numerator and denominator fields. Developers can create and validate ratios using makeRatio() and assertIsRatio(), respectively. Operations on ratios include multiplication and division with different rounding modes (floorMultiplyBy(), ceilDivideBy(), etc.), inversion (invertRatio()), and comparison (ratioGTE()).

Zoe Service Utilities

[Edit section]

[Copy link]

References: packages/zoe/src/zoeService/utils.d.ts, packages/zoe/src/zoeService/utils.test-d.ts

• • •

Within the Zoe Service, developers have access to a suite of utility functions and types that streamline the administrative management of smart contracts. These utilities facilitate the upgrade and restart of contract instances, ensuring that developers can maintain and improve their contracts over time.

Contract Upgradability

[Edit section]

[Copy link]

References: packages/zoe/src/contractFacet/types-ambient.d.ts

• • •

Smart contract developers on the Agoric platform can specify and manage upgrade paths for their contracts using the ContractMeta type defined in …/types-ambient.d.ts. This type includes metadata about a contract, such as the shapes of custom terms and private arguments, as well as an upgradability flag. The upgradability feature is crucial for maintaining and improving smart contracts over time without disrupting the contract's operation or the user's experience.

Ratio Math Operations

[Edit section]

[Copy link]

References: packages/zoe/src/contractSupport/ratio.js, packages/zoe/test/unitTests/contractSupport/ratio.test.js

• • •

In the Agoric SDK, ratios are fundamental to financial operations, allowing for the scaling of amounts and representation of exchange rates. The file …/ratio.js introduces the Ratio type, which consists of a numerator and denominator, both of which are Amount objects. Ratios are used extensively to perform arithmetic operations that involve scaling or exchanging digital assets.

Remote Subscriptions

[Edit section]

[Copy link]

References: packages/zoe/src/contractSupport/topics.js

• • •

In Zoe contracts, the management of data streams and event subscriptions is facilitated through the use of topics, which are handled by utilities provided in …/topics.js. Topics allow contracts to manage subscriptions in a way that supports remote participation, enabling subscribers to receive updates or notifications about specific events or state changes within the contract.

Cosmic Proto

[Edit section]

[Copy link]

References: packages/cosmic-proto

• • •

The …/cosmic-proto directory provides protocol buffer (protobuf) definitions and generated code for interacting with the Cosmos ecosystem and its various modules.

Signer Creation and Management

[Edit section]

[Copy link]

References: packages/cosmic-proto/src

• • •

In the Agoric SDK, the creation and management of signers are crucial for enabling transaction signing within the Cosmos ecosystem. Signers are entities that hold the cryptographic keys necessary to authorize and validate transactions. The …/src directory plays a pivotal role in this process by providing the necessary tools and utilities to handle Protobuf data, which is a serialization format widely used in the Cosmos network for encoding structured data.

Broadcasting Messages

[Edit section]

[Copy link]

References: packages/cosmic-proto/src

• • •

To broadcast messages to the Cosmos network, the Agoric SDK leverages the cosmic-proto package, specifically located within …/src. This package includes a suite of tools and utilities designed to facilitate the serialization and transmission of messages in the Cosmos ecosystem, adhering to the Protobuf standards.

Advanced Usage

[Edit section]

[Copy link]

References: packages/cosmic-proto/src

• • •

For developers seeking to leverage the Agoric SDK for more specialized use cases, the Cosmic Proto library offers advanced usage patterns that include the manual construction of a Stargate client with custom proto and amino configurations. This allows for a tailored approach to interacting with the Cosmos ecosystem, providing the flexibility to integrate with custom or non-standard blockchain functionalities.

Inter-Protocol

[Edit section]

[Copy link]

References: packages/inter-protocol

• • •

The …/inter-protocol directory contains the core implementation of the Agoric Inter-Protocol system, which includes the following key components:

Auction System

[Edit section]

[Copy link]

References: packages/inter-protocol/src/auction, packages/inter-protocol/test/auction

• • •

The auction process within the Agoric SDK's Inter-Protocol system is managed by a collection of components that handle offer settlement and auction upgrades. The AuctionBook class, located at …/auctionBook.js, is central to managing the state of ongoing auctions. It is responsible for:

Vault Factory

[Edit section]

[Copy link]

References: packages/inter-protocol/src/vaultFactory, packages/inter-protocol/test/vaultFactory, packages/inter-protocol/test/vaultFactory/director-allMgrsDo.test.js

• • •

The VaultFactory contract, established through the vaultFactory.js file, orchestrates the creation and management of vaults which are pivotal for borrowing and repaying the minted currency using collateral assets. The contract leverages a VaultDirector class, defined in vaultDirector.js, to oversee the addition of new vault types and the coordination of various vault managers. The VaultDirector is equipped with a machine interface that facilitates the creation of vaults, collection of fees, and scheduling of tasks like liquidation and price locking.

Contract Support

[Edit section]

[Copy link]

References: packages/inter-protocol/src/contractSupport.js

In the Agoric Inter-Protocol system, developers are equipped with a suite of utility functions found in …/contractSupport.js that streamline the development and operation of smart contracts. These utilities address common contract-related tasks, ensuring that developers can focus on the unique aspects of their smart contract logic.

Interest Calculation

[Edit section]

[Copy link]

References: packages/inter-protocol/src/interest.js, packages/inter-protocol/src/vaultFactory/vaultManager.js

• • •

Within the vault system of the Agoric SDK, interest on loans and debt is managed through a set of functions and methods designed to calculate and accrue interest over time. The primary utility for these calculations is found in …/interest.js, which includes the makeInterestCalculator function. This function is pivotal in setting up the interest calculation mechanism, allowing for the determination of new debt and interest amounts based on defined charging and reporting periods.

Testing and Simulation

[Edit section]

[Copy link]

References: packages/inter-protocol/test

• • •

In the Agoric SDK, the auction system is tested through a series of scenarios that validate the auction logic, ensuring that bids are sorted and settled correctly. Key functions like amountsToSettle are scrutinized to confirm accurate calculations of proceeds and collateral targets under various auction conditions. These tests are located in …/auctionMath.test.js and …/sortedOffers.test.js.

Swingset Runner

[Edit section]

[Copy link]

References: packages/swingset-runner

The …/swingset-runner directory contains the implementation of the Swingset Runner, a key component of the Agoric SDK. The Swingset Runner is responsible for managing the execution of the Agoric Swingset, which is the core runtime for the Agoric platform. The directory includes various files that handle different aspects of the Swingset Runner, such as:

Configuration Options

[Edit section]

[Copy link]

References: packages/swingset-runner/src/main.js

• • •

The swingset-runner provides a set of flags that modify its behavior, enabling developers to tailor the execution environment to their needs. Key flags include:

Vats

[Edit section]

[Copy link]

References: packages/vats

• • •

The …/vats directory contains the core functionality for bootstrapping, managing, and upgrading various aspects of the Agoric platform. This includes the setup of the bootstrap vat, the management of client bundles and provisioning, the configuration of the chain storage and communication, and the implementation of various utility functions and data structures used throughout the platform.

Core Vat Functionality

[Edit section]

[Copy link]

References: packages/vats/src/core

The Agoric SDK's vat system is architected to support the creation, management, and execution of vats, which are secure, isolated virtual machines within the Agoric environment. The bootstrapping process is a critical phase where the system's initial state is set up, and the vat infrastructure is wired together to ensure proper communication and operation.

Local Chain Interface

[Edit section]

[Copy link]

References: packages/vats/src/localchain.js

Interacting with a local chain in the Agoric SDK is facilitated through two primary interfaces: LocalChainAccountI and LocalChainI, which are instantiated using the prepareLocalChainTools factory function. These interfaces provide developers with a set of methods to manage accounts and perform queries on the local chain.

Virtual Purse

[Edit section]

[Copy link]

References: packages/vats/src/virtual-purse.js

• • •

The makeVirtualPurseKitIKit() function is pivotal in establishing the interfaces for a virtual purse within the Agoric SDK, defining the expected behavior and capabilities of a virtual purse. It outlines methods for retrieving the brand of the assets, current balance, and a notifier for balance updates. Additionally, it specifies interfaces for depositing and withdrawing assets, as well as for recovery operations.

Proposal Management

[Edit section]

[Copy link]

References: packages/vats/src/proposals/upgrade-provisionPool-proposal.js

• • •

In the Agoric SDK, the management of upgrade proposals is handled through a structured approach, focusing on the careful handling of private arguments and the systematic processing of proposal data. The …/upgrade-provisionPool-proposal.js file encapsulates this functionality, primarily through the upgradeProvisionPool function.

Testing and Simulation Tools

[Edit section]

[Copy link]

References: packages/vats/tools/fake-bridge.js

In the Agoric SDK, the …/fake-bridge.js plays a crucial role in the testing and simulation of bridge functionalities, which are pivotal for interactions with various blockchain protocols and services. The tool provides a suite of fake bridge managers that mimic the behavior of actual bridges in a controlled environment, enabling developers to validate logic and workflows without the need for a live blockchain connection.

IBC Functionality

[Edit section]

[Copy link]

References: packages/vats/src/types.d.ts

• • •

Inter-Blockchain Communication (IBC) is a critical protocol within the Agoric SDK, enabling secure and efficient cross-chain interactions. The …/types.d.ts file outlines the types and interfaces that facilitate the handling of IBC-related functionality.

Network and Vow Utilities

[Edit section]

[Copy link]

References: packages/vats/src/vat-network.js, packages/vats/test/network.test.js

Within the Agoric SDK, the management of network-related functionality is centralized through the buildRootObject function located in …/vat-network.js. This function orchestrates the initialization of network powers and vow tools, which are essential for enabling secure and efficient communication within the Agoric platform. Here's an overview of the key components and their roles:

ERTP

[Edit section]

[Copy link]

References: packages/ERTP

• • •

The Agoric ERTP (Electronic Rights Transfer Protocol) system is responsible for managing the transfer and representation of digital assets in the Agoric platform. The core functionality of the ERTP system is implemented in the …/ERTP directory.

Type Guards and Validation

[Edit section]

[Copy link]

References: packages/ERTP/src/typeGuards.js

• • •

In the Agoric SDK, the …/typeGuards.js file plays a crucial role in maintaining the integrity of digital assets by providing a suite of type guards and shape definitions. These tools are essential for validating the structure and consistency of various ERTP-related objects, ensuring that they conform to expected patterns before they are processed or manipulated within the system.

Amount Patterns

[Edit section]

[Copy link]

References: packages/ERTP/src/typeGuards.js

• • •

In the ERTP system, asset amounts are represented using structured patterns that enable matching and validation during various operations. The …/typeGuards.js file plays a crucial role in this process by providing shapes and type guard functions that ensure the integrity of asset amounts.

Orchestration

[Edit section]

[Copy link]

References: packages/orchestration

The …/orchestration directory provides the core functionality for the orchestration system in the Agoric SDK, enabling the management of assets and services across different blockchain networks.

Chain and Asset Management

[Edit section]

[Copy link]

References: packages/orchestration/src/chain-info.js, packages/orchestration/src/exos/chain-hub.js, packages/orchestration/test/assets.fixture.ts

• • •

The orchestration system within the Agoric SDK provides a structured approach to managing chain and asset information, crucial for the operation of Cosmos-based assets and the facilitation of IBC token transfers. The system utilizes components such as ChainHub and NameHub to enhance asset management capabilities across different blockchain networks.

Contract Orchestration and Setup

[Edit section]

[Copy link]

References: packages/orchestration/src/examples/auto-stake-it.flows.js, packages/orchestration/src/examples/basic-flows.flows.js

• • •

In the orchestration of contracts within the Agoric SDK, the makeAccounts function plays a pivotal role, particularly in the context of automatic staking scenarios. This function is designed to streamline the setup of accounts and portfolio holders across multiple chains. It is utilized in …/auto-stake-it.flows.js to create a local account on the Agoric chain and a corresponding staking account on a remote chain. The function is configured to automatically delegate any incoming tokens to a pre-specified validator through the MakeStakingTap.

Interchain Communication

[Edit section]

[Copy link]

References: packages/orchestration/src/exos/ibc-packet.js, packages/orchestration/src/exos/packet-tools.js

Interchain communication within the Agoric SDK leverages the Inter-Blockchain Communication (IBC) protocol to manage packet transfers and acknowledgments across different blockchain networks. The orchestration layer provides developers with tools to monitor packet transfers, match packets to specific patterns, and handle acknowledgments efficiently.

Orchestration Account Functionality

[Edit section]

[Copy link]

References: packages/orchestration/src/exos/cosmos-orchestration-account.js, packages/orchestration/test/exos/cosmos-orchestration-account.test.ts

• • •

The CosmosOrchestrationAccount class in …/cosmos-orchestration-account.js serves as a comprehensive interface for managing Cosmos-based staking accounts. It encapsulates a variety of staking operations such as delegation, redelegation, and reward withdrawal, as well as the ability to send tokens and initiate IBC transfers. The class provides methods like delegate(), redelegate(), withdrawReward(), withdrawRewards(), and undelegate() to interact with the staking process directly. Additionally, it includes send() and transfer() methods for token transactions within and across chains, respectively.

Orchestration Utilities and Tools

[Edit section]

[Copy link]

References: packages/orchestration/src/utils/time.js, packages/orchestration/src/utils/zoe-tools.js, packages/orchestration/src/utils/address.js

In the orchestration system of the Agoric SDK, a set of utilities and tools are provided to facilitate various operations such as time management, asset transfers, and address handling. The …/time.js file includes a makeTimestampHelper function that leverages a TimerService to calculate future timestamps in nanoseconds, which are crucial for setting timeouts in message transfers and other time-sensitive tasks.

Inter-Chain Account Management

[Edit section]

[Copy link]

References: packages/orchestration/src/exos/ica-account-kit.js, packages/orchestration/src/cosmos-api.ts

• • •

Inter-Chain Account Management within the Agoric SDK is facilitated by the IcaAccountKit class, which is part of the orchestration package located at …/ica-account-kit.js. This class provides a set of functionalities crucial for the operation of Inter-Chain Accounts (ICAs), which are accounts that exist on a remote blockchain and can be controlled from a different chain.

Cosmos Interchain Service

[Edit section]

[Copy link]

References: packages/orchestration/test/cosmos-interchain-service.test.ts

• • •

The CosmosInterchainService module manages Interchain Queries (ICQ) and Interchain Accounts (ICA) connections. Key functionalities include:

Smart Wallet

[Edit section]

[Copy link]

References: packages/smart-wallet

• • •

The Agoric Smart Wallet system is a core component of the Agoric platform, responsible for managing user wallets, handling offers and invitations, and providing a durable and reliable interface for interacting with the Agoric ecosystem.

Deployment

[Edit section]

[Copy link]

References: packages/deployment

• • •

The …/deployment directory contains the necessary scripts, configurations, and tools for deploying and managing the Agoric blockchain network. The key functionality includes:

Agoric CLI

[Edit section]

[Copy link]

References: packages/agoric-cli

• • •

The Agoric CLI is the main command-line interface tool for interacting with the Agoric blockchain and ecosystem. It provides a wide range of functionality, including:

Command-Line Interface Utilities

[Edit section]

[Copy link]

References: packages/agoric-cli/src/init.js, packages/agoric-cli/src/helpers.js

• • •

The Agoric CLI provides a suite of utilities designed to streamline the process of initializing and managing Agoric dapp projects. A key utility is the initMain() function from …/init.js, which automates the setup of a new dapp by cloning a template repository, re-initializing Git history, and preparing the project for development. This function simplifies the process of starting a new dapp project by handling the intricacies of repository setup and configuration.

Getting Started with Agoric

[Edit section]

[Copy link]

References: packages/agoric-cli/tools/getting-started.js

• • •

To begin Agoric development, the Agoric CLI provides a streamlined process that guides developers through setting up a new project, installing dependencies, and running a local test environment. The entry point for this workflow is the gettingStartedWorkflowTest() function, which automates the setup and testing of a new Agoric dapp.

Base Zone

[Edit section]

[Copy link]

References: packages/base-zone

• • •

The @agoric/base-zone library provides the core functionality for creating and managing "Zones" in the Agoric SDK. Zones are isolated execution environments that can be used to safely execute untrusted code.

XSnap

[Edit section]

[Copy link]

References: packages/xsnap

• • •

The XSnap (Extensible Secure Snapshots) package in the Agoric SDK provides a secure JavaScript runtime and a comprehensive testing framework for Agoric SDK components. The key functionality of the XSnap package includes:

XSnap API

[Edit section]

[Copy link]

References: packages/xsnap/api.js

• • •

Interacting with the XSnap virtual machine is facilitated by the XSnap API, which is crucial for script execution within a secure and isolated environment. The API is designed to manage computational resource metering and handle snapshots for maintaining persistent state across sessions.

XSnap Runtime

[Edit section]

[Copy link]

References: packages/xsnap/src/xsnap.js

• • •

The xsnap() function serves as the gateway to the XSnap virtual machine, enabling the execution of scripts and interaction with the worker process. It accepts an XSnapOptions object, which configures the environment and behavior of the XSnap instance. Upon invocation, xsnap() returns an interface with methods tailored for communication and control of the XSnap worker.

XSnap REPL

[Edit section]

[Copy link]

References: packages/xsnap/src/xsrepl.js

• • •

The XSnap provides an interactive environment through its REPL, allowing users to execute XS code in real-time. This feature is particularly useful for developers who need to test and debug their code in a controlled setting. The REPL is powered by the xsnap() function, which initializes the XS virtual machine instance, ensuring that each session starts with a clean slate.

XSnap Test Suite

[Edit section]

[Copy link]

References: packages/xsnap/test/xs-limits.test.js

• • •

The xsnap module is equipped with a test suite located in …/xs-limits.test.js, which is designed to validate the virtual machine's behavior under various resource limit conditions. The suite includes tests that simulate scenarios where the system resources are pushed to their limits, ensuring that xsnap responds appropriately.

Cosmic Swingset

[Edit section]

[Copy link]

References: packages/cosmic-swingset

• • •

The …/cosmic-swingset directory contains the core implementation of the Agoric Cosmos Swingset, which is the central component of the Agoric blockchain platform. The key functionality in this directory includes:

Swingset Launch Process

[Edit section]

[Copy link]

References: packages/cosmic-swingset/src/launch-chain.js

• • •

Launching a new Agoric swingset instance begins with the buildSwingset() function, which sets up the initial conditions for the SwingSet kernel. This includes the creation of essential devices such as mailbox, timer, and bridge, and initializing the SwingSet configuration. The function also prepares the system for upgrades by handling core proposals, which are crucial for the evolution of the SwingSet.

Swingset Device Endowments

[Edit section]

[Copy link]

References: packages/cosmic-swingset/src/launch-chain.js

• • •

Within the SwingSet environment of the Agoric blockchain platform, device endowments play a crucial role in the system's operation. The launch-chain.js file, specifically within the buildSwingset() function, sets up these device endowments, which include essential devices like the mailbox, timer, and notably, the bridgeDevice.

Swingset Export Callback

[Edit section]

[Copy link]

References: packages/cosmic-swingset/src/launch-chain.js

• • •

In the …/launch-chain.js, the state of the Agoric SwingSet is managed to ensure consistency and integrity during the export process. The swingStoreExportCallback function plays a pivotal role in this process. It is invoked to handle the export of the kernel's state, which is crucial for maintaining a consistent blockchain state across restarts or upgrades. The callback function is designed to work in conjunction with flags that signal the appropriate times to capture the state, such as before a block commit.

Swingset Bridge Outbound

[Edit section]

[Copy link]

References: packages/cosmic-swingset/src/launch-chain.js

• • •

The buildSwingset function within …/launch-chain.js is integral to the setup of the Agoric SwingSet kernel. One of its parameters, bridgeOutbound, serves as a crucial link for outbound communication from the SwingSet to the external world, particularly the Cosmos blockchain. This parameter is a function that is called whenever the SwingSet kernel needs to send a message to the outside, such as to other Cosmos zones or to off-chain components.