Search Apps Documentation Source Content File Folder Download Copy Actions Download State String Boolean Number Struct Map Slice Pointer Function Closure Reference Nil Package Type Interface Unknown

protocol_fee package

Overview

Package protocol_fee manages fee collection and distribution for GnoSwap protocol operations.

This contract collects authorized fees from protocol operations such as swaps, pool creation, withdrawals, and staking claims, then accounts for their distribution to DevOps and GovStaker according to configurable percentages.

Distribution Targets:

  • DevOps: Development and operations fund (default 0%)
  • GovStaker: Governance-staker destination (default 100%)

Accounting:

  • reservedTokens tracks token paths with collected fees awaiting distribution.
  • Per-token allocation accumulators and distribution-history trees distinguish amounts allocated from amounts actually transferred.
  • GovStaker allocations are bucketed by token path and accrual epoch.

Key Functions:

  • DistributeProtocolFee: Distributes accumulated fees to recipients
  • SetDevOpsPct/SetGovStakerPct: Configure distribution percentages
  • AddToProtocolFee: Pulls an approved fee into the distribution queue

The contract uses a version manager pattern for upgradeable implementations.

Functions

AddToProtocolFee

func AddToProtocolFee(cur realm, tokenPath string, amount int64) error

AddToProtocolFee pulls an approved fee amount from an authorized protocol caller into protocol-fee accounting. Authorized callers are pool, position, router, and staker realms; direct transfers to this address do not register a fee.

Parameters:

  • cur: Current realm context; callers use cross(cur) when crossing into this realm.
  • tokenPath: token contract path whose fee is being collected
  • amount: non-negative fee amount in the token's base units; zero performs no transfer

Returns:

  • err: nil on success; errSpoofedRealm for a spoofed-realm call; errProtocolFeeHalted when protocol-fee collection is halted

Halt check: returns errProtocolFeeHalted without transferring while the ProtocolFee halt scope is active.

Params

Command

# WARNING: This command is running in an INSECURE mode.
# It is strongly recommended to use a hardware device for signing
# and avoid trusting any computer connected to the internet,
# as your private keys could be exposed.

gnokey maketx call -pkgpath "gno.land/r/gnoswap/protocol_fee" -func "AddToProtocolFee" -args $'' -args $'' -gas-fee 1000000ugnot -gas-wanted 1_000_000_000 -send "" -chainid "gnoland-1" -remote "http://127.0.0.1:26657" ADDRESSgnokey query -remote "http://127.0.0.1:26657" auth/accounts/ADDRESS
gnokey maketx call -pkgpath "gno.land/r/gnoswap/protocol_fee" -func "AddToProtocolFee" -args $'' -args $'' -gas-fee 1000000ugnot -gas-wanted 1_000_000_000 -send "" -broadcast=false ADDRESS > call.tx
gnokey sign -tx-path call.tx -chainid "gnoland-1" -account-number ACCOUNTNUMBER -account-sequence SEQUENCENUMBER ADDRESS
gnokey broadcast -remote "http://127.0.0.1:26657" call.tx

AdvanceAccrualEpoch

func AdvanceAccrualEpoch(cur realm) int64

AdvanceAccrualEpoch closes the current accrual epoch and returns the new one. Fees arriving from now on are bucketed under the returned epoch. Only gov/staker may call it, on every stake change.

Parameters:

  • cur: Current realm context; callers use cross(cur) when crossing into this realm.

Returns:

  • epoch: newly active non-negative accrual epoch used for subsequently collected GovStaker fees

Command

# WARNING: This command is running in an INSECURE mode.
# It is strongly recommended to use a hardware device for signing
# and avoid trusting any computer connected to the internet,
# as your private keys could be exposed.

gnokey maketx call -pkgpath "gno.land/r/gnoswap/protocol_fee" -func "AdvanceAccrualEpoch" -gas-fee 1000000ugnot -gas-wanted 1_000_000_000 -send "" -chainid "gnoland-1" -remote "http://127.0.0.1:26657" ADDRESSgnokey query -remote "http://127.0.0.1:26657" auth/accounts/ADDRESS
gnokey maketx call -pkgpath "gno.land/r/gnoswap/protocol_fee" -func "AdvanceAccrualEpoch" -gas-fee 1000000ugnot -gas-wanted 1_000_000_000 -send "" -broadcast=false ADDRESS > call.tx
gnokey sign -tx-path call.tx -chainid "gnoland-1" -account-number ACCOUNTNUMBER -account-sequence SEQUENCENUMBER ADDRESS
gnokey broadcast -remote "http://127.0.0.1:26657" call.tx

