This page lists words, expressions, or concepts used by the Agoric technology stack.
Human-readable name of a kind of rights. The alleged name should not be trusted as an accurate depiction, since it is provided by the maker of the mint and could be deceptive, but is useful for debugging and double-checking.
The AllegedName must be a string.
AmountMath executes the logic of how amounts are changed when digital assets are merged, separated,
or otherwise manipulated. For example, a deposit of 2 bucks into a purse that already has 3 bucks
gives a new balance of 5 bucks. An empty purse has 0 bucks. AmountMath relies heavily on polymorphic
MathHelpers, which manipulate an
amount's value or unbranded portion.
Standard natural number operations cannot be used on values, since they can be an array or object.
See the ERTP Guide's AmountMath section
and the ERTP API's AmountMath section for more information.
Amounts are the canonical description of tradable goods. They are manipulated by issuers and mints, and represent the goods and currency carried by purses and payments. They represent things like currency, stock, and the abstract right to participate in a particular exchange.
Identifies the kind of issuer, such as "quatloos", "moola", etc. Brands are one of the two elements that make up an amount. See the ERTP Guide's Brand section and the ERTP API's Brand section for more information.
A passable is something that can be marshalled. A comparable is a passable whose leaves contain no promises. Two comparables can be synchronously compared for structural equivalence.
# Contract and Contract Instance
In Agoric documentation, contract usually refers to a contract's source code that defines how the contract works, which is installed on Zoe. A contract is instantiated to create contract instances, which are run on Zoe and are the active execution of the contract code.
For example, a realtor has a standard house selling agreement. The contract is the code defining how that agreement works. When the realtor has a new house to sell, they instantiate a new instance of their standard contract for that specific property. If they have ten houses for sale, they have ten different contract instances.
It uses object capabilities to enforce access control. Instead of having to prove ownership of a corresponding private key, if your program has a reference to an object, it can call methods on that object. If it doesn't have a reference, it can't. For more on object capabilities, see this post.
Values are the part of an amount that describe the value of something that can be owned or shared: How much, how many, or a description of a unique asset, such as Pixel(3,2), $3, or ‘Right to occupy on Tuesdays’. Fungible values are usually represented by natural numbers. Other values may be represented as strings naming a particular right, or an arbitrary object representing the rights at issue. The latter two examples are usually non-fungible assets. Values must be Comparable.
See the ERTP Guide's Value section for more information.
A fungible asset is one where all exemplars of the asset are interchangable. For example, if you have 100 one dollar bills and need to pay someone five dollars, it does not matter which five one dollar bills you use. Also see non-fungible.
For example, Zoe often uses
offerHandle to refer to offers. Zoe contracts can use an offer's
offerHandle as the key for requesting the current allocation of an offer or reallocating the offer's assets.
Issuers are linked to a single mint and vice versa, so each issuer works with one and only one asset type, such as only working with quatloos or only working with moola. They can create empty purses and payments for their asset type, but cannot mint new amounts.
Issuers can also transform payments of their asset type (splitting, combining, burning, and exclusively claiming payments). An issuer from a trusted source can determine if an untrusted payment of its asset type is valid.
MathHelpers are methods for performing arithmetic operations on an amount's value. AmountMath uses MathHelpers to do value arithmetic, after which it brands the result to create a new amount. For more information, see the MathHelpers ERTP Guide section and the MathHelpers ERTP API section.
In ERTP, mints create digital assets and are the only objects with the authority to do so. Access to a mint gives you the power to create more digital assets of its type at will. Mints can only create one type of asset.
Mints are issuer's admin facets, and there is a one-to-one relationship between an issuer and its mint.
A non-fungible asset is one where each incidence of the asset has unique individual properties and is not interchangable with another incidence. For example, if your asset is show tickets, it matters to the buyer what the date and time of the show is, which row the seat is in, and where in the row the seat is (and likely other factors as well). You can't just give them any ticket in your supply, as they are not interchangable (and may even have different prices). See also fungible.
You can track updates to contract state using a notifier. The notifier provides a stream of updates describing changes to the state of an offer.
See more: Notifier
# Object Capabilities
Objects have state, behavior, and references. Lets say Object A has references to Objects B and C, while B and C do not have references to each other. Thus, A can communicate with B and C, and B and C cannot commuicate with each other. There is an effective zero-cost firewall between B and C.
An object capability system constrains how references are obtained. You can't get one just by knowing the name of a global variable or a public class. You can get a reference in only three ways.
- Creation: Functions that create objects get a reference to them.
- Construction: Constuctors can endow their constructed objects with references, including inherited references.
- A has references to B and C.
- B and C do not have references to each other
- A sends B a reference to C.
- B now has a reference to C and can communicate with C.
If references can only be obtained by creation, construction, or introduction, you may have a safe system. If they can be obtained in any other way, your system is unsafe.
For more information, see Douglas Crockford on Object Capabilities.
Payments hold amounts of certain assets issued by Mints. Specifically amounts that are in transit from one party to another. Amounts from payments can be deposited in purses, but otherwise, the entire amount is available when the payment is transferred. Payments can be converted to Purses. All contents of a purse must be of the same brand.
A local version of a remote object that serves as a proxy for the remote object.
obj is a presence of a remote object, you can send messages to the remote object by using
Purses hold amounts of certain mint issued assets. Specifically amounts that are stationary. Purses can transfer part of their held balance to a payment, which is usually used to transfer value. A purse's contents are all of the same brand.
A vat runs a single event loop.
A physical machine can run one or several vats. A blockchain can run one or several communicating vats.
Different vats can communicate by sending asynchronous messages to other vats.
A vat is the moral equivalent of a Unix Process.