Agoric Wallet

This page documents the Agoric Wallet, including its use of petnames and its place in the Agoric Platform architecture. See also tour of the Wallet UI, Wallet API reference.

Wallet and Agoric Architecture

The Agoric System consists of interconnected Agoric VMs. Some are on the blockchain, some are local. The Wallet is a user's trusted agent for interacting with the Agoric VM network.

We also have Dapps (Decentralized applications), which are Web UIs that interact with Agoric VMs. Dapps have their own agendas...which may include wanting to steal assets from Wallets.

An Ag-Solo is a single off-chain Agoric VM. They have their own UI and way of communicating with chains (including multiple chains and network connections). They serve as entry points into the Agoric System.

When you run agoric start, you get a private ag-solo that runs your private wallet. The wallet is a user's trusted agent. It lets you enable or disable inbound connections from Dapps and approve or decline proposals from those Dapps you enabled. The Wallet is visible when you run agoric open.

The way this works in the Wallet's UI is via the proposals that are part of a Zoe offer; a Dapp says it wants the user to offer something. The wallet expresses that request/offer in a popup, and the user indicates if they want to enact or decline it.

Dapps can be anywhere; they can be web apps interacting with wallets, usually because they want your money and/or help you exchange something with someone else. They may even want to give you something for free. But a Dapp's main use is exchanging something on the chain, in addition to controlling what access they have and managing the proposals.

Wallet Bridge Protocol

The wallet bridge is a web page with direct access to an Agoric Wallet. It provides the Dapp with a facet of an API. Dapps never talk directly to a Wallet, only to this bridge that knows where the Wallet is. So, for example, if a Dapp is running in your browser at https://treasury.agoric.app/ and the Wallet is running locally, they don't communicate directly. They do so by sending JSON-encoded messages through the wallet bridge.

Petnames and Paths

Before we get into the Wallet itself, you should know about petnames, which are your personal names for objects. No one else can see or modify a petname without your permission. You can think of them as your phone's contacts list. The actual phone number is what your phone uses to call someone, but for you to more easily tell who a number is associated with, you've assigned a petname to it, such as Mom, Grandpa, Kate S., etc. Different people can have different petnames for different objects. For example, the same person is "Mom" to you, "Mimi" to her granddaughter, and "Mrs. Watson" to many others.

Your Wallet manages your petnames for Dapps, asset types, issuers, etc.

The wallet bridge protocol is migrating petnames to paths. All former petnames are now either a path or still a plain string. A path is an array of strings whose first element is the user's petname for a Dapp. Dapps must be able to work with either plain string petnames or array-of-strings paths.

They can do this via JSON.stringify(petnameOrPath) before using the petnameOrPath in a programmatic string-only context (such as a key in a Map or Set, or an HTML element's attribute value, such as an ID). When displaying a path to users, you should join its elements with '.'. If in a UI, you should ideally color the first element differently from the dots and other elements. The first element is a trusted, user-assigned petname for the Dapp, while the other elements were automatically generated by the Dapp or wallet. Thus, they have no special relationship to the user.

Dapp-Specific Path Suggestions

Your Dapp should suggest names for any Installations, Instances, or Issuers wallet users will interact with. When a wallet accepts them, it returns them to the Dapp as paths (arrays of strings) that start with the user's petname for the Dapp.

For example, here are the messages that the Fungible Faucet Dapp sends over the wallet bridge:

// Our issuer will default to something like `FungibleFaucet.Installation`.
walletSend({
  type: 'walletSuggestInstallation',
  petname: 'Installation',
  boardId: INSTALLATION_BOARD_ID
});
// Our issuer will default to something like `FungibleFaucet.Instance`.
walletSend({
  type: 'walletSuggestInstance',
  petname: 'Instance',
  boardId: INSTANCE_BOARD_ID
});
// Our issuer will default to something like `FungibleFaucet.Token`.
walletSend({
  type: 'walletSuggestIssuer',
  petname: 'Token',
  boardId: TOKEN_ISSUER_BOARD_ID
});

The Agoric Board

Several Wallet API methods use Agoric's Board, a key-value "bulletin board" that lets users make data generally available. Users can obtain an Id by posting a value and others can get the value just by knowing the Id. You can make Id(s) known by any communication method you like; private email, an email blast to a mailing list or many individuals, buying an ad on a website, tv program, or newspaper, listing it on your website, etc.

const depositFacet = E(board).getValue(aliceQuatloosDepositFacetId);
await E(depositFacet).receive(myQuatloosPayment);

To get an object, such as a depositFacet, using the Board, first you have to be told what Board Id is associated with it. Using the getValue() method, you retrieve the reference to the depositFacet and can deposit payments into it.