API documentation of Agoric SDK / Exports / @agoric/ertp

Module: @agoric/ertp

Table of contents

Interfaces

• IssuerRecord

Type Aliases

• IssuerOptionsRecord

Variables

• AmountMath
• AmountShape
• AssetKind
• AssetKindShape
• BrandI
• BrandShape
• DepositFacetShape
• DisplayInfoShape
• IssuerKitShape
• IssuerShape
• MAX_ABSOLUTE_DECIMAL_PLACES
• MintShape
• NotifierShape
• PaymentShape
• PurseShape
• RatioShape

Functions

• assertAssetKind
• assertValueGetHelpers
• getAssetKind
• hasIssuer
• isCopyBagValue
• isCopySetValue
• isNatValue
• isSetValue
• makeDurableIssuerKit
• makeIssuerInterfaces
• makeIssuerKit
• prepareIssuerKit
• upgradeIssuerKit

Type Aliases

IssuerOptionsRecord

Ƭ IssuerOptionsRecord: Partial<{ elementShape: Pattern ; recoverySetsOption: RecoverySetsOption }>

Defined in

issuerKit.js:164

Variables

AmountMath

• Const AmountMath: Object

Logic for manipulating amounts.

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 can be used to represent things like currency, stock, and the abstract right to participate in a particular exchange.

Type declaration

Name	Type	Description
add	<K>(leftAmount: Amount<K>, rightAmount: Amount<K>, brand?: Brand<K>) => Amount<K>	-
coerce	<K>(brand: Brand<K>, allegedAmount: Amount<K>) => Amount<K>	-
getValue	<K>(brand: Brand<K>, amount: Amount<K>) => AssetValueForKind<K>	-
isEmpty	(amount: Amount<AssetKind>, brand?: Brand<AssetKind>) => boolean	-
isEqual	<K>(leftAmount: Amount<K>, rightAmount: Amount<K>, brand?: Brand<K>) => boolean	-
isGTE	<K>(leftAmount: Amount<K>, rightAmount: Amount<K>, brand?: Brand<K>) => boolean	Returns true if the leftAmount is greater than or equal to the rightAmount. The notion of "greater than or equal to" depends on the kind of amount, as defined by the MathHelpers. For example, whether rectangle A is greater than rectangle B depends on whether rectangle A includes rectangle B as defined by the logic in MathHelpers.
make	<K>(brand: Brand<K>, allegedValue: AssetValueForKind<K>) => Amount<K>	-
makeEmpty	(brand: Brand<AssetKind>) => Amount<"nat"><K>(brand: Brand<AssetKind>, assetKind: K) => Amount<K>	-
makeEmptyFromAmount	<K>(amount: Amount<K>) => Amount<K>	-
max	<K>(x: Amount<K>, y: Amount<K>, brand?: Brand<K>) => Amount<K>	-
min	<K>(x: Amount<K>, y: Amount<K>, brand?: Brand<K>) => Amount<K>	-
subtract	<K>(leftAmount: Amount<K>, rightAmount: Amount<K>, brand?: Brand<K>) => Amount<K>	-

Defined in

amountMath.js:198

---

AmountShape

• Const AmountShape: Object

Type declaration

Name	Type
brand	Matcher
value	Matcher

Defined in

typeGuards.js:74

---

AssetKind

• Const AssetKind: Object

Constants for the kinds of assets we support.

Type declaration

Name	Type
COPY_BAG	"copyBag"
COPY_SET	"copySet"
NAT	"nat"
SET	"set"

Defined in

amountMath.js:21

---

AssetKindShape

• Const AssetKindShape: Matcher

Defined in

typeGuards.js:126

---

BrandI

• Const BrandI: InterfaceGuard<{ getAllegedName: MethodGuard ; getAmountShape: MethodGuard ; getDisplayInfo: MethodGuard ; isMyIssuer: MethodGuard }>

Defined in

