Skip to content Search Apps Documentation Source Content Run Reset Eval Playground File Folder Download Copy Actions State String Boolean Number Struct Map Slice Pointer Function Closure Reference Nil Package Type Interface Unknown

Playground

doc.gno

// Package limit is the GnoSwap limit order realm.
//
// Users escrow makingAmount of tokenIn for takingAmount of tokenOut before
// expiresAt. Authorized keepers fill orders on a whitelisted direct pool,
// without the router, choosing the pool fee tier and swap price limit for
// each fill. Partial fills leave unsold input in escrow; each fill pays the
// owner immediately after deducting the order's snapshotted execution fee,
// while enforcing the order's slippage-adjusted owner-net exchange ratio.
// Owners can cancel for the remaining input, and anyone can refund expired
// orders through bounded cleanup. Settled orders are removed from the indexes.
//
// This package is the permanent entry point. It owns the escrow address, the
// KV store shared by every version, and the upgrade switch; the business
// logic lives in a registered implementation (impl/v0).
//
// Files:
//   - proxy.gno: state-changing entry points
//   - getter.gno: read-only queries
//   - store.gno: KV store and store keys
//   - state.gno: realm state and the active implementation
//   - upgrade.gno: implementation registration and upgrades
//   - swap_callback.gno: authenticated pool callback paying escrowed input
package limit

errors.gno

package limit

// Proxy errors carry no error code; codes belong to the implementation.

// ErrSpoofedRealm is returned when a store write gets a non-current realm.
const ErrSpoofedRealm = "spoofed realm"

// ErrNilInitializer is raised by RegisterInitializer for a nil factory.
const ErrNilInitializer = "nil initializer"

const (
	errImplNotInitialized                = "implementation is not initialized"
	errInvalidImpl                       = "impl is not an ILimitOrder"
	errInvalidDomainStore                = "domainStore is not an ILimitOrderStore"
	errNilConfig                         = "config is nil"
	errImplDoesNotSupportTargetedCleanup = "implementation does not support targeted expired-order cleanup"
	errImplDoesNotSupportFeeCollection   = "implementation does not support pending execution fee collection"

	// errInvalidSwapCallback is returned by an order's swap callback for a
	// call it must not pay.
	errInvalidSwapCallback = "invalid swap callback"

	// Format strings: the store key name, the config value.
	errNilValue          = "%s is nil"
	errInvalidConfigType = "failed to cast config: %T"
)

getter.gno

package limit

import (
	plimit "gno.land/p/gnoswap/order/limit/v0"
	rotree "gno.land/p/nt/bptree/rotree/v0"
)

// Getters return detached copies of stored values. Store trees are returned
// as read-only views keyed as in the store layout (see store.gno); views whose
// entries are pointers copy every entry they return. Callers page a view
// themselves through Iterate, IterateByOffset, or their reverse forms.

// ==================================
// Config Getters
// ==================================

// GetConfig returns a detached copy of the current global configuration.
//
// Returns:
//   - *plimit.Config: copy of the stored configuration
func GetConfig() *plimit.Config {
	return getImplementation().GetConfig()
}

// GetExecutionFeeRate returns the execution fee rate snapshotted into new orders.
//
// Returns:
//   - int64: execution fee rate, in basis points of gross output
func GetExecutionFeeRate() int64 {
	return GetConfig().ExecutionFeeRate()
}

// GetMaxSlippageBps returns the slippage cap for new orders.
//
// Returns:
//   - int64: maximum slippage, in basis points
func GetMaxSlippageBps() int64 {
	return GetConfig().MaxSlippageBps()
}

// GetMinMakingAmount returns the minimum input amount for new orders.
//
// Returns:
//   - int64: minimum makingAmount, in raw token units
func GetMinMakingAmount() int64 {
	return GetConfig().MinMakingAmount()
}

