# Agoric Dapp

This is a generic guide to Agoric Dapp projects

A Dapp is a distributed application which typically has a browser-based user interface, a public API server, and a contract running on the Agoric blockchain.

# Using a Dapp

If you have installed the Agoric CLI and you just want to try running a Dapp locally (on a simulated Agoric VM, not an actual public chain), you can:

# Clone a local version of the dapp. Here we chose the encouragement dapp
git clone https://github.com/Agoric/dapp-encouragement.git
cd dapp-encouragement
# Install the project dependencies
agoric install
# Start the Agoric VM
agoric start --reset

Leave this command running (it is your simulated environment). Then, in a separate terminal:

# Start the user interface
cd ui && yarn start

Then in a third terminal, deploy the contract and API to the VM.

# Deploy a new instance of the contract to the VM
agoric deploy contract/deploy.js
# Reset the VM's API server
agoric deploy api/deploy.js

You can then navigate to http://localhost:3000 to view your Dapp.

# Modifying this Dapp

In the Agoric system, components are written in Javascript.

# Components

The following are the important directories in an Agoric Dapp project:

  • contract define and deploy the on-chain contract
  • api define and deploy the chain-connected server's /api HTTP endpoint
  • ui the browser user interface that connects between the user's personal wallet and the API server

Other files and directories in this toplevel folder should not typically be modified.

# Contract directory

In the contract directory, you can find the following files to edit:

  • init contract initialization modules, starting with init/custom-deploy.js
  • src contract source code, starting with src/contract.js

Other files and folders that you don't typically need to edit:

  • deploy.js generic Agoric contract deployment script
  • lib library modules provided by Agoric and used by the contract


In the api directory, you can find the following files to edit:

  • src /api endpoint handler, starting with src/handler.js

Other files and folders that you don't typicaly need to edit:

  • deploy.js generic Agoric API handler deployment script

# UI

The ui directory is almost completely under your control. The only files and folders that you don't typically need to edit:

  • public/lib Agoric UI library
  • public/conf configuration files that are generated by the contract/deploy.js script

# More information

You can learn more about the Agoric smart contract platform and how to create Agoric Dapps.