typeGuards.js:153

---

BrandShape

• Const BrandShape: Matcher

Defined in

typeGuards.js:5

---

DepositFacetShape

• Const DepositFacetShape: Matcher

Defined in

typeGuards.js:9

---

DisplayInfoShape

• Const DisplayInfoShape: Matcher

Defined in

typeGuards.js:128

---

IssuerKitShape

• Const IssuerKitShape: Object

Type declaration

Name	Type
brand	Matcher
displayInfo	Matcher
issuer	Matcher
mint	Matcher
mintRecoveryPurse	Matcher

Defined in

typeGuards.js:143

---

IssuerShape

• Const IssuerShape: Matcher

Defined in

typeGuards.js:6

---

MAX_ABSOLUTE_DECIMAL_PLACES

• Const MAX_ABSOLUTE_DECIMAL_PLACES: 100

Defined in

typeGuards.js:124

---

MintShape

• Const MintShape: Matcher

Defined in

typeGuards.js:11

---

NotifierShape

• Const NotifierShape: Matcher

Defined in

typeGuards.js:10

---

PaymentShape

• Const PaymentShape: Matcher

Defined in

typeGuards.js:7

---

PurseShape

• Const PurseShape: Matcher

Defined in

typeGuards.js:8

---

RatioShape

• Const RatioShape: Object

Type declaration

Name	Type
denominator	{ brand: Matcher = BrandShape; value: Matcher = AmountValueShape }
denominator.brand	Matcher
denominator.value	Matcher
numerator	{ brand: Matcher = BrandShape; value: Matcher = AmountValueShape }
numerator.brand	Matcher
numerator.value	Matcher

Defined in

typeGuards.js:79

Functions

assertAssetKind

▸ assertAssetKind(allegedAK): void

Parameters

Name	Type
allegedAK	AssetKind

Returns

void

Defined in

amountMath.js:30

---

assertValueGetHelpers

▸ assertValueGetHelpers<V>(value): MathHelpers<V>

Asserts that value is a valid AmountMath and returns the appropriate helpers.

Made available only for testing, but it is harmless for other uses.

Type parameters

Name	Type
V	extends AmountValue

Parameters

Name	Type
value	V

Returns

MathHelpers<V>

Defined in

amountMath.js:118

---

getAssetKind

▸ getAssetKind(amount): AssetKindForValue<V>

Parameters

Name	Type
amount	Amount<AssetKind>

Returns

AssetKindForValue<V>

Defined in

amountMath.js:374

---

hasIssuer

▸ hasIssuer(baggage): boolean

Does baggage already have an issuerKit?

Parameters

Name	Type
baggage	Baggage

Returns

boolean

Defined in

issuerKit.js:145

---

isCopyBagValue

▸ isCopyBagValue(value): value is CopyBag

Returns true if value is a CopyBag

Parameters

Name	Type
value	AmountValue

Returns

value is CopyBag

Defined in

typeGuards.js:120

---

isCopySetValue

▸ isCopySetValue(value): value is CopySet<any>

Returns true if value is a CopySet

Parameters

Name	Type
value	AmountValue

Returns

value is CopySet<any>

Defined in

typeGuards.js:99

---

isNatValue

▸ isNatValue(value): value is any

Returns true if value is a Nat bigint.

Parameters

Name	Type
value	AmountValue

Returns

value is any

Defined in

typeGuards.js:90

---

isSetValue

▸ isSetValue(value): value is SetValue

Returns true if value is a pass by copy array structure. Does not check for duplicates. To check for duplicates, use setMathHelpers.coerce.

Parameters

Name	Type
value	AmountValue

Returns

value is SetValue

Deprecated

Please change from using array-based SetValues to CopySet-based CopySetValues.

Defined in

typeGuards.js:111

---

makeDurableIssuerKit

▸ makeDurableIssuerKit<K>(issuerBaggage, name, assetKind?, displayInfo?, optShutdownWithFailure?, options?): IssuerKit<K>

