Resolutions

Resolutions are custom governance proposals that can be implemented in a Kwil network. Custom resolutions allow developers to build types of governance proposals that can be proposed and voted on by all stakeholders in the network. Implementations can specify the required voting threshold, the maximum duration of the proposal, and the subsequent state changes that will be applied if the proposal is approved.

Defining a Resolution

Resolutions are defined using a ResolutionConfig:

// ResolutionConfig is a configuration for a type of resolution.
// It can be used to define resolutions that a Kwil network can vote
// on, and define the resulting logic if the resolution receives the
// required number of votes.
type ResolutionConfig struct {
    // RefundThreshold is the required vote percentage threshold for
    // all voters on a resolution to be refunded the gas costs
    // associated with voting. This allows for resolutions that have
    // not received enough votes to pass to refund gas to the voters
    // that have voted on the resolution. For a 1/3rds threshold,
    // >=1/3rds of the voters must vote for the resolution for
    // refunds to occur. If this threshold is not met, voters will
    // not be refunded when the resolution expires. The number must
    // be a fraction between 0 and 1. If this field is nil, it will
    // default to only refunding voters when the resolution is confirmed.
    RefundThreshold *big.Rat
    // ConfirmationThreshold is the required vote percentage
    // threshold for whether a resolution is confirmed. In a 2/3rds
    // threshold, >=2/3rds of the voters must vote for the resolution
    // for it to be confirmed. Voters will also be refunded if this
    // threshold is met, regardless of the refund threshold. The
    // number must be a fraction between 0 and 1. If this field is
    // nil, it will default to 2/3.
    ConfirmationThreshold *big.Rat
    // ExpirationPeriod is the amount of blocks that the resolution
    // will be valid for before it expires. It is applied additively
    // to the current block height when the resolution is proposed;
    // if the current block height is 10 and the expiration height is
    // 5, the resolution will expire at block 15. If this field is
    // <1, it will default to 14400, which is approximately 1 day
    // assuming 6 second blocks.
    ExpirationPeriod int64
    // ResolveFunc is a function that is called once a resolution has
    // received a required number of votes, as defined by the
    // ConfirmationThreshold. It is given a readwrite database
    // connection and the information for the resolution that has
    // been confirmed. All nodes will call this function as a part of
    // block execution. It is therefore expected that the function is
    // deterministic, regardless of a node's local configuration.
    ResolveFunc func(ctx context.Context, app *common.App, resolution *Resolution) error
}

ResolutionConfig structs should be registered in an init function, to ensure that they are available to the network when it starts:

package main

import (
    "math/big"

    "github.com/kwilteam/kwil-db/extensions/resolutions"
    "github.com/kwilteam/kwil-db/common"
)
func init() {
    // Register the resolution with the network
    err := resolutions.RegisterResolution("my_resolution", resolutions.ModAdd, resolutions.ResolutionConfig{
        RefundThreshold:       big.NewRat(1, 3), // 1/3rds threshold
        ConfirmationThreshold: big.NewRat(2, 3), // 2/3rds threshold
        ExpirationPeriod:      14400,
        ResolveFunc:           func(ctx context.Context, app *common.App, resolution *resolutions.Resolution) error {
            // Implement the resolution logic here
        },
    })
    if err != nil {
        panic(err)
    }
}