# Agoric Dapps

This is a generic guide to Agoric Dapp projects

A dapp is a decentralized 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 want to try running a dapp locally on a simulated Agoric VM (i.e., it won't be running on an actual public chain), do the following:

  1. Checkout the latest beta release of the SDK.

    cd agoric-sdk
    git checkout beta
    yarn && yarn build
    
  2. Run agoric init to make a new local copy of a dapp template.

    # Here we chose the Fungible Faucet Dapp.
    # You can replace `my-fungible-faucet` with a name of your choice.
    agoric init --dapp-template dapp-fungible-faucet --dapp-branch beta my-fungible-faucet
    cd my-fungible-faucet
    # Install the project dependencies
    agoric install
    # Start the Agoric VM
    agoric start --reset
    
  3. Leave this command running (it is your simulated environment).

  4. In a separate 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
    
  5. In a third terminal, run the following.

    # Start the user interface
    cd ui && yarn start
    
  6. You can now navigate to http://localhost:3000 (opens new window) 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/ defines the on-chain smart contract.
  • api/ defines the chain-connected server's /api HTTP endpoint.
  • ui/ defines the browser user interface connecting users' personal wallets and the API server.

Other files and directories in this top-level folder should not typically be modified.

# Contract Directory

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

  • src directory: Contract source code, starting with src/contract.js.

There are also files and folders that you usually shouldn't edit:

  • deploy.js: Generic Agoric contract deployment script.

# API Directory

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

  • src directory: Handler for API HTTP endpoints, starting with src/handler.js.

There are also files and folders that you usually shouldn't edit:

  • deploy.js: Generic Agoric API handler deployment script.

# UI Directory

The ui directory is almost completely under your control. The only files and folders that you usually shouldn't edit are:

  • public/lib: The 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 (opens new window).