Used only to make a new durable issuer, i.e., the initial incarnation of that issuer.

Type parameters

Name	Type	Description
K	extends AssetKind	The name becomes part of the brand in asset descriptions. The name is useful for debugging and double-checking assumptions, but should not be trusted wrt any external namespace. For example, anyone could create a new issuer kit with name 'BTC', but it is not bitcoin or even related. It is only the name according to that issuer and brand. The assetKind will be used to import a specific mathHelpers from the mathHelpers library. For example, natMathHelpers, the default, is used for basic fungible tokens. displayInfo gives information to the UI on how to display the amount.

Parameters

Name	Type	Default value	Description
issuerBaggage	Baggage	undefined	-
name	string	undefined	-
assetKind?	K	AssetKind.NAT	-
displayInfo?	AdditionalDisplayInfo	undefined	-
optShutdownWithFailure?	ShutdownWithFailure	undefined	If this issuer fails in the middle of an atomic action (which btw should never happen), it potentially leaves its ledger in a corrupted state. If this function was provided, then the failed atomic action will call it, so that some larger unit of computation, like the enclosing vat, can be shutdown before anything else is corrupted by that corrupted state. See https://github.com/Agoric/agoric-sdk/issues/3434
options?	Partial<{ elementShape: any ; recoverySetsOption: RecoverySetsOption }>	{}	-

Returns

IssuerKit<K>

Defined in

issuerKit.js:197

---

makeIssuerInterfaces

▸ makeIssuerInterfaces(brandShape?, assetKindShape?, amountShape?): Object

Parameters

Name	Type	Default value
brandShape?	any	BrandShape
assetKindShape?	any	AssetKindShape
amountShape?	any	AmountShape

Returns

Object

Name	Type
IssuerI	InterfaceGuard<{ burn: MethodGuard ; getAllegedName: MethodGuard ; getAmountOf: MethodGuard ; getAssetKind: MethodGuard ; getBrand: MethodGuard ; getDisplayInfo: MethodGuard ; isLive: MethodGuard ; makeEmptyPurse: MethodGuard }>
MintI	InterfaceGuard<{ getIssuer: MethodGuard ; mintPayment: MethodGuard }>
PaymentI	InterfaceGuard<{ getAllegedBrand: MethodGuard }>
PurseIKit	{ depositFacet: InterfaceGuard<{ receive: MethodGuard }> = DepositFacetI; purse: InterfaceGuard<{ deposit: MethodGuard ; getAllegedBrand: MethodGuard ; getCurrentAmount: MethodGuard ; getCurrentAmountNotifier: MethodGuard ; getDepositFacet: MethodGuard ; getRecoverySet: MethodGuard ; recoverAll: MethodGuard ; withdraw: MethodGuard }> = PurseI }
PurseIKit.depositFacet	InterfaceGuard<{ receive: MethodGuard }>
PurseIKit.purse	InterfaceGuard<{ deposit: MethodGuard ; getAllegedBrand: MethodGuard ; getCurrentAmount: MethodGuard ; getCurrentAmountNotifier: MethodGuard ; getDepositFacet: MethodGuard ; getRecoverySet: MethodGuard ; recoverAll: MethodGuard ; withdraw: MethodGuard }>

Defined in

typeGuards.js:165

---

makeIssuerKit

▸ makeIssuerKit<K>(name, assetKind?, displayInfo?, optShutdownWithFailure?, options?): IssuerKit<K>

Used only to make a new issuerKit that is effectively non-durable. This is currently done by making a durable one in a baggage not reachable from anywhere. TODO Once rebuilt on zones, this should instead just build on the virtual zone. See https://github.com/Agoric/agoric-sdk/pull/7116

Currently used for testing only. Should probably continue to be used for testing only.

Type parameters

