API documentation of Agoric SDK / Exports / @agoric/zoe / src/contractSupport

Module: src/contractSupport

Interfaces

Type Aliases

Variables

Functions

Type Aliases

CompareAmount

Ƭ CompareAmount: (amount: Amount, amountLimit: Amount) => boolean

Type declaration

▸ (amount, amountLimit): boolean

Parameters

Name	Type
`amount`	`Amount`
`amountLimit`	`Amount`

Returns

boolean

Defined in

zoe/src/contractSupport/priceAuthority.js:16

EventualRecorderKit

Ƭ EventualRecorderKit<T>: Pick<PublishKit<T>, "subscriber"> & { recorderP: ERef<Recorder<T>> }

Type parameters

Name
`T`

Defined in

zoe/src/contractSupport/recorder.js:36

MakeERecorderKit

Ƭ MakeERecorderKit: ReturnType<typeof defineERecorderKit>

Defined in

zoe/src/contractSupport/recorder.js:195

MakeRecorder

Ƭ MakeRecorder: ReturnType<typeof prepareRecorder>

Defined in

zoe/src/contractSupport/recorder.js:135

MakeRecorderKit

Ƭ MakeRecorderKit: ReturnType<typeof defineRecorderKit>

Defined in

zoe/src/contractSupport/recorder.js:164

MatchedType

Ƭ MatchedType<TM>: TM extends TypedMatcher<infer T> ? T : never

Type parameters

Name	Type
`TM`	extends `TypedMatcher`<`any`>

Defined in

zoe/src/contractSupport/recorder.js:275

PublicTopic

Ƭ PublicTopic<T>: Object

Type parameters

Name	Type	Description
`T`	extends `object`	topic value

Type declaration

Name	Type
`description?`	`string`
`storagePath`	`ERef`<`string`>
`subscriber`	`Subscriber`<`T`>

Defined in

zoe/src/contractSupport/topics.js:21

Recorder

Ƭ Recorder<T>: Object

Type parameters

Name
`T`

Type declaration

Name	Type
`getStorageNode`	() => `DataOnly`<`StorageNode`> & `RemotableBrand`<`DataOnly`<`StorageNode`>, `StorageNode`>
`getStoragePath`	() => `Promise`<`string`>
`write`	(`value`: `T`) => `Promise`<`void`>
`writeFinal`	(`value`: `T`) => `Promise`<`void`>

Defined in

zoe/src/contractSupport/recorder.js:26

RecorderKit

Ƭ RecorderKit<T>: Pick<PublishKit<T>, "subscriber"> & { recorder: Recorder<T> }

Type parameters

Name
`T`

Defined in

zoe/src/contractSupport/recorder.js:31

TopicsRecord

Ƭ TopicsRecord: Object

Index signature

▪ [topicName: string]: PublicTopic<unknown>

Defined in

zoe/src/contractSupport/topics.js:29

Trigger

Ƭ Trigger: (createInstantQuote: PriceQuoteCreate) => Promise<void>

Type declaration

▸ (createInstantQuote): Promise<void>

Parameters

Name	Type
`createInstantQuote`	`PriceQuoteCreate`

Returns

Promise<void>

Defined in

zoe/src/contractSupport/priceAuthority.js:35

TypedMatcher

Ƭ TypedMatcher<T>: Object

Type parameters

Name
`T`

Type declaration

Name	Type
`validatedType?`	`T`

Defined in

zoe/src/contractSupport/recorder.js:270

Variables

PriceAuthorityI

• Const PriceAuthorityI: InterfaceGuard<{ getQuoteIssuer: MethodGuard ; getTimerService: MethodGuard ; makeQuoteNotifier: MethodGuard ; mutableQuoteWhenGT: MethodGuard = GuardCallAmountTuple; mutableQuoteWhenGTE: MethodGuard = GuardCallAmountTuple; mutableQuoteWhenLT: MethodGuard = GuardCallAmountTuple; mutableQuoteWhenLTE: MethodGuard = GuardCallAmountTuple; quoteAtTime: MethodGuard ; quoteGiven: MethodGuard ; quoteWanted: MethodGuard ; quoteWhenGT: MethodGuard = GuardCallAmountTuple; quoteWhenGTE: MethodGuard = GuardCallAmountTuple; quoteWhenLT: MethodGuard = GuardCallAmountTuple; quoteWhenLTE: MethodGuard = GuardCallAmountTuple }>

Defined in

zoe/src/contractSupport/priceAuthority.js:43

PublicTopicShape

• Const PublicTopicShape: Matcher

Defined in

zoe/src/contractSupport/topics.js:7

SubscriberShape

• Const SubscriberShape: Matcher

Defined in

notifier/src/publish-kit.js:480

TopicsRecordShape

• Const TopicsRecordShape: Matcher

Template

topic value

Defined in

zoe/src/contractSupport/topics.js:24

defaultAcceptanceMsg

• Const defaultAcceptanceMsg: "The offer has been accepted. Once the contract has been completed, please check your payout"

Defined in

zoe/src/contractSupport/zoeHelpers.js:10

natSafeMath

• Const natSafeMath: Object

These operations should be used for calculations with the values of basic fungible tokens.

natSafeMath is designed to be used directly, and so it needs to validate the inputs, as well as the outputs when necessary.

Type declaration