ConsumeAccrualBuckets

func ConsumeAccrualBuckets(cur realm, tokenPath string, limit int) ([]int64, []int64)

ConsumeAccrualBuckets returns and clears up to limit of the oldest pending buckets of tokenPath as parallel epoch and amount slices. A limit of zero or less consumes every pending bucket. Only gov/staker may call it.

Parameters:

  • cur: Current realm context; callers use cross(cur) when crossing into this realm.
  • tokenPath: token contract path whose pending GovStaker accrual buckets are consumed
  • limit: maximum number of oldest buckets to consume; zero or negative consumes all pending buckets

Returns:

  • epochs: consumed accrual epoch numbers in ascending epoch order
  • amounts: GovStaker fee amounts corresponding positionally to epochs, in token base units

Params

Command

# WARNING: This command is running in an INSECURE mode.
# It is strongly recommended to use a hardware device for signing
# and avoid trusting any computer connected to the internet,
# as your private keys could be exposed.

gnokey maketx call -pkgpath "gno.land/r/gnoswap/protocol_fee" -func "ConsumeAccrualBuckets" -args $'' -args $'' -gas-fee 1000000ugnot -gas-wanted 1_000_000_000 -send "" -chainid "gnoland-1" -remote "http://127.0.0.1:26657" ADDRESSgnokey query -remote "http://127.0.0.1:26657" auth/accounts/ADDRESS
gnokey maketx call -pkgpath "gno.land/r/gnoswap/protocol_fee" -func "ConsumeAccrualBuckets" -args $'' -args $'' -gas-fee 1000000ugnot -gas-wanted 1_000_000_000 -send "" -broadcast=false ADDRESS > call.tx
gnokey sign -tx-path call.tx -chainid "gnoland-1" -account-number ACCOUNTNUMBER -account-sequence SEQUENCENUMBER ADDRESS
gnokey broadcast -remote "http://127.0.0.1:26657" call.tx

DistributeProtocolFee

func DistributeProtocolFee(cur realm)

DistributeProtocolFee distributes accumulated protocol fees to DevOps and GovStaker, subject to the implementation's caller authorization and halt checks.

Parameters:

  • cur: Current realm context; callers use cross(cur) when crossing into this realm.

Halt check: returns without distributing while the Withdraw halt scope is active.

Command

# WARNING: This command is running in an INSECURE mode.
# It is strongly recommended to use a hardware device for signing
# and avoid trusting any computer connected to the internet,
# as your private keys could be exposed.

gnokey maketx call -pkgpath "gno.land/r/gnoswap/protocol_fee" -func "DistributeProtocolFee" -gas-fee 1000000ugnot -gas-wanted 1_000_000_000 -send "" -chainid "gnoland-1" -remote "http://127.0.0.1:26657" ADDRESSgnokey query -remote "http://127.0.0.1:26657" auth/accounts/ADDRESS
gnokey maketx call -pkgpath "gno.land/r/gnoswap/protocol_fee" -func "DistributeProtocolFee" -gas-fee 1000000ugnot -gas-wanted 1_000_000_000 -send "" -broadcast=false ADDRESS > call.tx
gnokey sign -tx-path call.tx -chainid "gnoland-1" -account-number ACCOUNTNUMBER -account-sequence SEQUENCENUMBER ADDRESS
gnokey broadcast -remote "http://127.0.0.1:26657" call.tx

DistributeProtocolFeeByTokenPath

func DistributeProtocolFeeByTokenPath(cur realm, tokenPath string)

DistributeProtocolFeeByTokenPath distributes accumulated protocol fees reserved for one token path; an unreserved path has nothing to distribute.

Parameters:

  • cur: Current realm context; callers use cross(cur) when crossing into this realm.
  • tokenPath: token contract path whose reserved fee balance should be distributed

Halt check: returns without distributing while the Withdraw halt scope is active.

Param

Command

