Name Services
The Agoric chain has a few name services:
agoricNames
for well-known names controlled by governancenamesByAddress
- a namespace for each provisioned accountboard
- to map objects to arbitrary names and back
agoricNames / agoricNamesAdmin - well known names
Well-known names are chosen by BLD staker governance.
To look up well-known objects, such as the BLD brand:
const brandHub = E(agoricNames).lookup('brand');
const bldBrand = await E(brandHub).lookup('BLD');
or, equivalently:
const bldBrand = await E(agoricNames).lookup('brand', 'BLD');
agoricNames
is a NameHub. In general, E(hub).lookup(key1, key2, ...rest)
is equivalent to E(E(hub).lookup(key1)).lookup(key2, ...rest)
. The NameHub interface also includes Map
-like methods has
, entries
, keys
, and values
.
The keys of agoricNames
include:
brand
- IST, BLD, Invitation (Zoe invitation brand), timer (a TimerBrand, not an ERTP brand)issuer
- IST, BLD, Invitation, ...vbankAsset
- IST, BLD, USDC, ATOM, ... - including info about corresponding cosmos denomoracleBrand
- USD, ATOMinstallation
- psm, reserve, priceAuthority, ... (see deployed contracts)instance
- reserve, one for each psm, one for each priceAuthority, ... (see deployed contracts)
Adding or updating an entry requires access to the corresponding NameAdmin facet: agoricNamesAdmin
or one of its descendants - most likely as part of permissioned contract deployment. For example:
const { instance } = await E(zoe).startInstance(lemonadeStand);
const { brands: { Lemonade: lemonadeBrand } } = await E(zoe).getTerms(instance);
const brandAdmin = E(agoricNamesAdmin).lookupAdmin('brand');
await E(brandAdmin).update('Lemonade', lemonadeBrand);
agoricNames in vstorage
The NameAdmin
interface has an onUpdate
method for registering a callback. This is used to reflect the brand entries, that is: E(E(agoricNames).lookup('brand')).entries()
into vstorage at published.agoricNames.brand
each time they change. The entries for instance
and the other keys of agoricNames
are likewise reflected under published.agoricNames
. See marshalling amounts and instance for details on the format of the data stored in vstorage.
namesByAddress / namesByAddressAdmin, and depositFacet - per account namespace
Each time a smart wallet is provisioned for address a
, a NameHub / NameAdmin pair is installed at E(namesByAddress).lookup(a)
and E(namesByAddressAdmin).lookupAdmin(a)
. Also, a deposit facet is installed at E(namesByAddress).lookup(a, 'depositFacet')
so that you can send a payment, such as an invitation, to such a smart wallet using the receive
method of the deposit facet:
const bobAddress = 'agoric1...';
const anInvitationPayment = await zcf.makeInvitation(...);
const bobDepositFacet = E(namesByAddress).lookup(bobAddress, 'depositFacet');
const amtReceived = await E(bobDepositFacet).receive(anInvitationPayment);
Normally, calling E(nameHub).lookup(k)
before calling E(nameAdmin).update(k, v)
throws. But the NameAdmin
interface also includes a E(nameAdmin).reserve(k)
method so that E(nameHub).lookup(k)
will then return promise that waits for a call to E(nameAdmin).update(k, v)
and then resolves to v
. This lets those authorized to use namesByAddressAdmin
to send invitations even if a smart wallet has not yet been provisioned:
const bobAddress = 'agoric1...';
const anInvitationPayment = await zcf.makeInvitation(...);
await E(namesByAddressAdmin).reserve(bobAddress);
await E(E(namesByAddressAdmin).lookupAdmin(bobAddress)).reserve('depositFacet');
const bobDepositFacet = E(namesByAddress).lookup(bobAddress, 'depositFacet');
const receievedP = E(bobDepositFacet).receive(anInvitationPayment);
// waits for bob to provision a smart wallet
const amtReceived = await receivedP;
The Board - publishing under arbitrary names
If we have an object such as a brand or a contract instance, and we need a name / id for it, but we don't much care what the name is, we can use the board:
const { instance } = await E(zoe).startInstance(...);
const instanceId = await E(board).getId(instance);
We can then save the id in a file or send it in email to someone else, and they can look up the object:
const instance = await E(board).getValue('board023423')
See also: marshalling amounts and instance for details on using board ids to refer to objects from structures stored in vstorage,