Name	Type	Description
`add`	`NatOp`	-
`bankersDivide`	`NatOp`	Divide using half-to-even (aka Banker's Rounding) as in IEEE 774 default rounding
`ceilDivide`	`NatOp`	-
`floorDivide`	`NatOp`	-
`isGTE`	(`x`: `number` \| `bigint`, `y`: `number` \| `bigint`) => `boolean`	-
`multiply`	`NatOp`	-
`subtract`	`NatOp`	-

Defined in

zoe/src/contractSupport/safeMath.js:12

Functions

addRatios

▸ addRatios(left, right): Ratio

Parameters

Name	Type
`left`	`Ratio`
`right`	`Ratio`

Returns

Ratio

Defined in

zoe/src/contractSupport/ratio.js:191

assertIsRatio

▸ assertIsRatio(ratio): void

Parameters

Name	Type
`ratio`	`any`

Returns

void

Defined in

zoe/src/contractSupport/ratio.js:41

assertIssuerKeywords

▸ assertIssuerKeywords(zcf, expected): void

Parameters

Name	Type
`zcf`	`any`
`expected`	`any`

Returns

void

Defined in

zoe/src/contractSupport/zoeHelpers.js:16

assertNatAssetKind

▸ assertNatAssetKind(zcf, brand): void

Parameters

Name	Type
`zcf`	`any`
`brand`	`any`

Returns

void

Defined in

zoe/src/contractSupport/zoeHelpers.js:167

assertProposalShape

▸ assertProposalShape(seat, expected): void

Check the seat's proposal against an expected record that says what "shape" of proposal is acceptable.

Note that by our current terminology, this function is misnamed because we use "Shape" to refer to patterns, and the expected argument is not such a pattern. Rather it is an ad-hoc pattern-like special case record that is different and much less expressive.

This ExpectedRecord is like a Proposal, but the amounts in 'want' and 'give' should be null; the exit clause should specify a rule with null contents. If the client submits an offer which does not match these expectations, the seat will be exited (and payments refunded).

Parameters

Name	Type
`seat`	`ZCFSeat`
`expected`	`ExpectedRecord`

Returns

void

Deprecated

Use optional proposalShape argument to makeInvitation with a genuine pattern.

Defined in

zoe/src/contractSupport/zoeHelpers.js:135

atomicRearrange

▸ atomicRearrange(zcf, transfers): void

Asks Zoe (via zcf) to rearrange the allocations among the seats mentioned. This is a set of changes to allocations that must satisfy several constraints. If these constraints are all met, then the reallocation happens atomically. Otherwise it does not happen at all.

The conditions

All the mentioned seats are still live -- enforced by ZCF.
No outstanding stagings for any of the mentioned seats. Stagings now deprecated in favor or atomicRearrange. To prevent confusion, for each reallocation, it can only be expressed in the old way or the new way, but not a mixture.
Offer safety -- enforced by ZCF.
Overall conservation -- enforced by ZCF.
The overall transfer is expressed as an array of TransferPart. Each individual TransferPart is one of
- A transfer from a fromSeat to a toSeat. This is not needed for Zoe's safety, as Zoe does its own overall conservation check. Rather, it helps catch and diagnose contract bugs earlier.
- A taking from a fromSeat's allocation. See the fromOnly helper.
  - A giving into a toSeat's allocation. See the toOnly helper.

TODO(6679) Refactor atomicRearrangefrom being a helper into being zcf's replacement for reallocate. It was made a helper during the transition, to avoid interference with progress on Zoe durability.

See the helpers below, fromOnly, toOnly, and atomicTransfer, which will remain helpers. These helper are for convenience in expressing atomic rearrangements clearly.

Parameters

Name	Type
`zcf`	`ZCF`<`Record`<`string`, `unknown`>>
`transfers`	`TransferPart`[]

Returns

void

Deprecated

use the zcf builtin instead

Defined in

zoe/src/contractSupport/atomicTransfer.js:48

atomicTransfer

▸ atomicTransfer(zcf, fromSeat?, toSeat?, fromAmounts?, toAmounts?): void

Special case of atomicRearrange for a single one-way transfer

Parameters

Name	Type	Default value
`zcf`	`ZCF`<`Record`<`string`, `unknown`>>	`undefined`
`fromSeat?`	`ZCFSeat`	`undefined`
`toSeat?`	`ZCFSeat`	`undefined`
`fromAmounts?`	`AmountKeywordRecord`	`undefined`
`toAmounts?`	`AmountKeywordRecord`	`undefined`

Returns

void

Defined in

zoe/src/contractSupport/atomicTransfer.js:91

calcLiqValueToMint

▸ calcLiqValueToMint(liqTokenSupply, inputValue, inputReserve): bigint

Calculate how many liquidity tokens we should be minting to send back to the user when adding liquidity. We provide new liquidity equal to the existing liquidity multiplied by the ratio of new central tokens to central tokens already held. If the current supply is zero, return the inputValue as the initial liquidity to mint is arbitrary.

Parameters

Name	Type
`liqTokenSupply`	`bigint`
`inputValue`	`bigint`
`inputReserve`	`bigint`

Returns

bigint

Defined in

zoe/src/contractSupport/bondingCurves.js:110

calcSecondaryRequired

▸ calcSecondaryRequired(centralIn, centralPool, secondaryPool, secondaryIn): bigint

Calculate how much of the secondary token is required from the user when adding liquidity. We require that the deposited ratio of central to secondary match the current ratio of holdings in the pool.

Parameters

Name	Type	Description
`centralIn`	`any`	The value of central assets being deposited
`centralPool`	`any`	The value of central assets in the pool
`secondaryPool`	`any`	The value of secondary assets in the pool
`secondaryIn`	`any`	The value of secondary assets provided. If the pool is empty, the entire amount will be accepted

Returns

bigint

the amount of secondary required

Defined in

zoe/src/contractSupport/bondingCurves.js:137

calcValueToRemove

▸ calcValueToRemove(liqTokenSupply, poolValue, liquidityValueIn): bigint

Parameters

Name	Type
`liqTokenSupply`	`any`
`poolValue`	`any`
`liquidityValueIn`	`any`

Returns

bigint

Defined in

zoe/src/contractSupport/bondingCurves.js:167

calculateMedian

▸ calculateMedian<T>(samples, math): undefined | T

Calculate the median of a set of samples

Type parameters

Name
`T`

Parameters

Name	Type	Description
`samples`	`T`[]	the input measurements
`math`	`TypedMath`<`T`>	-

Returns

undefined | T

the median (undefined if no samples)

Defined in

zoe/src/contractSupport/statistics.js:17

ceilDivideBy

▸ ceilDivideBy(amount, ratio): Amount<"nat">

Parameters

Name	Type
`amount`	`Amount`<`"nat"`>
`ratio`	`Ratio`

Returns

Amount<"nat">

Defined in

zoe/src/contractSupport/ratio.js:162

ceilMultiplyBy

▸ ceilMultiplyBy(amount, ratio): Amount<"nat">

Parameters

Name	Type
`amount`	`Amount`<`"nat"`>
`ratio`	`Ratio`

Returns

Amount<"nat">

Defined in

zoe/src/contractSupport/ratio.js:125

defineERecorderKit

▸ defineERecorderKit(makers): <T>(storageNodeP: ERef<StorageNode>, valueShape?: TypedMatcher<T>) => EventualRecorderKit<T>

makeERecorderKit is for closures that must return a subscriber synchronously but can defer the recorder.

Parameters

Name	Type
`makers`	`Object`
`makers.makeDurablePublishKit`	(...`args`: [options: Object]) => `GuardedKit`<{ `publisher`: { `fail`: (`reason`: `any`) => `void` ; `finish`: (`finalValue`: `any`) => `void` ; `publish`: (`value`: `any`) => `void` } ; `subscriber`: { `getUpdateSince`: (`updateCount`: `any`) => `any` ; `subscribeAfter`: (`publishCount`: `bigint`) => `Promise`<`any`> } }>
`makers.makeRecorder`	(...`args`: [publisher: Publisher<unknown>, storageNode: DataOnly<StorageNode> & RemotableBrand<DataOnly<StorageNode>, StorageNode>, valueShape: TypedMatcher<unknown>]) => `Guarded`<{ `getStorageNode`: () => `DataOnly`<`StorageNode`> & `RemotableBrand`<`DataOnly`<`StorageNode`>, `StorageNode`> ; `getStoragePath`: () => `Promise`<`string`> ; `write`: (`value`: `unknown`) => `Promise`<`void`> ; `writeFinal`: (`value`: `unknown`) => `Promise`<`void`> }>

Returns

fn

▸ <T>(storageNodeP, valueShape?): EventualRecorderKit<T>

Type parameters

Name
`T`

Parameters

Name	Type
`storageNodeP`	`ERef`<`StorageNode`>
`valueShape?`	`TypedMatcher`<`T`>

Returns

EventualRecorderKit<T>

See

Defined in

zoe/src/contractSupport/recorder.js:173

defineRecorderKit

▸ defineRecorderKit(makers): <T>(storageNode: StorageNode | DataOnly<StorageNode> & RemotableBrand<DataOnly<StorageNode>, StorageNode>, valueShape?: TypedMatcher<T>) => RecorderKit<T>

makeRecorderKit is suitable for making a durable RecorderKit which can be held in Exo state.

Parameters

Name	Type
`makers`	`Object`
`makers.makeDurablePublishKit`	(...`args`: [options: Object]) => `GuardedKit`<{ `publisher`: { `fail`: (`reason`: `any`) => `void` ; `finish`: (`finalValue`: `any`) => `void` ; `publish`: (`value`: `any`) => `void` } ; `subscriber`: { `getUpdateSince`: (`updateCount`: `any`) => `any` ; `subscribeAfter`: (`publishCount`: `bigint`) => `Promise`<`any`> } }>
`makers.makeRecorder`	(...`args`: [publisher: Publisher<unknown>, storageNode: DataOnly<StorageNode> & RemotableBrand<DataOnly<StorageNode>, StorageNode>, valueShape: TypedMatcher<unknown>]) => `Guarded`<{ `getStorageNode`: () => `DataOnly`<`StorageNode`> & `RemotableBrand`<`DataOnly`<`StorageNode`>, `StorageNode`> ; `getStoragePath`: () => `Promise`<`string`> ; `write`: (`value`: `unknown`) => `Promise`<`void`> ; `writeFinal`: (`value`: `unknown`) => `Promise`<`void`> }>

Returns

fn

▸ <T>(storageNode, valueShape?): RecorderKit<T>

Type parameters

Name
`T`

Parameters

Name	Type
`storageNode`	`StorageNode` \| `DataOnly`<`StorageNode`> & `RemotableBrand`<`DataOnly`<`StorageNode`>, `StorageNode`>
`valueShape?`	`TypedMatcher`<`T`>

Returns

RecorderKit<T>

See

Defined in

zoe/src/contractSupport/recorder.js:144

depositToSeat

▸ depositToSeat(zcf, recipientSeat, amounts, payments): Promise<string>

Deposit payments such that their amounts are reallocated to a seat. The amounts and payments records must have corresponding keywords.

Parameters

Name	Type
`zcf`	`ZCF`<`Record`<`string`, `unknown`>>
`recipientSeat`	`ZCFSeat`
`amounts`	`AmountKeywordRecord`
`payments`	`PaymentPKeywordRecord`

Returns

Promise<string>

Deposit and reallocation successful.

Defined in

zoe/src/contractSupport/zoeHelpers.js:185

fitProposalShape

▸ fitProposalShape(seat, proposalShape): void

Check the seat's proposal against proposalShape. If the client submits an offer which does not match these expectations, the seat will be exited (and payments refunded).

Parameters

Name	Type
`seat`	`ZCFSeat`
`proposalShape`	`any`

Returns

void

Defined in

zoe/src/contractSupport/zoeHelpers.js:111

floorDivideBy

▸ floorDivideBy(amount, ratio): Amount<"nat">

Parameters

Name	Type
`amount`	`Amount`<`"nat"`>
`ratio`	`Ratio`

Returns

Amount<"nat">

Defined in

zoe/src/contractSupport/ratio.js:157

floorMultiplyBy

▸ floorMultiplyBy(amount, ratio): Amount<"nat">

Parameters

Name	Type
`amount`	`Amount`<`"nat"`>
`ratio`	`Ratio`

Returns

Amount<"nat">

Defined in

zoe/src/contractSupport/ratio.js:120

fromOnly

▸ fromOnly(fromSeat, fromAmounts): TransferPart

Sometimes a TransferPart in an atomicRearrange only expresses what amounts should be taken from a seat, leaving it to other TransferPart of the same atomicRearrange to balance it out. For this case, the [fromSeat, undefined, fromAmounts] form is more clearly expressed as fromOnly(fromSeat, fromAmounts). Unlike TransferPart, both arguments to fromOnly are non-optional, as otherwise it doesn't make much sense.

Parameters

Name	Type
`fromSeat`	`ZCFSeat`
`fromAmounts`	`AmountKeywordRecord`

Returns

TransferPart

Defined in

zoe/src/contractSupport/atomicTransfer.js:64

getAmountIn

▸ getAmountIn(quote): Amount<"nat">

Parameters

Name	Type
`quote`	`PriceQuote`

Returns

Amount<"nat">

Defined in

zoe/src/contractSupport/priceQuote.js:25

getAmountOut

▸ getAmountOut(quote): Amount<"nat">

Parameters

Name	Type
`quote`	`PriceQuote`

Returns

Amount<"nat">

Defined in

zoe/src/contractSupport/priceQuote.js:27

getInputPrice

▸ getInputPrice(inputValue, inputReserve, outputReserve, feeBasisPoints?): bigint

Contains the logic for calculating how much should be given back to the user in exchange for what they sent in. Reused in several different places, including to check whether an offer is valid, getting the current price for an asset on user request, and to do the actual reallocation after an offer has been made.

Parameters

Name	Type	Description
`inputValue`	`any`	the value of the asset sent in to be swapped
`inputReserve`	`any`	the value in the liquidity pool of the kind of asset sent in
`outputReserve`	`any`	the value in the liquidity pool of the kind of asset to be sent out
`feeBasisPoints?`	`bigint`	the fee taken in basis points. The default is 0.3% or 30 basis points. The fee is taken from inputValue

Returns

bigint

outputValue - the current price, in value form

Defined in

zoe/src/contractSupport/bondingCurves.js:35

getOutputPrice

▸ getOutputPrice(outputValue, inputReserve, outputReserve, feeBasisPoints?): bigint

Contains the logic for calculating how much should be taken from the user in exchange for what they want to obtain. Reused in several different places, including to check whether an offer is valid, getting the current price for an asset on user request, and to do the actual reallocation after an offer has been made.

Parameters

Name	Type	Description
`outputValue`	`any`	the value of the asset the user wants to get
`inputReserve`	`any`	the value in the liquidity pool of the asset being spent
`outputReserve`	`any`	the value in the liquidity pool of the kind of asset to be sent out
`feeBasisPoints?`	`bigint`	the fee taken in basis points. The default is 0.3% or 30 basis points. The fee is taken from outputValue

Returns

bigint

inputValue - the value of input required to purchase output

Defined in

zoe/src/contractSupport/bondingCurves.js:74

getPriceDescription

▸ getPriceDescription(quote): PriceDescription

Parameters

Name	Type
`quote`	`PriceQuote`

Returns

PriceDescription

Defined in

zoe/src/contractSupport/priceQuote.js:18

getTimestamp

▸ getTimestamp(quote): Timestamp

Parameters

Name	Type
`quote`	`PriceQuote`

Returns

Timestamp

Defined in

zoe/src/contractSupport/priceQuote.js:29

invertRatio

▸ invertRatio(ratio): Ratio

Parameters

Name	Type
`ratio`	`Ratio`

Returns

Ratio

Defined in

zoe/src/contractSupport/ratio.js:175

makeEphemeraProvider

▸ makeEphemeraProvider<E, K>(init): (key: K) => E

SCALE: Only for low cardinality provisioning. Every value from init() will remain in the map for the lifetime of the heap. If a key object is GCed, its representative also remains.

Type parameters

Name	Type	Description
`E`	extends `Object`	Ephemeral state
`K`	extends `Object` = `any`	key on which to provision

Parameters

Name	Type
`init`	(`key`: `K`) => `E`

Returns

fn

▸ (key): E

Parameters

Name	Type
`key`	`K`

Returns

E

Defined in

zoe/src/contractSupport/durability.js:14

makeOnewayPriceAuthorityKit

▸ makeOnewayPriceAuthorityKit(opts): PriceAuthorityKit

Parameters

Name	Type
`opts`	`Object`
`opts.actualBrandIn`	`Brand`<`"nat"`>
`opts.actualBrandOut`	`Brand`<`"nat"`>
`opts.createQuote`	`PriceQuoteCreate`
`opts.notifier`	`ERef`<`Notifier`<`unknown`>>
`opts.quoteIssuer`	`Issuer`<`"set"`>
`opts.timer`	`ERef`<`TimerService`>

Returns

PriceAuthorityKit

Defined in

zoe/src/contractSupport/priceAuthority.js:72

makeRatio

▸ makeRatio(numerator, numeratorBrand, denominator?, denominatorBrand?): Ratio

Parameters

Name	Type	Default value	Description
`numerator`	`bigint`	`undefined`	-
`numeratorBrand`	`Brand`<`AssetKind`>	`undefined`	-
`denominator?`	`bigint`	`PERCENT`	The default denominator is 100
`denominatorBrand?`	`Brand`<`AssetKind`>	`numeratorBrand`	The default is to reuse the numeratorBrand

Returns

Ratio

Defined in

zoe/src/contractSupport/ratio.js:64

makeRatioFromAmounts

▸ makeRatioFromAmounts(numeratorAmount, denominatorAmount): Ratio

Parameters

Name	Type
`numeratorAmount`	`Amount`<`AssetKind`>
`denominatorAmount`	`Amount`<`AssetKind`>

Returns

Ratio

Defined in

zoe/src/contractSupport/ratio.js:85

makeRecorderTopic

▸ makeRecorderTopic<T>(description, recorderKit): PublicTopic<T>

Type parameters

Name
`T`

Parameters

Name	Type
`description`	`string`
`recorderKit`	`RecorderKit`<`T`> \| `EventualRecorderKit`<`T`>

Returns

PublicTopic<T>

Defined in

zoe/src/contractSupport/topics.js:38

makeStateMachine

▸ makeStateMachine(initialState, allowedTransitionsArray): Object

Parameters

Name	Type
`initialState`	`any`
`allowedTransitionsArray`	`any`

Returns

Object

Name	Type
`canTransitionTo`	(`nextState`: `any`) => `any`
`getStatus`	(`_`: `any`) => `any`
`transitionTo`	(`nextState`: `any`) => `void`

Defined in

zoe/src/contractSupport/stateMachine.js:11

multiplyRatios

▸ multiplyRatios(left, right): Ratio

Parameters

Name	Type
`left`	`Ratio`
`right`	`Ratio`

Returns

Ratio

Defined in

zoe/src/contractSupport/ratio.js:244

offerTo

▸ offerTo<Args, Result>(zcf, invitation, keywordMapping, proposal, fromSeat, toSeat?, offerArgs?): Promise<{ deposited: Promise<AmountKeywordRecord> ; userSeatPromise: Promise<UserSeat<Result>> }>

Make an offer to another contract instance (labeled contractB below), withdrawing the payments for the offer from a seat in the current contract instance (contractA) and depositing the payouts in another seat in the current contract instance (contractA).

Type parameters

Name	Type	Description
`Args`	extends `unknown`	Offer args
`Result`	extends `unknown`	Offer result

Parameters

Name	Type	Description
`zcf`	`ZCF`<`Record`<`string`, `unknown`>>	Zoe Contract Facet for contractA
`invitation`	`ERef`<`Invitation`<`Result`, `Args`>>	Invitation to contractB
`keywordMapping`	`undefined` \| `KeywordKeywordRecord`	Mapping of keywords used in contractA to keywords to be used in contractB. Note that the pathway to deposit the payout back to contractA reverses this mapping.
`proposal`	`Partial`<`ProposalRecord`>	The proposal for the offer to be made to contractB
`fromSeat`	`ZCFSeat`	The seat in contractA to take the offer payments from.
`toSeat?`	`ZCFSeat`	The seat in contractA to deposit the payout of the offer to. If `toSeat` is not provided, this defaults to the `fromSeat`.
`offerArgs?`	`Args`	Additional contract-specific optional arguments in a record.

Returns

Promise<{ deposited: Promise<AmountKeywordRecord> ; userSeatPromise: Promise<UserSeat<Result>> }>

A promise for the userSeat for the offer to the other contract, and a promise (deposited) which resolves when the payout for the offer has been deposited to the toSeat. Any failures of the invitation will be returned by userSeatPromise.getOfferResult().

Defined in

zoe/src/contractSupport/zoeHelpers.js:318

oneMinus

▸ oneMinus(ratio): Ratio

If ratio is between 0 and 1, subtract from 1.

Parameters

Name	Type
`ratio`	`Ratio`

Returns

Ratio

Defined in

zoe/src/contractSupport/ratio.js:280

prepareMockRecorderKitMakers

▸ prepareMockRecorderKitMakers(): Object

For use in tests

Returns

Object

Name	Type
`makeDurablePublishKit`	(...`args`: [options: Object]) => `GuardedKit`<{ `publisher`: { `fail`: (`reason`: `any`) => `void` ; `finish`: (`finalValue`: `any`) => `void` ; `publish`: (`value`: `any`) => `void` } ; `subscriber`: { `getUpdateSince`: (`updateCount`: `any`) => `any` ; `subscribeAfter`: (`publishCount`: `bigint`) => `Promise`<`any`> } }>
`makeERecorderKit`	<T>(`storageNodeP`: `ERef`<`StorageNode`>, `valueShape?`: `TypedMatcher`<`T`>) => `EventualRecorderKit`<`T`>
`makeRecorder`	(...`args`: [publisher: Publisher<unknown>, storageNode: DataOnly<StorageNode> & RemotableBrand<DataOnly<StorageNode>, StorageNode>, valueShape: TypedMatcher<unknown>]) => `Guarded`<{ `getStorageNode`: () => `DataOnly`<`StorageNode`> & `RemotableBrand`<`DataOnly`<`StorageNode`>, `StorageNode`> ; `getStoragePath`: () => `Promise`<`string`> ; `write`: (`value`: `unknown`) => `Promise`<`void`> ; `writeFinal`: (`value`: `unknown`) => `Promise`<`void`> }>
`makeRecorderKit`	<T>(`storageNode`: `StorageNode` \| `DataOnly`<`StorageNode`> & `RemotableBrand`<`DataOnly`<`StorageNode`>, `StorageNode`>, `valueShape?`: `TypedMatcher`<`T`>) => `RecorderKit`<`T`>
`storageNode`	`StorageNode` & { `countSetValueCalls`: () => `number` }

Defined in

zoe/src/contractSupport/recorder.js:253

prepareOwnable

▸ prepareOwnable<MN>(zone, makeInvitation, uKindName, uMethodNames, options?): <U>(underlying: U) => Pick<U, MN[number]> & { makeTransferInvitation: () => Invitation<U, undefined> }

Type parameters

Name	Type	Description
`MN`	extends (`string` \| `symbol`)[]	Method names

Parameters

Name	Type	Description
`zone`	`Zone`	-
`makeInvitation`	<R, A>(`offerHandler`: `OfferHandler`<`ERef`<`R`>, `A`>, `description`: `string`, `customDetails?`: `object`, `proposalShape?`: `any`) => `Promise`<`Invitation`<`R`, `A`>>	A function with the same behavior as `zcf.makeInvitation`. A contract will normally just extract it from its own zcf using the argument expression `js (...args) => zcf.makeInvitation(...args)` See ownable-counter.js for the canonical example.
`uKindName`	`string`	The `kindName` of the underlying exo class
`uMethodNames`	`MN`	The method names of the underlying exo class that should be represented by transparently-forwarding methods of the wrapping ownable object.
`options?`	`OwnableOptions`	-

Returns

fn

▸ <U>(underlying): Pick<U, MN[number]> & { makeTransferInvitation: () => Invitation<U, undefined> }

Type parameters

Name
`U`

Parameters

Name	Type
`underlying`	`U`

Returns

Pick<U, MN[number]> & { makeTransferInvitation: () => Invitation<U, undefined> }

Defined in

zoe/src/contractSupport/prepare-ownable.js:39

prepareRecorder

▸ prepareRecorder(baggage, marshaller): (...args: [publisher: Publisher<unknown>, storageNode: DataOnly<StorageNode> & RemotableBrand<DataOnly<StorageNode>, StorageNode>, valueShape: TypedMatcher<unknown>]) => Guarded<{ getStorageNode: () => DataOnly<StorageNode> & RemotableBrand<DataOnly<StorageNode>, StorageNode> ; getStoragePath: () => Promise<string> ; write: (value: unknown) => Promise<void> ; writeFinal: (value: unknown) => Promise<void> }>

Wrap a Publisher to record all the values to chain storage.

Parameters

Name	Type
`baggage`	`Baggage`
`marshaller`	`ERef`<`Marshaller`<`unknown`>>

Returns

fn

▸ (...args): Guarded<{ getStorageNode: () => DataOnly<StorageNode> & RemotableBrand<DataOnly<StorageNode>, StorageNode> ; getStoragePath: () => Promise<string> ; write: (value: unknown) => Promise<void> ; writeFinal: (value: unknown) => Promise<void> }>

Parameters

Name	Type
`...args`	[publisher: Publisher<unknown>, storageNode: DataOnly<StorageNode> & RemotableBrand<DataOnly<StorageNode>, StorageNode>, valueShape: TypedMatcher<unknown>]

Returns

Guarded<{ getStorageNode: () => DataOnly<StorageNode> & RemotableBrand<DataOnly<StorageNode>, StorageNode> ; getStoragePath: () => Promise<string> ; write: (value: unknown) => Promise<void> ; writeFinal: (value: unknown) => Promise<void> }>

Defined in

zoe/src/contractSupport/recorder.js:45

prepareRecorderKit

▸ prepareRecorderKit(baggage, marshaller): <T>(storageNode: StorageNode | DataOnly<StorageNode> & RemotableBrand<DataOnly<StorageNode>, StorageNode>, valueShape?: TypedMatcher<T>) => RecorderKit<T>

Convenience wrapper to prepare the DurablePublishKit and Recorder kinds. Note that because prepareRecorder() can only be called once per baggage, this should only be used when there is no need for an EventualRecorderKit. When there is, prepare the kinds separately and pass to the kit definers.

Parameters

Name	Type
`baggage`	`Baggage`
`marshaller`	`ERef`<`Marshaller`<`unknown`>>

Returns

fn

▸ <T>(storageNode, valueShape?): RecorderKit<T>

Type parameters

Name
`T`

Parameters

Name	Type
`storageNode`	`StorageNode` \| `DataOnly`<`StorageNode`> & `RemotableBrand`<`DataOnly`<`StorageNode`>, `StorageNode`>
`valueShape?`	`TypedMatcher`<`T`>

Returns

RecorderKit<T>

Defined in

zoe/src/contractSupport/recorder.js:206

prepareRecorderKitMakers

▸ prepareRecorderKitMakers(baggage, marshaller): Object

Convenience wrapper for DurablePublishKit and Recorder kinds.

NB: this defines two durable kinds. Must be called at most once per baggage.

makeRecorderKit is suitable for making a durable RecorderKit which can be held in Exo state. makeERecorderKit is for closures that must return a subscriber synchronously but can defer the recorder.

Parameters

Name	Type
`baggage`	`Baggage`
`marshaller`	`ERef`<`Marshaller`<`unknown`>>

Returns

Object

Name	Type
`makeDurablePublishKit`	(...`args`: [options: Object]) => `GuardedKit`<{ `publisher`: { `fail`: (`reason`: `any`) => `void` ; `finish`: (`finalValue`: `any`) => `void` ; `publish`: (`value`: `any`) => `void` } ; `subscriber`: { `getUpdateSince`: (`updateCount`: `any`) => `any` ; `subscribeAfter`: (`publishCount`: `bigint`) => `Promise`<`any`> } }>
`makeERecorderKit`	<T>(`storageNodeP`: `ERef`<`StorageNode`>, `valueShape?`: `TypedMatcher`<`T`>) => `EventualRecorderKit`<`T`>
`makeRecorder`	(...`args`: [publisher: Publisher<unknown>, storageNode: DataOnly<StorageNode> & RemotableBrand<DataOnly<StorageNode>, StorageNode>, valueShape: TypedMatcher<unknown>]) => `Guarded`<{ `getStorageNode`: () => `DataOnly`<`StorageNode`> & `RemotableBrand`<`DataOnly`<`StorageNode`>, `StorageNode`> ; `getStoragePath`: () => `Promise`<`string`> ; `write`: (`value`: `unknown`) => `Promise`<`void`> ; `writeFinal`: (`value`: `unknown`) => `Promise`<`void`> }>
`makeRecorderKit`	<T>(`storageNode`: `StorageNode` \| `DataOnly`<`StorageNode`> & `RemotableBrand`<`DataOnly`<`StorageNode`>, `StorageNode`>, `valueShape?`: `TypedMatcher`<`T`>) => `RecorderKit`<`T`>

Defined in

zoe/src/contractSupport/recorder.js:226

provideAll

▸ provideAll<T>(baggage, thunks): Promise<{ [K in string | number | symbol]: Awaited<ReturnType<T[K]>> }>

For use in contract upgrades to provide values that come from other vats. All vats must be able to finish their upgrade without contacting other vats, so whatever values an instance needs from other vats must be saved in the first incarnation and read from baggage in each subsequent.

This abstracts that condition so that the contract can convert a dictionary of thunks into a dictionary of values during its first prepare (start). Each subsequent prepare call will automatically read from the baggage and eschew remote calls.

The values are thunks instead of promises so that they don't start executing unnecessarily or induce failures.

For example,

const invitationIssuerP = E(zoe).getInvitationIssuer();
const {
  invitationIssuer,
  invitationBrand,
} = await provideAll(baggage, {
  invitationIssuer: () => invitationIssuerP,
  invitationBrand: () => E(invitationIssuerP).getBrand(),
});

Type parameters

Name	Type	Description
`T`	extends `Record`<`string`, () => `any`>	dict of thunks (promise makers)

Parameters

Name	Type
`baggage`	`MapStore`<`string`, `any`>
`thunks`	`T`

Returns

Promise<{ [K in string | number | symbol]: Awaited<ReturnType<T[K]>> }>

Defined in

zoe/src/contractSupport/durability.js:78

provideEmptySeat

▸ provideEmptySeat(zcf, baggage, name): ZCFSeat

Provide an empty ZCF seat.

Parameters

Name	Type
`zcf`	`ZCF`<`Record`<`string`, `unknown`>>
`baggage`	`MapStore`<`string`, `any`>
`name`	`string`

Returns

ZCFSeat

Defined in

zoe/src/contractSupport/durability.js:43

provideSingleton

▸ provideSingleton<T>(mapStore, key, makeValue, withValue?): Promise<Awaited<ReturnType<T>>>

Like provideAsync in AtomicProvider but assumes only one call so there are no race conditions. Additionally offers a withValue helper useful for triggering procesess on a provided object.

Type parameters

Name	Type
`T`	extends () => `any`

Parameters

Name	Type
`mapStore`	`Baggage`
`key`	`string`
`makeValue`	`T`
`withValue?`	(`value`: `Awaited`<`ReturnType`<`T`>>) => `void`

Returns

Promise<Awaited<ReturnType<T>>>

See

Defined in

zoe/src/contractSupport/durability.js:115

quantize

▸ quantize(ratio, newDen): Ratio

Make an equivalant ratio with a new denominator

Parameters

Name	Type
`ratio`	`Ratio`
`newDen`	`bigint`

Returns

Ratio

Defined in

zoe/src/contractSupport/ratio.js:338

ratioGTE

▸ ratioGTE(left, right): boolean

Parameters

Name	Type
`left`	`Ratio`
`right`	`Ratio`

Returns

boolean

Defined in

zoe/src/contractSupport/ratio.js:299

ratioToNumber

▸ ratioToNumber(ratio): number

Ratios might be greater or less than one.

Parameters

Name	Type
`ratio`	`Ratio`

Returns

number

Defined in

zoe/src/contractSupport/ratio.js:396

ratiosSame

▸ ratiosSame(left, right): boolean

True iff the ratios are the same values (equal or equivalant may return false)

Parameters

Name	Type
`left`	`Ratio`
`right`	`Ratio`

Returns

boolean

Defined in

zoe/src/contractSupport/ratio.js:324

satisfies

▸ satisfies(zcf, seat, update): 0 | 1

Check whether an update to currentAllocation satisfies proposal.want. Note that this is half of the offer safety check; whether the allocation constitutes a refund is not checked. The update is merged with currentAllocation (update's values prevailing if the keywords are the same) to produce the newAllocation. The return value is 0 for false and 1 for true. When multiples are introduced, any positive return value will mean true.

Parameters

Name	Type
`zcf`	`ZCF`<`Record`<`string`, `unknown`>>
`seat`	`ZcfSeatPartial`
`update`	`AmountKeywordRecord`

Returns

0 | 1

Defined in

zoe/src/contractSupport/zoeHelpers.js:46

saveAllIssuers

▸ saveAllIssuers(zcf, issuerKeywordRecord?): Promise<(undefined | IssuerRecord<any>)[]>

Save all of the issuers in an issuersKeywordRecord to ZCF, using the method zcf.saveIssuer. This does not error if any of the keywords already exist. If the keyword is already present, it is ignored.

Parameters

Name	Type	Description
`zcf`	`ZCF`<`Record`<`string`, `unknown`>>	-
`issuerKeywordRecord`	`IssuerKeywordRecord`	Issuers to save to ZCF

Returns

Promise<(undefined | IssuerRecord<any>)[]>

Defined in

zoe/src/contractSupport/zoeHelpers.js:242

subtractRatios

▸ subtractRatios(left, right): Ratio

Parameters

Name	Type
`left`	`Ratio`
`right`	`Ratio`

Returns

Ratio

Defined in

zoe/src/contractSupport/ratio.js:220

swap

▸ swap(zcf, leftSeat, rightSeat): string

Parameters

Name	Type
`zcf`	`ZCF`<`Record`<`string`, `unknown`>>
`leftSeat`	`ZCFSeat`
`rightSeat`	`ZCFSeat`

Returns

string

Defined in

zoe/src/contractSupport/zoeHelpers.js:54

swapExact

▸ swapExact(zcf, leftSeat, rightSeat): string

Parameters

Name	Type
`zcf`	`ZCF`<`Record`<`string`, `unknown`>>
`leftSeat`	`ZCFSeat`
`rightSeat`	`ZCFSeat`

Returns

string

Defined in

zoe/src/contractSupport/zoeHelpers.js:74

toOnly

▸ toOnly(toSeat, toAmounts): TransferPart

Sometimes a TransferPart in an atomicRearrange only expresses what amounts should be given to a seat, leaving it to other TransferPart of the same atomicRearrange to balance it out. For this case, the [undefined, toSeat, undefined, toAmounts] form is more clearly expressed as toOnly(toSeat, toAmounts). Unlike TransferPart, both arguments to toOnly are non-optional, as otherwise it doesn't make much sense.

Parameters

Name	Type
`toSeat`	`ZCFSeat`
`toAmounts`	`AmountKeywordRecord`

Returns

TransferPart

Defined in

zoe/src/contractSupport/atomicTransfer.js:79

unitAmount

▸ unitAmount(brand): Promise<Amount<"nat">>

Parameters

Name	Type
`brand`	`Brand`<`"nat"`>

Returns

Promise<Amount<"nat">>

Defined in

zoe/src/contractSupport/priceQuote.js:32

withdrawFromSeat

▸ withdrawFromSeat(zcf, seat, amounts): Promise<PaymentPKeywordRecord>

Withdraw payments from a seat. Note that withdrawing the amounts of the payments must not and cannot violate offer safety for the seat. The amounts and payments records must have corresponding keywords.

Parameters

Name	Type
`zcf`	`ZCF`<`Record`<`string`, `unknown`>>
`seat`	`ZCFSeat`
`amounts`	`AmountKeywordRecord`

Returns

Promise<PaymentPKeywordRecord>

Defined in

zoe/src/contractSupport/zoeHelpers.js:225

Module: src/contractSupport ​

Table of contents ​

Interfaces ​

Type Aliases ​

Variables ​

Functions ​

Type Aliases ​

CompareAmount ​

Type declaration ​

Parameters ​

Returns ​

Defined in ​

EventualRecorderKit ​

Type parameters ​

Defined in ​

MakeERecorderKit ​

Defined in ​

MakeRecorder ​

Defined in ​

MakeRecorderKit ​

Defined in ​

MatchedType ​

Type parameters ​

Defined in ​

PublicTopic ​

Type parameters ​

Type declaration ​

Defined in ​

Recorder ​

Type parameters ​

Type declaration ​

Defined in ​

RecorderKit ​

Type parameters ​

Defined in ​

TopicsRecord ​

Index signature ​

Defined in ​

Trigger ​

Type declaration ​

Parameters ​

Returns ​

Defined in ​

TypedMatcher ​

Type parameters ​

Type declaration ​

Defined in ​

Variables ​

PriceAuthorityI ​

Defined in ​

PublicTopicShape ​

Defined in ​

SubscriberShape ​

Defined in ​

TopicsRecordShape ​

Defined in ​

defaultAcceptanceMsg ​

Defined in ​

natSafeMath ​

Type declaration ​

Defined in ​

Functions ​

addRatios ​

Parameters ​

Returns ​

Defined in ​

assertIsRatio ​

Parameters ​

Returns ​

Defined in ​

assertIssuerKeywords ​

Parameters ​

Returns ​

Defined in ​

assertNatAssetKind ​

Parameters ​

Returns ​

Defined in ​

assertProposalShape ​

Parameters ​

Module: src/contractSupport

Table of contents

Interfaces

Type Aliases

Variables

Functions

Type Aliases

CompareAmount

Type declaration

Parameters

Returns

Defined in

EventualRecorderKit

Type parameters

Defined in

MakeERecorderKit

Defined in

MakeRecorder

Defined in

MakeRecorderKit

Defined in

MatchedType

Type parameters

Defined in

PublicTopic

Type parameters

Type declaration

Defined in

Recorder

Type parameters

Type declaration

Defined in

RecorderKit

Type parameters

Defined in

TopicsRecord

Index signature

Defined in

Trigger

Type declaration

Parameters

Returns

Defined in

TypedMatcher

Type parameters

Type declaration

Defined in

Variables

PriceAuthorityI

Defined in

PublicTopicShape

Defined in

SubscriberShape

Defined in

TopicsRecordShape

Defined in

defaultAcceptanceMsg

Defined in

natSafeMath

Type declaration

Defined in

Functions

addRatios

Parameters

Returns

Defined in

assertIsRatio

Parameters

Returns

Defined in

assertIssuerKeywords

Parameters

Returns

Defined in

assertNatAssetKind

Parameters

Returns

Defined in

assertProposalShape

Parameters