# WARNING: This command is running in an INSECURE mode.
# It is strongly recommended to use a hardware device for signing
# and avoid trusting any computer connected to the internet,
# as your private keys could be exposed.

gnokey maketx call -pkgpath "gno.land/r/gnoswap/protocol_fee" -func "DistributeProtocolFeeByTokenPath" -args $'' -gas-fee 1000000ugnot -gas-wanted 1_000_000_000 -send "" -chainid "gnoland-1" -remote "http://127.0.0.1:26657" ADDRESSgnokey query -remote "http://127.0.0.1:26657" auth/accounts/ADDRESS
gnokey maketx call -pkgpath "gno.land/r/gnoswap/protocol_fee" -func "DistributeProtocolFeeByTokenPath" -args $'' -gas-fee 1000000ugnot -gas-wanted 1_000_000_000 -send "" -broadcast=false ADDRESS > call.tx
gnokey sign -tx-path call.tx -chainid "gnoland-1" -account-number ACCOUNTNUMBER -account-sequence SEQUENCENUMBER ADDRESS
gnokey broadcast -remote "http://127.0.0.1:26657" call.tx

GetAccrualBuckets

func GetAccrualBuckets(tokenPath string, limit int) ([]int64, []int64)

GetAccrualBuckets returns up to limit of the oldest pending buckets of tokenPath without clearing them. A limit of zero or less returns every pending bucket.

Parameters:

  • tokenPath: token contract path whose pending GovStaker accrual buckets are queried
  • limit: maximum number of oldest buckets to return; zero or negative returns all pending buckets

Returns:

  • epochs: selected accrual epoch numbers in ascending epoch order
  • amounts: GovStaker fee amounts corresponding positionally to epochs, in token base units

Params

Command

gnokey query vm/qeval -remote "http://127.0.0.1:26657" -data "gno.land/r/gnoswap/protocol_fee.GetAccrualBuckets(,)"

Result

GetAccrualEpoch

func GetAccrualEpoch() int64

GetAccrualEpoch returns the accrual epoch fees are currently bucketed under.

Returns:

  • epoch: current non-negative accrual epoch assigned to newly collected GovStaker fees

Command

gnokey query vm/qeval -remote "http://127.0.0.1:26657" -data "gno.land/r/gnoswap/protocol_fee.GetAccrualEpoch()"

Result

GetAccrualPendingTokens

func GetAccrualPendingTokens() []string

GetAccrualPendingTokens returns the token paths that still own pending accrual buckets.

Returns:

  • tokenPaths: token contract paths with at least one pending GovStaker accrual bucket

Command

gnokey query vm/qeval -remote "http://127.0.0.1:26657" -data "gno.land/r/gnoswap/protocol_fee.GetAccrualPendingTokens()"

Result

GetAccuTransferToDevOpsByTokenPath

func GetAccuTransferToDevOpsByTokenPath(tokenPath string) int64

GetAccuTransferToDevOpsByTokenPath returns accumulated DevOps transfer for a token.

Parameters:

  • tokenPath: path of the token

Returns:

  • amount: accumulated transfer amount

Param

Command

gnokey query vm/qeval -remote "http://127.0.0.1:26657" -data "gno.land/r/gnoswap/protocol_fee.GetAccuTransferToDevOpsByTokenPath()"

Result

GetAccuTransferToGovStakerByTokenPath

func GetAccuTransferToGovStakerByTokenPath(tokenPath string) int64

GetAccuTransferToGovStakerByTokenPath returns accumulated GovStaker transfer for a token.

Parameters:

  • tokenPath: path of the token

Returns:

  • amount: accumulated transfer amount

Param

Command

gnokey query vm/qeval -remote "http://127.0.0.1:26657" -data "gno.land/r/gnoswap/protocol_fee.GetAccuTransferToGovStakerByTokenPath()"

Result

GetAccuTransfersToDevOps

func GetAccuTransfersToDevOps() map[string]int64

GetAccuTransfersToDevOps returns accumulated transfers to DevOps.

Returns:

  • transfers: map of token paths to accumulated amounts

Command

gnokey query vm/qeval -remote "http://127.0.0.1:26657" -data "gno.land/r/gnoswap/protocol_fee.GetAccuTransfersToDevOps()"

Result