// GetOrderDeadlines returns the allowed order duration range for new orders.
//
// Returns:
//   - int64: shortest allowed expiresAt - createdAt, in seconds
//   - int64: longest allowed expiresAt - createdAt, in seconds
func GetOrderDeadlines() (int64, int64) {
	config := GetConfig()

	return config.MinOrderDuration(), config.MaxOrderDuration()
}

// GetMaxCleanupBatchSize returns the most orders one CleanupExpiredOrders call examines.
//
// Returns:
//   - int64: maximum cleanup batch size
func GetMaxCleanupBatchSize() int64 {
	return GetConfig().MaxCleanupBatchSize()
}

// ==================================
// Order Getters
// ==================================

// GetNextOrderID returns the ID the next created order receives.
//
// Returns:
//   - uint64: next order ID
func GetNextOrderID() uint64 {
	return getImplementation().GetNextOrderID()
}

// ExistsOrder reports whether an order is pending.
// Settled orders are deleted.
//
// Parameters:
//   - orderID: order to look up
//
// Returns:
//   - bool: true while the order is pending
func ExistsOrder(orderID uint64) bool {
	return getImplementation().ExistsOrder(orderID)
}

// GetOrder returns a detached pending order, or nil after it is settled.
//
// Parameters:
//   - orderID: order to look up
//
// Returns:
//   - *plimit.Order: copy of the order; nil when it is not pending
func GetOrder(orderID uint64) *plimit.Order {
	return getImplementation().GetOrder(orderID)
}

// GetOrders returns a live read-only view of pending orders.
//
// Returns:
//   - *rotree.ReadOnlyTree: plimit.OrderKey(orderID) -> *plimit.Order;
//     each order read from the view is detached from stored state
func GetOrders() *rotree.ReadOnlyTree {
	return getImplementation().GetOrders()
}

// GetOrdersByOwner returns the read-only owner index of pending orders.
// Iterate the [plimit.OwnerOrderPrefix(owner), plimit.PrefixEnd(prefix))
// range for one owner's orders in ID order, choosing the page size.
//
// Returns:
//   - *rotree.ReadOnlyTree: plimit.OwnerOrderKey(owner, orderID) -> uint64 orderID
func GetOrdersByOwner() *rotree.ReadOnlyTree {
	return getImplementation().GetOrdersByOwner()
}

// ==================================
// Execution Fee Getters
// ==================================

// GetPendingExecutionFeeAmount returns execution fees held for tokenPath until the
// protocol fee realm accepts them. A later fill with the same output token retries collection.
//
// Parameters:
//   - tokenPath: fee token path
//
// Returns:
//   - int64: pending execution fee, in raw token units
func GetPendingExecutionFeeAmount(tokenPath string) int64 {
	return getImplementation().GetPendingExecutionFeeAmount(tokenPath)
}

// GetPendingExecutionFees returns the read-only index of pending execution fees.
//
// Returns:
//   - *rotree.ReadOnlyTree: tokenPath -> int64 pending amount
func GetPendingExecutionFees() *rotree.ReadOnlyTree {
	return getImplementation().GetPendingExecutionFees()
}

gnomod.toml

module = "gno.land/r/gnoswap/order/limit"
gno = "0.9"

[addpkg]
  creator = "g1q5tjjv3kkslzwf2na9y9wk7e5a8ugph8xfsk04"
  height = 1108551
  max_deposit = "100000000ugnot"

proxy.gno

package limit

type expiredOrderCleanup interface {
	CleanupExpiredOrdersByIDs(_ int, rlm realm, orderIDs string) (expired int, retryOrderIDs string)
}

type pendingExecutionFeeCollector interface {
	CollectPendingExecutionFee(_ int, rlm realm, tokenPath string) (int64, int64)
}