Name	Type	Description
K	extends AssetKind = "nat"	The name becomes part of the brand in asset descriptions. The name is useful for debugging and double-checking assumptions, but should not be trusted wrt any external namespace. For example, anyone could create a new issuer kit with name 'BTC', but it is not bitcoin or even related. It is only the name according to that issuer and brand. The assetKind will be used to import a specific mathHelpers from the mathHelpers library. For example, natMathHelpers, the default, is used for basic fungible tokens. displayInfo gives information to the UI on how to display the amount.

Parameters

Name	Type	Default value	Description
name	string	undefined	-
assetKind?	K	AssetKind.NAT	-
displayInfo?	AdditionalDisplayInfo	undefined	-
optShutdownWithFailure?	ShutdownWithFailure	undefined	If this issuer fails in the middle of an atomic action (which btw should never happen), it potentially leaves its ledger in a corrupted state. If this function was provided, then the failed atomic action will call it, so that some larger unit of computation, like the enclosing vat, can be shutdown before anything else is corrupted by that corrupted state. See https://github.com/Agoric/agoric-sdk/issues/3434
options?	Partial<{ elementShape: any ; recoverySetsOption: RecoverySetsOption }>	{}	-

Returns

IssuerKit<K>

Defined in

issuerKit.js:329

---

prepareIssuerKit

▸ prepareIssuerKit<K>(issuerBaggage, name, assetKind?, displayInfo?, optShutdownWithFailure?, options?): IssuerKit<K>

Used to either revive a predecessor issuerKit, or to make a new durable one if it is absent, and to place it in baggage for the next successor.

Type parameters

Name	Type	Description
K	extends AssetKind	The name becomes part of the brand in asset descriptions. The name is useful for debugging and double-checking assumptions, but should not be trusted wrt any external namespace. For example, anyone could create a new issuer kit with name 'BTC', but it is not bitcoin or even related. It is only the name according to that issuer and brand. The assetKind will be used to import a specific mathHelpers from the mathHelpers library. For example, natMathHelpers, the default, is used for basic fungible tokens. displayInfo gives information to the UI on how to display the amount.

Parameters

Name	Type	Default value	Description
issuerBaggage	Baggage	undefined	-
name	string	undefined	-
assetKind?	K	AssetKind.NAT	-
displayInfo?	AdditionalDisplayInfo	undefined	-
optShutdownWithFailure?	ShutdownWithFailure	undefined	If this issuer fails in the middle of an atomic action (which btw should never happen), it potentially leaves its ledger in a corrupted state. If this function was provided, then the failed atomic action will call it, so that some larger unit of computation, like the enclosing vat, can be shutdown before anything else is corrupted by that corrupted state. See https://github.com/Agoric/agoric-sdk/issues/3434
options?	Partial<{ elementShape: any ; recoverySetsOption: RecoverySetsOption }>	{}	-

Returns

IssuerKit<K>

Defined in

issuerKit.js:255

---

upgradeIssuerKit

▸ upgradeIssuerKit<K>(issuerBaggage, optShutdownWithFailure?, recoverySetsOption?): IssuerKit<K>

Used only to upgrade a predecessor issuerKit. Use makeDurableIssuerKit to make a new one.

Type parameters

Name	Type
K	extends AssetKind

Parameters

Name	Type	Default value	Description
issuerBaggage	Baggage	undefined	-
optShutdownWithFailure?	ShutdownWithFailure	undefined	If this issuer fails in the middle of an atomic action (which btw should never happen), it potentially leaves its ledger in a corrupted state. If this function was provided, then the failed atomic action will call it, so that some larger unit of computation, like the enclosing vat, can be shutdown before anything else is corrupted by that corrupted state. See https://github.com/Agoric/agoric-sdk/issues/3434
recoverySetsOption?	RecoverySetsOption	undefined	Added in upgrade, so last and optional. See RecoverySetsOption for defaulting behavior.

Returns

IssuerKit<K>

Defined in

issuerKit.js:108