GetAccuTransfersToGovStaker

func GetAccuTransfersToGovStaker() map[string]int64

GetAccuTransfersToGovStaker returns accumulated transfers to GovStaker.

Returns:

  • transfers: map of token paths to accumulated amounts

Command

gnokey query vm/qeval -remote "http://127.0.0.1:26657" -data "gno.land/r/gnoswap/protocol_fee.GetAccuTransfersToGovStaker()"

Result

GetActualDistributedToDevOps

func GetActualDistributedToDevOps() map[string]int64

GetActualDistributedToDevOps returns actual transfers completed to DevOps.

Returns:

  • transfers: map of token paths to actual distributed amounts

Command

gnokey query vm/qeval -remote "http://127.0.0.1:26657" -data "gno.land/r/gnoswap/protocol_fee.GetActualDistributedToDevOps()"

Result

GetActualDistributedToDevOpsByTokenPath

func GetActualDistributedToDevOpsByTokenPath(tokenPath string) int64

GetActualDistributedToDevOpsByTokenPath returns actual DevOps transfer for a token.

Parameters:

  • tokenPath: path of the token

Returns:

  • amount: actual distributed amount for the token

Param

Command

gnokey query vm/qeval -remote "http://127.0.0.1:26657" -data "gno.land/r/gnoswap/protocol_fee.GetActualDistributedToDevOpsByTokenPath()"

Result

GetActualDistributedToGovStaker

func GetActualDistributedToGovStaker() map[string]int64

GetActualDistributedToGovStaker returns actual transfers completed to GovStaker.

Returns:

  • transfers: map of token paths to actual distributed amounts

Command

gnokey query vm/qeval -remote "http://127.0.0.1:26657" -data "gno.land/r/gnoswap/protocol_fee.GetActualDistributedToGovStaker()"

Result

GetActualDistributedToGovStakerByTokenPath

func GetActualDistributedToGovStakerByTokenPath(tokenPath string) int64

GetActualDistributedToGovStakerByTokenPath returns actual GovStaker transfer for a token.

Parameters:

  • tokenPath: path of the token

Returns:

  • amount: actual distributed amount for the token

Param

Command

gnokey query vm/qeval -remote "http://127.0.0.1:26657" -data "gno.land/r/gnoswap/protocol_fee.GetActualDistributedToGovStakerByTokenPath()"

Result

GetDevOpsPct

func GetDevOpsPct() int64

GetDevOpsPct returns the DevOps fee allocation in basis-point units.

Returns:

  • pct: configured DevOps allocation from 0 through 10000 (10000 = 100%)

Command

gnokey query vm/qeval -remote "http://127.0.0.1:26657" -data "gno.land/r/gnoswap/protocol_fee.GetDevOpsPct()"

Result

GetDomainPath

func GetDomainPath() string

GetDomainPath returns the domain path of the protocol fee contract.

Returns:

  • domainPath: protocol fee contract domain path

Command

gnokey query vm/qeval -remote "http://127.0.0.1:26657" -data "gno.land/r/gnoswap/protocol_fee.GetDomainPath()"

Result

GetGovStakerPct

func GetGovStakerPct() int64

GetGovStakerPct returns the GovStaker fee allocation in basis-point units.

Returns:

  • pct: configured GovStaker allocation from 0 through 10000 (10000 = 100%)

Command

gnokey query vm/qeval -remote "http://127.0.0.1:26657" -data "gno.land/r/gnoswap/protocol_fee.GetGovStakerPct()"

Result

GetImplementationPackagePath

func GetImplementationPackagePath() string

GetImplementationPackagePath returns the package path of the currently active implementation.

Returns:

  • packagePath: package path of the active implementation

Command

gnokey query vm/qeval -remote "http://127.0.0.1:26657" -data "gno.land/r/gnoswap/protocol_fee.GetImplementationPackagePath()"

Result

GetReservedTokens

func GetReservedTokens() []string

GetReservedTokens returns token paths reserved for distribution.

Returns:

  • tokenPaths: token paths reserved for distribution

Command

gnokey query vm/qeval -remote "http://127.0.0.1:26657" -data "gno.land/r/gnoswap/protocol_fee.GetReservedTokens()"

Result

GetVersionPackagePath

func GetVersionPackagePath() string