// CreateOrder escrows makingAmount of tokenIn for takingAmount of tokenOut.
// Each fill supplies its pool fee tier and price limit.
// slippageBps=0 enforces the making/taking ratio or better.
// expiresAt must be positive and within the configured duration bounds.
// The execution fee rate is snapshotted into each new order.
// baseToken must be tokenIn (Sell) or tokenOut (Buy); it is emitted only as
// creation metadata and does not affect the order's execution terms.
// The caller must first approve Address() for makingAmount.
// Reverts while execution is halted for Limit orders.
func CreateOrder(
	cur realm,
	tokenIn string,
	tokenOut string,
	makingAmount int64,
	takingAmount int64,
	slippageBps int64,
	expiresAt int64,
	baseToken string,
) uint64 {
	return getImplementation().CreateOrder(0, cur, tokenIn, tokenOut, makingAmount, takingAmount, slippageBps, expiresAt, baseToken)
}

// CancelOrder refunds the remaining input and removes the order from the indexes.
// A past-deadline refund uses the expired event.
// It returns the refunded input.
//
// Owner only. Reverts while withdrawals are halted for limit orders.
func CancelOrder(cur realm, orderID uint64) int64 {
	return getImplementation().CancelOrder(0, cur, orderID)
}

// ExecuteOrder fills up to maxAmountIn through the order's token pair at poolFee.
// A nonzero sqrtPriceLimitX96 stops at that pool price and may leave input
// unspent in escrow. Zero requires maxAmountIn to be consumed in full.
// The order's minimum owner-net output is enforced on the actual input.
// Returns actual input and pool output before the order's execution fee;
// the owner is paid immediately after that fee is deducted.
// The immediate caller must be authorized for ExecuteOrder by the shared
// keeper policy. Reverts while execution or withdrawals are halted for limit orders.
func ExecuteOrder(cur realm, orderID uint64, maxAmountIn int64, poolFee uint32, sqrtPriceLimitX96 string) (int64, int64) {
	return getImplementation().ExecuteOrder(0, cur, orderID, maxAmountIn, poolFee, sqrtPriceLimitX96)
}

// CollectPendingExecutionFee forwards fees pending for tokenPath to the protocol
// fee realm without another fill. Anyone may call it; the caller receives nothing.
// Returns the amount forwarded and the amount left pending.
// Reverts while withdrawals are halted for Limit orders.
func CollectPendingExecutionFee(cur realm, tokenPath string) (int64, int64) {
	collector, ok := getImplementation().(pendingExecutionFeeCollector)
	if !ok {
		panic(errImplDoesNotSupportFeeCollection)
	}

	return collector.CollectPendingExecutionFee(0, cur, tokenPath)
}

// CleanupExpiredOrders refunds pending orders after their deadline.
// Anyone may call it.
//
// One call examines at most min(maxOrders, maxCleanupBatchSize) orders after
// startAfterOrderID, in ID order. It returns the number of orders expired and
// the cursor for the next call; repeat until the cursor is 0.
// Reverts while withdrawals are halted for limit orders.
func CleanupExpiredOrders(cur realm, startAfterOrderID uint64, maxOrders int) (int, uint64) {
	return getImplementation().CleanupExpiredOrders(0, cur, startAfterOrderID, maxOrders)
}

// CleanupExpiredOrdersByIDs refunds only the named expired orders.
// orderIDs is a strictly increasing comma-separated list of positive decimal
// order IDs. Existing unexpired or underfunded orders are returned for retry.
// Reverts while withdrawals are halted for limit orders.
func CleanupExpiredOrdersByIDs(cur realm, orderIDs string) (int, string) {
	cleanup, ok := getImplementation().(expiredOrderCleanup)
	if !ok {
		panic(errImplDoesNotSupportTargetedCleanup)
	}

	return cleanup.CleanupExpiredOrdersByIDs(0, cur, orderIDs)
}

// SetExecutionFeeRate sets the execution fee rate snapshotted into new orders,
// in basis points of gross output.
// Admin or governance only.
func SetExecutionFeeRate(cur realm, executionFeeRate int64) {
	getImplementation().SetExecutionFeeRate(0, cur, executionFeeRate)
}

