API documentation of Agoric SDK / Exports / @agoric/governance / src
Module: src
Table of contents
Variables
Functions
- assertBallotConcernsParam
- assertContractElectorate
- assertContractGovernance
- assertElectorateMatches
- buildQuestion
- coerceQuestionSpec
- handleParamGovernance
- makeParamChangePositions
- makeParamManager
- makeParamManagerBuilder
- makeParamManagerSync
- positionIncluded
- setupParamGovernance
- validateQuestionDetails
- validateQuestionFromCounter
Variables
CONTRACT_ELECTORATE
• Const CONTRACT_ELECTORATE: "Electorate"
The electorate that governs changes to the contract's parameters. It must be declared in the governed contract.
Defined in
src/contractGovernance/governParam.js:19
ChoiceMethod
• Const ChoiceMethod: Object
"unranked" is more formally known as "approval" voting, but this is hard for people to intuit when there are only two alternatives.
Type declaration
| Name | Type |
|---|---|
ORDER | "order" |
PLURALITY | "plurality" |
UNRANKED | "unranked" |
Defined in
ElectionType
• Const ElectionType: Object
Type declaration
| Name | Type |
|---|---|
API_INVOCATION | "api_invocation" |
ELECTION | "election" |
OFFER_FILTER | "offer_filter" |
PARAM_CHANGE | "param_change" |
SURVEY | "survey" |
Defined in
ParamTypes
• Const ParamTypes: Object
Enum of parameter types
UNKNOWN is an escape hatch for types we haven't added yet. If you are developing a new contract and use UNKNOWN, please also file an issue to ask us to support the new type.
Type declaration
| Name | Type |
|---|---|
AMOUNT | "amount" |
BRAND | "brand" |
INSTALLATION | "installation" |
INSTANCE | "instance" |
INVITATION | "invitation" |
NAT | "nat" |
PASSABLE_RECORD | "record" |
RATIO | "ratio" |
RELATIVE_TIME | "relativeTime" |
STRING | "string" |
TIMESTAMP | "timestamp" |
UNKNOWN | "unknown" |
Defined in
QuorumRule
• Const QuorumRule: Object
Type declaration
| Name | Type |
|---|---|
ALL | "all" |
MAJORITY | "majority" |
NO_QUORUM | "no_quorum" |
Defined in
publicMixinAPI
• Const publicMixinAPI: Object
Type declaration
| Name | Type |
|---|---|
getAmount | MethodGuard |
getBrand | MethodGuard |
getGovernedParams | MethodGuard |
getInstallation | MethodGuard |
getInstance | MethodGuard |
getInvitationAmount | MethodGuard |
getNat | MethodGuard |
getRatio | MethodGuard |
getRelativeTime | MethodGuard |
getString | MethodGuard |
getSubscription | MethodGuard |
getTimestamp | MethodGuard |
getUnknown | MethodGuard |
Defined in
Functions
assertBallotConcernsParam
▸ assertBallotConcernsParam(paramSpec, questionSpec): void
assert that the parameter described by paramSpec is proposed to be changed in the question described by questionSpec.
Parameters
| Name | Type |
|---|---|
paramSpec | Object |
paramSpec.paramPath | unknown |
paramSpec.parameterName | string |
questionSpec | QuestionSpec<ParamChangeIssue<unknown>> |
Returns
void
Defined in
src/contractGovernance/governParam.js:43
assertContractElectorate
▸ assertContractElectorate(zoe, allegedGovernor, allegedElectorate): any
Assert that the governor refers to the indicated electorate.
Parameters
| Name | Type |
|---|---|
zoe | ERef<ZoeService> |
allegedGovernor | Instance |
allegedElectorate | Instance |
Returns
any
Defined in
assertContractGovernance
▸ assertContractGovernance(zoe, allegedGoverned, allegedGovernor, contractGovernorInstallation): Promise<GovernancePair>
Assert that the governed contract was started by the governor. Throws if either direction can't be established. If the call succeeds, then the governor got exclusive access to the governed contract's creatorFacet, and can be trusted to manage its parameters.
Parameters
| Name | Type |
|---|---|
zoe | ERef<ZoeService> |
allegedGoverned | Instance<(zcf: ZCF<GovernanceTerms<{}>>) => {}> |
allegedGovernor | Instance |
contractGovernorInstallation | Installation<<SF>(zcf: ZCF<{ governed: { issuerKeywordRecord: IssuerKeywordRecord ; label?: string ; terms: { governedParams: { Electorate: InvitationParam } } } ; governedContractInstallation: Installation<SF> ; timer: TimerService }>, privateArgs: { governed: Record<string, unknown> }, baggage: Baggage) => Promise<{ creatorFacet: GovernorCreatorFacet<SF> ; publicFacet: GovernorPublic }>> |
Returns
Promise<GovernancePair>
Defined in
assertElectorateMatches
▸ assertElectorateMatches(paramManager, governedParams): void
Parameters
| Name | Type |
|---|---|
paramManager | ParamManagerBase |
governedParams | Object |
governedParams.Electorate | ParamValueTyped<"invitation"> |
Returns
void
Defined in
src/contractGovernance/paramManager.js:27
buildQuestion
▸ buildQuestion(questionSpec, instance): Question
Parameters
| Name | Type | Description |
|---|---|---|
questionSpec | QuestionSpec<Issue> | - |
instance | Instance | voteCounter instance |
Returns
Question
Defined in
coerceQuestionSpec
▸ coerceQuestionSpec(allegedQuestionSpec): QuestionSpec<Issue>
Parameters
| Name | Type |
|---|---|
allegedQuestionSpec | QuestionSpec<Issue> |
Returns
QuestionSpec<Issue>
Defined in
handleParamGovernance
▸ handleParamGovernance<M>(zcf, initialPoserInvitation, paramTypesMap, storageNode?, marshaller?): Object
Helper for the 90% of contracts that will have only a single set of parameters. Using this for managed parameters, a contract only has to
- Define the parameter template, which includes name, type and value
- Add any methods needed in the public and creator facets.
It's also crucial that the governed contract not interact with the product of makeGovernorFacet(). The wrapped creatorFacet has the power to change parameter values, and the governance guarantees only hold if they're not used directly by the governed contract.
Type parameters
| Name | Type | Description |
|---|---|---|
M | extends ParamTypesMap | Map of types of custom governed terms |
Parameters
| Name | Type |
|---|---|
zcf | ZCF<GovernanceTerms<M>> |
initialPoserInvitation | Invitation<unknown, undefined> |
paramTypesMap | M |
storageNode? | ERef<StorageNode> |
marshaller? | ERef<Marshaller<unknown>> |
Returns
Object
| Name | Type |
|---|---|
augmentPublicFacet | <PF>(originalPublicFacet: PF) => GovernedPublicFacet<PF> |
augmentVirtualPublicFacet | <OPF>(originalPublicFacet: OPF) => OPF & { getAmount: PlusContext<never, (name: string) => Amount<"set"> | (name: string) => Amount<AssetKind> | (name: string) => Brand<AssetKind> | (name: string) => Instance | (name: string) => Installation<any> | (name: string) => bigint | (name: string) => Ratio | (name: string) => string | (name: string) => TimestampRecord | (name: string) => RelativeTimeRecord | (name: string) => any> ; getBrand: PlusContext<never, (name: string) => Amount<"set"> | (name: string) => Amount<AssetKind> | (name: string) => Brand<AssetKind> | (name: string) => Instance | (name: string) => Installation<any> | (name: string) => bigint | (name: string) => Ratio | (name: string) => string | (name: string) => TimestampRecord | (name: string) => RelativeTimeRecord | (name: string) => any> ; getGovernedParams: () => ERef<ParamStateRecord> ; getInstallation: PlusContext<never, (name: string) => Amount<"set"> | (name: string) => Amount<AssetKind> | (name: string) => Brand<AssetKind> | (name: string) => Instance | (name: string) => Installation<any> | (name: string) => bigint | (name: string) => Ratio | (name: string) => string | (name: string) => TimestampRecord | (name: string) => RelativeTimeRecord | (name: string) => any> ; getInstance: PlusContext<never, (name: string) => Amount<"set"> | (name: string) => Amount<AssetKind> | (name: string) => Brand<AssetKind> | (name: string) => Instance | (name: string) => Installation<any> | (name: string) => bigint | (name: string) => Ratio | (name: string) => string | (name: string) => TimestampRecord | (name: string) => RelativeTimeRecord | (name: string) => any> ; getInvitationAmount: PlusContext<never, (name: string) => Amount<"set"> | (name: string) => Amount<AssetKind> | (name: string) => Brand<AssetKind> | (name: string) => Instance | (name: string) => Installation<any> | (name: string) => bigint | (name: string) => Ratio | (name: string) => string | (name: string) => TimestampRecord | (name: string) => RelativeTimeRecord | (name: string) => any> ; getNat: PlusContext<never, (name: string) => Amount<"set"> | (name: string) => Amount<AssetKind> | (name: string) => Brand<AssetKind> | (name: string) => Instance | (name: string) => Installation<any> | (name: string) => bigint | (name: string) => Ratio | (name: string) => string | (name: string) => TimestampRecord | (name: string) => RelativeTimeRecord | (name: string) => any> ; getRatio: PlusContext<never, (name: string) => Amount<"set"> | (name: string) => Amount<AssetKind> | (name: string) => Brand<AssetKind> | (name: string) => Instance | (name: string) => Installation<any> | (name: string) => bigint | (name: string) => Ratio | (name: string) => string | (name: string) => TimestampRecord | (name: string) => RelativeTimeRecord | (name: string) => any> ; getRelativeTime: PlusContext<never, (name: string) => Amount<"set"> | (name: string) => Amount<AssetKind> | (name: string) => Brand<AssetKind> | (name: string) => Instance | (name: string) => Installation<any> | (name: string) => bigint | (name: string) => Ratio | (name: string) => string | (name: string) => TimestampRecord | (name: string) => RelativeTimeRecord | (name: string) => any> ; getString: PlusContext<never, (name: string) => Amount<"set"> | (name: string) => Amount<AssetKind> | (name: string) => Brand<AssetKind> | (name: string) => Instance | (name: string) => Installation<any> | (name: string) => bigint | (name: string) => Ratio | (name: string) => string | (name: string) => TimestampRecord | (name: string) => RelativeTimeRecord | (name: string) => any> ; getSubscription: () => StoredSubscription<GovernanceSubscriptionState> ; getTimestamp: PlusContext<never, (name: string) => Amount<"set"> | (name: string) => Amount<AssetKind> | (name: string) => Brand<AssetKind> | (name: string) => Instance | (name: string) => Installation<any> | (name: string) => bigint | (name: string) => Ratio | (name: string) => string | (name: string) => TimestampRecord | (name: string) => RelativeTimeRecord | (name: string) => any> ; getUnknown: PlusContext<never, (name: string) => Amount<"set"> | (name: string) => Amount<AssetKind> | (name: string) => Brand<AssetKind> | (name: string) => Instance | (name: string) => Installation<any> | (name: string) => bigint | (name: string) => Ratio | (name: string) => string | (name: string) => TimestampRecord | (name: string) => RelativeTimeRecord | (name: string) => any> } & RemotableBrand<{}, OPF & { getAmount: PlusContext<never, (name: string) => Amount<"set"> | (name: string) => Amount<AssetKind> | (name: string) => Brand<AssetKind> | (name: string) => Instance | (name: string) => Installation<any> | (name: string) => bigint | (name: string) => Ratio | (name: string) => string | (name: string) => TimestampRecord | (name: string) => RelativeTimeRecord | (name: string) => any> ; getBrand: PlusContext<never, (name: string) => Amount<"set"> | (name: string) => Amount<AssetKind> | (name: string) => Brand<AssetKind> | (name: string) => Instance | (name: string) => Installation<any> | (name: string) => bigint | (name: string) => Ratio | (name: string) => string | (name: string) => TimestampRecord | (name: string) => RelativeTimeRecord | (name: string) => any> ; getGovernedParams: () => ERef<ParamStateRecord> ; getInstallation: PlusContext<never, (name: string) => Amount<"set"> | (name: string) => Amount<AssetKind> | (name: string) => Brand<AssetKind> | (name: string) => Instance | (name: string) => Installation<any> | (name: string) => bigint | (name: string) => Ratio | (name: string) => string | (name: string) => TimestampRecord | (name: string) => RelativeTimeRecord | (name: string) => any> ; getInstance: PlusContext<never, (name: string) => Amount<"set"> | (name: string) => Amount<AssetKind> | (name: string) => Brand<AssetKind> | (name: string) => Instance | (name: string) => Installation<any> | (name: string) => bigint | (name: string) => Ratio | (name: string) => string | (name: string) => TimestampRecord | (name: string) => RelativeTimeRecord | (name: string) => any> ; getInvitationAmount: PlusContext<never, (name: string) => Amount<"set"> | (name: string) => Amount<AssetKind> | (name: string) => Brand<AssetKind> | (name: string) => Instance | (name: string) => Installation<any> | (name: string) => bigint | (name: string) => Ratio | (name: string) => string | (name: string) => TimestampRecord | (name: string) => RelativeTimeRecord | (name: string) => any> ; getNat: PlusContext<never, (name: string) => Amount<"set"> | (name: string) => Amount<AssetKind> | (name: string) => Brand<AssetKind> | (name: string) => Instance | (name: string) => Installation<any> | (name: string) => bigint | (name: string) => Ratio | (name: string) => string | (name: string) => TimestampRecord | (name: string) => RelativeTimeRecord | (name: string) => any> ; getRatio: PlusContext<never, (name: string) => Amount<"set"> | (name: string) => Amount<AssetKind> | (name: string) => Brand<AssetKind> | (name: string) => Instance | (name: string) => Installation<any> | (name: string) => bigint | (name: string) => Ratio | (name: string) => string | (name: string) => TimestampRecord | (name: string) => RelativeTimeRecord | (name: string) => any> ; getRelativeTime: PlusContext<never, (name: string) => Amount<"set"> | (name: string) => Amount<AssetKind> | (name: string) => Brand<AssetKind> | (name: string) => Instance | (name: string) => Installation<any> | (name: string) => bigint | (name: string) => Ratio | (name: string) => string | (name: string) => TimestampRecord | (name: string) => RelativeTimeRecord | (name: string) => any> ; getString: PlusContext<never, (name: string) => Amount<"set"> | (name: string) => Amount<AssetKind> | (name: string) => Brand<AssetKind> | (name: string) => Instance | (name: string) => Installation<any> | (name: string) => bigint | (name: string) => Ratio | (name: string) => string | (name: string) => TimestampRecord | (name: string) => RelativeTimeRecord | (name: string) => any> ; getSubscription: () => StoredSubscription<GovernanceSubscriptionState> ; getTimestamp: PlusContext<never, (name: string) => Amount<"set"> | (name: string) => Amount<AssetKind> | (name: string) => Brand<AssetKind> | (name: string) => Instance | (name: string) => Installation<any> | (name: string) => bigint | (name: string) => Ratio | (name: string) => string | (name: string) => TimestampRecord | (name: string) => RelativeTimeRecord | (name: string) => any> ; getUnknown: PlusContext<never, (name: string) => Amount<"set"> | (name: string) => Amount<AssetKind> | (name: string) => Brand<AssetKind> | (name: string) => Instance | (name: string) => Installation<any> | (name: string) => bigint | (name: string) => Ratio | (name: string) => string | (name: string) => TimestampRecord | (name: string) => RelativeTimeRecord | (name: string) => any> }> |
makeDurableGovernorFacet | <CF>(baggage: Baggage, limitedCreatorFacet: CF, governedApis?: Record<string, (...any: any[]) => unknown>) => { governorFacet: Guarded<{ getGovernedApiNames: () => string[] ; getGovernedApis: () => GovernedApis ; getInvitation: (name: any) => Promise<Invitation<unknown, undefined>> ; getLimitedCreatorFacet: () => CF ; getParamMgrRetriever: () => { get: () => TypedParamManager<... & ...> } & RemotableBrand<{}, { get: () => TypedParamManager<...> }> ; setOfferFilter: (strings: any) => Promise<void> }> ; limitedCreatorFacet: CF } |
makeFarGovernorFacet | <CF>(limitedCreatorFacet: CF, governedApis?: Record<string, (...any: any[]) => unknown>) => GovernedCreatorFacet<CF> |
makeGovernorFacet | <CF>(originalCreatorFacet: CF, governedApis?: {}) => GovernedCreatorFacet<CF> |
makeVirtualGovernorFacet | <LCF>(limitedCreatorFacet: LCF) => { governorFacet: FunctionsPlusContext<unknown, GovernedCreatorFacet<LCF>> ; limitedCreatorFacet: LCF } |
params | Getters<M & { Electorate: "invitation" = initialPoserInvitation }> |
publicMixin | { getAmount: (name: string) => Amount<AssetKind> = paramManager.getAmount; getBrand: (name: string) => Brand<AssetKind> = paramManager.getBrand; getGovernedParams: () => ERef<ParamStateRecord> ; getInstallation: (name: string) => Installation<any> = paramManager.getInstallation; getInstance: (name: string) => Instance = paramManager.getInstance; getInvitationAmount: (name: string) => Amount<"set"> = paramManager.getInvitationAmount; getNat: (name: string) => bigint = paramManager.getNat; getRatio: (name: string) => Ratio = paramManager.getRatio; getRelativeTime: (name: string) => RelativeTimeRecord = paramManager.getRelativeTime; getString: (name: string) => string = paramManager.getString; getSubscription: () => StoredSubscription<GovernanceSubscriptionState> ; getTimestamp: (name: string) => TimestampRecord = paramManager.getTimestamp; getUnknown: (name: string) => any = paramManager.getUnknown } |
publicMixin.getAmount | (name: string) => Amount<AssetKind> |
publicMixin.getBrand | (name: string) => Brand<AssetKind> |
publicMixin.getGovernedParams | () => ERef<ParamStateRecord> |
publicMixin.getInstallation | (name: string) => Installation<any> |
publicMixin.getInstance | (name: string) => Instance |
publicMixin.getInvitationAmount | (name: string) => Amount<"set"> |
publicMixin.getNat | (name: string) => bigint |
publicMixin.getRatio | (name: string) => Ratio |
publicMixin.getRelativeTime | (name: string) => RelativeTimeRecord |
publicMixin.getString | (name: string) => string |
publicMixin.getSubscription | () => StoredSubscription<GovernanceSubscriptionState> |
publicMixin.getTimestamp | (name: string) => TimestampRecord |
publicMixin.getUnknown | (name: string) => any |
Defined in
makeParamChangePositions
▸ makeParamChangePositions(changes): ParamChangePositions
Return a record containing the positive and negative positions for a question on changing the param to the proposedValue.
Parameters
| Name | Type |
|---|---|
changes | Record<string, unknown> |
Returns
ParamChangePositions
Defined in
src/contractGovernance/governParam.js:28
makeParamManager
▸ makeParamManager<T>(publisherKit, spec, zcf): TypedParamManager<{ [K in string | number | symbol]: T[K][0] }>
Type parameters
| Name | Type |
|---|---|
T | extends Record<string, SyncSpecTuple | AsyncSpecTuple> |
Parameters
| Name | Type |
|---|---|
publisherKit | StoredPublisherKit<GovernanceSubscriptionState> |
spec | T |
zcf | ZCF<Record<string, unknown>> |
Returns
TypedParamManager<{ [K in string | number | symbol]: T[K][0] }>
See
makeParamManagerSync
Defined in
src/contractGovernance/typedParamManager.js:85
makeParamManagerBuilder
▸ makeParamManagerBuilder(publisherKit, zoe?): ParamManagerBuilder
Parameters
| Name | Type |
|---|---|
publisherKit | StoredPublisherKit<GovernanceSubscriptionState> |
zoe? | ERef<ZoeService> |
Returns
ParamManagerBuilder
Defined in
src/contractGovernance/paramManager.js:60
makeParamManagerSync
▸ makeParamManagerSync<T>(publisherKit, spec): TypedParamManager<{ [K in string | number | symbol]: T[K][0] }>
Used only when the contract has multiple param managers. Exactly one must manage the electorate, which requires the async version.
Type parameters
| Name | Type |
|---|---|
T | extends Record<string, SyncSpecTuple> |
Parameters
| Name | Type |
|---|---|
publisherKit | StoredPublisherKit<GovernanceSubscriptionState> |
spec | T |
Returns
TypedParamManager<{ [K in string | number | symbol]: T[K][0] }>
See
makeParamManager
Defined in
src/contractGovernance/typedParamManager.js:119
positionIncluded
▸ positionIncluded(positions, position): boolean
Parameters
| Name | Type |
|---|---|
positions | Position[] |
position | Position |
Returns
boolean
Defined in
setupParamGovernance
▸ setupParamGovernance(paramManagerRetriever, contractInstance, timer, getUpdatedPoserFacet): ParamGovernor
Parameters
| Name | Type |
|---|---|
paramManagerRetriever | ERef<ParamManagerRetriever> |
contractInstance | Instance |
timer | TimerService |
getUpdatedPoserFacet | () => Promise<PoserFacet> |
Returns
ParamGovernor
Defined in
src/contractGovernance/governParam.js:61
validateQuestionDetails
▸ validateQuestionDetails(zoe, electorate, details): Promise<[void, void, void]>
Validate that the question details correspond to a parameter change question that the electorate hosts, and that the voteCounter and other details are consistent with it.
Parameters
| Name | Type |
|---|---|
zoe | ERef<ZoeService> |
electorate | Instance |
details | ParamChangeIssueDetails |
Returns
Promise<[void, void, void]>
Defined in
validateQuestionFromCounter
▸ validateQuestionFromCounter(zoe, electorate, voteCounter): Promise<[void, void, void]>
Validate that the questions counted by the voteCounter correspond to a parameter change question that the electorate hosts, and that the voteCounter and other details are consistent.
Parameters
| Name | Type |
|---|---|
zoe | ERef<ZoeService> |
electorate | Instance |
voteCounter | Instance |
Returns
Promise<[void, void, void]>