GetVersionPackagePath returns the current implementation package path.

Returns:

  • packagePath: current implementation package path

Command

gnokey query vm/qeval -remote "http://127.0.0.1:26657" -data "gno.land/r/gnoswap/protocol_fee.GetVersionPackagePath()"

Result

NewBPTreeN

func NewBPTreeN(fanout int) *bptree.BPTree

NewBPTreeN allocates a BP-tree under /r/gnoswap/protocol_fee's realm context so tree.Set leaf-slot writes clear the readonly-taint gate regardless of which realm (protocol_fee/v1, mock, tests) calls Set. Callers must allocate protocol_fee trees through here rather than bptree.NewBPTreeN directly.

Parameters:

  • fanout: Branching factor passed to the BP-tree constructor.

Returns:

  • tree: A new BP-tree configured with fanout and allocated in the protocol-fee realm context.

Param

Command

gnokey query vm/qeval -remote "http://127.0.0.1:26657" -data "gno.land/r/gnoswap/protocol_fee.NewBPTreeN()"

Result

RegisterInitializer

func RegisterInitializer(cur realm, initializer func(_ int, rlm realm, protocolFeeStore IProtocolFeeStore) IProtocolFee)

RegisterInitializer registers a new protocol fee implementation version. This function is called by each version (v1, v2, etc.) during initialization to register their implementation with the proxy system.

The initializer function creates a new instance of the implementation using the provided protocolFeeStore interface. It receives a realm value that resolves to the protocol_fee proxy realm — the only address with write permission on the shared KV store — so any per-version store bootstrapping performed inside the initializer passes the proxy's authorization check.

Security: Only contracts within the domain path can register initializers. Each package path can only register once to prevent duplicate registrations.

Parameters:

  • cur: Current realm context; callers use cross(cur) when crossing into this realm.
  • initializer: callback that receives the proxy realm context and protocol-fee store, initializes version-specific state, and returns the implementation instance

Param

Command

# WARNING: This command is running in an INSECURE mode.
# It is strongly recommended to use a hardware device for signing
# and avoid trusting any computer connected to the internet,
# as your private keys could be exposed.

gnokey maketx call -pkgpath "gno.land/r/gnoswap/protocol_fee" -func "RegisterInitializer" -args $'' -gas-fee 1000000ugnot -gas-wanted 1_000_000_000 -send "" -chainid "gnoland-1" -remote "http://127.0.0.1:26657" ADDRESSgnokey query -remote "http://127.0.0.1:26657" auth/accounts/ADDRESS
gnokey maketx call -pkgpath "gno.land/r/gnoswap/protocol_fee" -func "RegisterInitializer" -args $'' -gas-fee 1000000ugnot -gas-wanted 1_000_000_000 -send "" -broadcast=false ADDRESS > call.tx
gnokey sign -tx-path call.tx -chainid "gnoland-1" -account-number ACCOUNTNUMBER -account-sequence SEQUENCENUMBER ADDRESS
gnokey broadcast -remote "http://127.0.0.1:26657" call.tx

Render

func Render(path string) string

Render delegates web rendering to the active implementation.

Param

Command

gnokey query vm/qeval -remote "http://127.0.0.1:26657" -data "gno.land/r/gnoswap/protocol_fee.Render()"

Result

SetDevOpsPct

func SetDevOpsPct(cur realm, pct int64)

SetDevOpsPct sets the share of protocol fees allocated to DevOps.

Parameters:

  • cur: Current realm context; callers use cross(cur) when crossing into this realm.
  • pct: DevOps allocation in basis-point units, from 0 through 10000 inclusive (10000 = 100%)

Halt check: reverts while the ProtocolFee halt scope is active.

Param

Command

# WARNING: This command is running in an INSECURE mode.
# It is strongly recommended to use a hardware device for signing
# and avoid trusting any computer connected to the internet,
# as your private keys could be exposed.