// SetMinMakingAmount sets the minimum input amount for new orders, in raw token units.
// Existing orders are unaffected. Admin or governance only.
func SetMinMakingAmount(cur realm, minMakingAmount int64) {
	getImplementation().SetMinMakingAmount(0, cur, minMakingAmount)
}

// SetOrderDeadlines sets the allowed order duration range for new orders,
// in seconds. Admin or governance only.
func SetOrderDeadlines(cur realm, minDuration int64, maxDuration int64) {
	getImplementation().SetOrderDeadlines(0, cur, minDuration, maxDuration)
}

// SetMaxCleanupBatchSize caps the orders one CleanupExpiredOrders call examines,
// bounding its gas. Admin or governance only.
func SetMaxCleanupBatchSize(cur realm, maxCleanupBatchSize int64) {
	getImplementation().SetMaxCleanupBatchSize(0, cur, maxCleanupBatchSize)
}

// SetMaxSlippageBps sets the slippage cap for new orders in [0, 10000] bps.
// Existing orders keep their slippage. Admin or governance only.
func SetMaxSlippageBps(cur realm, maxSlippageBps int64) {
	getImplementation().SetMaxSlippageBps(0, cur, maxSlippageBps)
}

state.gno

package limit

import (
	_ "gno.land/r/gnoswap/rbac/v1" // registers the roles read through access

	"errors"

	plimit "gno.land/p/gnoswap/order/limit/v0"
	"gno.land/p/gnoswap/store/v1"
	"gno.land/p/gnoswap/version_manager/v1"
)

var (
	currentAddress address
	kvStore        store.KVStore

	versionManager version_manager.VersionManager
	implementation plimit.ILimitOrder
)

func init(cur realm) {
	currentAddress = cur.Address()
	kvStore = store.NewKVStore(currentAddress)

	versionManager = version_manager.NewVersionManager(
		cur.PkgPath(),
		kvStore,
		initializeDomainStore,
	)

	implementation = nil
}

func initializeDomainStore(_ int, _ realm, kvStore store.KVStore) any {
	return NewLimitOrderStore(kvStore)
}

// Address returns the realm address that escrows order funds.
// Users approve it before CreateOrder.
func Address() address {
	return currentAddress
}

func getImplementation() plimit.ILimitOrder {
	if implementation == nil {
		panic(errImplNotInitialized)
	}

	return implementation
}

func updateImplementation() error {
	result := versionManager.GetCurrentImplementation()
	if result == nil {
		return errors.New(errImplNotInitialized)
	}

	impl, ok := result.(plimit.ILimitOrder)
	if !ok {
		return errors.New(errInvalidImpl)
	}

	implementation = impl

	return nil
}

store.gno

package limit

import (
	"errors"

	plimit "gno.land/p/gnoswap/order/limit/v0"
	"gno.land/p/gnoswap/store/v1"
	bptree "gno.land/p/nt/bptree/v0"
	ufmt "gno.land/p/nt/ufmt/v0"
)

// NewBPTreeN allocates an empty B+tree in the order/limit realm.
// Implementations create the store trees through it,
// so the trees are owned by the realm that stores them.
func NewBPTreeN(fanout int) *bptree.BPTree {
	return bptree.NewBPTreeN(fanout)
}

// StoreKey is a key of the limit order KV store.
type StoreKey string

func (s StoreKey) String() string {
	return string(s)
}

// Store layout. Tree keys are built by the plimit key helpers.
//
//	orders         OrderKey -> *Order, pending orders only
//	ordersByOwner  OwnerOrderKey -> orderID, pending orders only
//	pendingExecutionFees tokenPath -> int64, held until the protocol fee collector accepts them
//	nextOrderID    uint64
//	config         *Config
const (
	StoreKeyOrders               StoreKey = "orders"
	StoreKeyOrdersByOwner        StoreKey = "ordersByOwner"
	StoreKeyPendingExecutionFees StoreKey = "pendingExecutionFees"
	StoreKeyNextOrderID          StoreKey = "nextOrderID"
	StoreKeyConfig               StoreKey = "config"
)