gnokey maketx call -pkgpath "gno.land/r/gnoswap/protocol_fee" -func "SetDevOpsPct" -args $'' -gas-fee 1000000ugnot -gas-wanted 1_000_000_000 -send "" -chainid "gnoland-1" -remote "http://127.0.0.1:26657" ADDRESSgnokey query -remote "http://127.0.0.1:26657" auth/accounts/ADDRESS
gnokey maketx call -pkgpath "gno.land/r/gnoswap/protocol_fee" -func "SetDevOpsPct" -args $'' -gas-fee 1000000ugnot -gas-wanted 1_000_000_000 -send "" -broadcast=false ADDRESS > call.tx
gnokey sign -tx-path call.tx -chainid "gnoland-1" -account-number ACCOUNTNUMBER -account-sequence SEQUENCENUMBER ADDRESS
gnokey broadcast -remote "http://127.0.0.1:26657" call.tx

SetGovStakerPct

func SetGovStakerPct(cur realm, pct int64)

SetGovStakerPct sets the share of protocol fees allocated to GovStaker.

Parameters:

  • cur: Current realm context; callers use cross(cur) when crossing into this realm.
  • pct: GovStaker allocation in basis-point units, from 0 through 10000 inclusive (10000 = 100%)

Halt check: reverts while the ProtocolFee halt scope is active.

Param

Command

# WARNING: This command is running in an INSECURE mode.
# It is strongly recommended to use a hardware device for signing
# and avoid trusting any computer connected to the internet,
# as your private keys could be exposed.

gnokey maketx call -pkgpath "gno.land/r/gnoswap/protocol_fee" -func "SetGovStakerPct" -args $'' -gas-fee 1000000ugnot -gas-wanted 1_000_000_000 -send "" -chainid "gnoland-1" -remote "http://127.0.0.1:26657" ADDRESSgnokey query -remote "http://127.0.0.1:26657" auth/accounts/ADDRESS
gnokey maketx call -pkgpath "gno.land/r/gnoswap/protocol_fee" -func "SetGovStakerPct" -args $'' -gas-fee 1000000ugnot -gas-wanted 1_000_000_000 -send "" -broadcast=false ADDRESS > call.tx
gnokey sign -tx-path call.tx -chainid "gnoland-1" -account-number ACCOUNTNUMBER -account-sequence SEQUENCENUMBER ADDRESS
gnokey broadcast -remote "http://127.0.0.1:26657" call.tx

UpgradeImpl

func UpgradeImpl(cur realm, packagePath string)

UpgradeImpl switches the active protocol fee implementation to a different version. This function allows seamless upgrades from one version to another without data migration or downtime.

Security: Only admin or governance can perform upgrades. The new implementation must have been previously registered via RegisterInitializer.

Parameters:

  • cur: Current realm context; callers use cross(cur) when crossing into this realm.
  • packagePath: registered implementation package path to activate

Param

Command

# WARNING: This command is running in an INSECURE mode.
# It is strongly recommended to use a hardware device for signing
# and avoid trusting any computer connected to the internet,
# as your private keys could be exposed.

gnokey maketx call -pkgpath "gno.land/r/gnoswap/protocol_fee" -func "UpgradeImpl" -args $'' -gas-fee 1000000ugnot -gas-wanted 1_000_000_000 -send "" -chainid "gnoland-1" -remote "http://127.0.0.1:26657" ADDRESSgnokey query -remote "http://127.0.0.1:26657" auth/accounts/ADDRESS
gnokey maketx call -pkgpath "gno.land/r/gnoswap/protocol_fee" -func "UpgradeImpl" -args $'' -gas-fee 1000000ugnot -gas-wanted 1_000_000_000 -send "" -broadcast=false ADDRESS > call.tx
gnokey sign -tx-path call.tx -chainid "gnoland-1" -account-number ACCOUNTNUMBER -account-sequence SEQUENCENUMBER ADDRESS
gnokey broadcast -remote "http://127.0.0.1:26657" call.tx

NewProtocolFeeStore

func NewProtocolFeeStore(kvStore store.KVStore) IProtocolFeeStore

NewProtocolFeeStore creates a protocol-fee store backed by the provided KV store. This function is used by the upgrade system to create storage instances for each implementation.

Parameters:

  • kvStore: Domain KV store used to persist protocol-fee state.

Returns:

  • protocolFeeStore: An IProtocolFeeStore implementation backed by kvStore.

Param

Command

gnokey query vm/qeval -remote "http://127.0.0.1:26657" -data "gno.land/r/gnoswap/protocol_fee.NewProtocolFeeStore()"

Result