type limitOrderStore struct {
	kvStore store.KVStore
}

// NewLimitOrderStore wraps the domain KV store.
func NewLimitOrderStore(kvStore store.KVStore) plimit.ILimitOrderStore {
	return &limitOrderStore{kvStore: kvStore}
}

// set writes key after checking that rlm is the current realm.
// The KV store additionally enforces its write ACL for code realms.
func (s *limitOrderStore) set(_ int, rlm realm, key string, value any) error {
	if !rlm.IsCurrent() {
		return errors.New(ErrSpoofedRealm)
	}

	return s.kvStore.Set(0, rlm, key, value)
}

func (s *limitOrderStore) getTree(key StoreKey) *bptree.BPTree {
	tree, err := s.kvStore.GetBPTree(key.String())
	if err != nil {
		panic(err.Error())
	}

	if tree == nil {
		panic(ufmt.Sprintf(errNilValue, key.String()))
	}

	return tree
}

func (s *limitOrderStore) setTree(_ int, rlm realm, key StoreKey, tree *bptree.BPTree) error {
	if !rlm.IsCurrent() {
		return errors.New(ErrSpoofedRealm)
	}

	if tree == nil {
		return ufmt.Errorf(errNilValue, key.String())
	}

	return s.kvStore.Set(0, rlm, key.String(), tree)
}

func (s *limitOrderStore) HasOrders() bool { return s.kvStore.Has(StoreKeyOrders.String()) }

func (s *limitOrderStore) GetOrders() *bptree.BPTree { return s.getTree(StoreKeyOrders) }

func (s *limitOrderStore) SetOrders(_ int, rlm realm, orders *bptree.BPTree) error {
	return s.setTree(0, rlm, StoreKeyOrders, orders)
}

func (s *limitOrderStore) HasOrdersByOwner() bool {
	return s.kvStore.Has(StoreKeyOrdersByOwner.String())
}

func (s *limitOrderStore) GetOrdersByOwner() *bptree.BPTree {
	return s.getTree(StoreKeyOrdersByOwner)
}

func (s *limitOrderStore) SetOrdersByOwner(_ int, rlm realm, ordersByOwner *bptree.BPTree) error {
	return s.setTree(0, rlm, StoreKeyOrdersByOwner, ordersByOwner)
}

func (s *limitOrderStore) HasPendingExecutionFees() bool {
	return s.kvStore.Has(StoreKeyPendingExecutionFees.String())
}

func (s *limitOrderStore) GetPendingExecutionFees() *bptree.BPTree {
	return s.getTree(StoreKeyPendingExecutionFees)
}

func (s *limitOrderStore) SetPendingExecutionFees(_ int, rlm realm, pendingExecutionFees *bptree.BPTree) error {
	return s.setTree(0, rlm, StoreKeyPendingExecutionFees, pendingExecutionFees)
}

func (s *limitOrderStore) HasNextOrderID() bool {
	return s.kvStore.Has(StoreKeyNextOrderID.String())
}

func (s *limitOrderStore) GetNextOrderID() uint64 {
	id, err := s.kvStore.GetUint64(StoreKeyNextOrderID.String())
	if err != nil {
		panic(err.Error())
	}

	return id
}

func (s *limitOrderStore) SetNextOrderID(_ int, rlm realm, id uint64) error {
	return s.set(0, rlm, StoreKeyNextOrderID.String(), id)
}

func (s *limitOrderStore) HasConfig() bool { return s.kvStore.Has(StoreKeyConfig.String()) }

func (s *limitOrderStore) GetConfig() *plimit.Config {
	result, err := s.kvStore.Get(StoreKeyConfig.String())
	if err != nil {
		panic(err.Error())
	}

	config, ok := result.(*plimit.Config)
	if !ok || config == nil {
		panic(ufmt.Sprintf(errInvalidConfigType, result))
	}

	return config
}

func (s *limitOrderStore) SetConfig(_ int, rlm realm, config *plimit.Config) error {
	if !rlm.IsCurrent() {
		return errors.New(ErrSpoofedRealm)
	}

	if config == nil {
		return errors.New(errNilConfig)
	}

	return s.kvStore.Set(0, rlm, StoreKeyConfig.String(), config)
}

swap_callback.gno

package limit

import (
	"errors"

	prbac "gno.land/p/gnoswap/rbac/v1"
	"gno.land/r/gnoswap/access/v1"
	"gno.land/r/gnoswap/common"
	"gno.land/r/gnoswap/pool"
)

// NewSwapCallback binds payment to this proxy's custody, the order's input
// token and its input budget. Only code already executing in the proxy's current
// realm context can create it. The closure is declared here so pool callbacks
// retain proxy custody rather than paying from an implementation realm.
func NewSwapCallback(_ int, rlm realm, tokenIn string, zeroForOne bool, maxAmountIn int64) func(cur realm, amount0Delta, amount1Delta int64, marker *pool.CallbackMarker) error {
	if !rlm.IsCurrent() || rlm.Address() != Address() || tokenIn == "" || maxAmountIn <= 0 {
		panic(errInvalidSwapCallback)
	}

	poolAddress := access.MustGetAddress(prbac.ROLE_POOL.String())
	remaining := maxAmountIn

	return func(cur realm, amount0Delta, amount1Delta int64, marker *pool.CallbackMarker) error {
		if !cur.IsCurrent() || cur.Address() != Address() || cur.Previous().Address() != poolAddress || marker == nil {
			return errors.New(errInvalidSwapCallback)
		}

		input, output := amount0Delta, amount1Delta
		if !zeroForOne {
			input, output = amount1Delta, amount0Delta
		}

		if input <= 0 || output > 0 || input > remaining {
			return errors.New(errInvalidSwapCallback)
		}

		remaining -= input

		return common.Transfer(0, cur, tokenIn, poolAddress, input)
	}
}

upgrade.gno

package limit

import (
	plimit "gno.land/p/gnoswap/order/limit/v0"

	"gno.land/r/gnoswap/access/v1"
)

// RegisterInitializer registers an implementation version.
// Each version calls it from init with a factory that receives the shared store.
// Only packages under this realm's path may register,
// and the first registration becomes active.
// A nil initializer is rejected before its version path is registered.
func RegisterInitializer(cur realm, initializer func(_ int, rlm realm, orderStore plimit.ILimitOrderStore) plimit.ILimitOrder) {
	if initializer == nil {
		panic(ErrNilInitializer)
	}

	initializerFunc := func(_ int, rlm realm, domainStore any) any {
		access.AssertIsRlmCurrent(0, rlm)

		orderStore, ok := domainStore.(plimit.ILimitOrderStore)
		if !ok {
			panic(errInvalidDomainStore)
		}

		return initializer(0, rlm, orderStore)
	}

	err := versionManager.RegisterInitializer(0, cur, initializerFunc)
	if err != nil {
		panic(err.Error())
	}

	err = updateImplementation()
	if err != nil {
		panic(err.Error())
	}
}

// UpgradeImpl activates a previously registered version by package path.
// Admin or governance only.
func UpgradeImpl(cur realm, packagePath string) {
	caller := cur.Previous().Address()
	access.AssertIsAdminOrGovernance(caller)

	err := versionManager.ChangeImplementation(0, cur, packagePath)
	if err != nil {
		panic(err.Error())
	}

	err = updateImplementation()
	if err != nil {
		panic(err.Error())
	}
}

// GetImplementationPackagePath returns the active implementation path.
func GetImplementationPackagePath() string {
	return versionManager.GetCurrentPackagePath()
}