accum

package
v0.0.15 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 4, 2024 License: Apache-2.0 Imports: 13 Imported by: 32

Documentation

Overview

package accumulator allows one to define an accumulator to accommodate constant-rate (linear) distribution mechanisms with constant runtime and linear memory

Index

Constants

View Source 
const (
	KeySeparator = "||" // needs to be different from other modules.

)

Variables

View Source 
var (
	ErrInvalidLengthAccum        = fmt.Errorf("proto: negative length found during unmarshaling")
	ErrIntOverflowAccum          = fmt.Errorf("proto: integer overflow")
	ErrUnexpectedEndOfGroupAccum = fmt.Errorf("proto: unexpected end of group")
)
View Source 
var (
	ZeroSharesError = errors.New("shares must be non-zero")
)

Functions

func FormatPositionPrefixKey added in v0.0.5 

func FormatPositionPrefixKey(accumName, name string) []byte

FormatPositionPrefixKey returns the key prefix used specifically for position values in the KVStore. Returns "accum||pos||{accumName}||{name}" as bytes. We use a different key separator, namely `||`, to separate the accumulator name and the position name. This is because we require that accumName does not contain this as a substring.

func GetTotalRewards added in v0.0.5 

func GetTotalRewards(accum *AccumulatorObject, position Record) sdk.DecCoins

Gets total unclaimed rewards, including existing and newly accrued unclaimed rewards

func MakeAccumulator 

func MakeAccumulator(accumStore store.KVStore, accumName string) error

Makes a new accumulator at store/accum/{accumName} Returns error if: * accumName already exists * there's some overlapping keys * Accumulator name contains "||"

func MakeAccumulatorWithValueAndShare added in v0.0.5 

func MakeAccumulatorWithValueAndShare(accumStore store.KVStore, accumName string, accumValue sdk.DecCoins, totalShares osmomath.Dec) error

Makes a new accumulator at store/accum/{accumName} Returns error if: * accumName already exists * there's some overlapping keys * Accumulator name contains "||"

func OverwriteAccumulatorUnsafe added in v0.0.9 

func OverwriteAccumulatorUnsafe(accumStore store.KVStore, accumName string, accumValue sdk.DecCoins, totalShares osmomath.Dec) error

OverwriteAccumulatorUnsafe overwrites the accumulator with the given name in accumStore. Use with caution as this method is only meant for use in migrations.

Types

type AccumDoesNotExistError 

type AccumDoesNotExistError struct {
	AccumName string
}

func (AccumDoesNotExistError) Error 

func (e AccumDoesNotExistError) Error() string

type AccumulatorContent 

type AccumulatorContent struct {
	AccumValue  github_com_cosmos_cosmos_sdk_types.DecCoins `` /* 138-byte string literal not displayed */
	TotalShares cosmossdk_io_math.LegacyDec                 `protobuf:"bytes,2,opt,name=total_shares,json=totalShares,proto3,customtype=cosmossdk.io/math.LegacyDec" json:"total_shares"`
}

AccumulatorContent is the state-entry for the global accumulator. It contains the name of the global accumulator and the total value of shares belonging to it from all positions.

func (*AccumulatorContent) Descriptor 

func (*AccumulatorContent) Descriptor() ([]byte, []int)

func (*AccumulatorContent) GetAccumValue 

func (m *AccumulatorContent) GetAccumValue() github_com_cosmos_cosmos_sdk_types.DecCoins

func (*AccumulatorContent) Marshal 

func (m *AccumulatorContent) Marshal() (dAtA []byte, err error)

func (*AccumulatorContent) MarshalTo 

func (m *AccumulatorContent) MarshalTo(dAtA []byte) (int, error)

func (*AccumulatorContent) MarshalToSizedBuffer 

func (m *AccumulatorContent) MarshalToSizedBuffer(dAtA []byte) (int, error)

func (*AccumulatorContent) ProtoMessage 

func (*AccumulatorContent) ProtoMessage()

func (*AccumulatorContent) Reset 

func (m *AccumulatorContent) Reset()

func (*AccumulatorContent) Size 

func (m *AccumulatorContent) Size() (n int)

func (*AccumulatorContent) String 

func (m *AccumulatorContent) String() string

func (*AccumulatorContent) Unmarshal 

func (m *AccumulatorContent) Unmarshal(dAtA []byte) error

func (*AccumulatorContent) XXX_DiscardUnknown 

func (m *AccumulatorContent) XXX_DiscardUnknown()

func (*AccumulatorContent) XXX_Marshal 

func (m *AccumulatorContent) XXX_Marshal(b []byte, deterministic bool) ([]byte, error)

func (*AccumulatorContent) XXX_Merge 

func (m *AccumulatorContent) XXX_Merge(src proto.Message)

func (*AccumulatorContent) XXX_Size 

func (m *AccumulatorContent) XXX_Size() int

func (*AccumulatorContent) XXX_Unmarshal 

func (m *AccumulatorContent) XXX_Unmarshal(b []byte) error

type AccumulatorObject 

type AccumulatorObject struct {
	// contains filtered or unexported fields
}

We keep this object as a way to interface with the methods, even though only the Accumulator inside is stored in state

func GetAccumulator 

func GetAccumulator(accumStore store.KVStore, accumName string) (*AccumulatorObject, error)

Gets the current value of the accumulator corresponding to accumName in accumStore

func (*AccumulatorObject) AddToAccumulator 

func (accum *AccumulatorObject) AddToAccumulator(amt sdk.DecCoins)

AddToAccumulator updates the accumulator's value by amt. It does so by increasing the value of the accumulator by the given amount. Persists to store. Mutates the receiver.

func (*AccumulatorObject) AddToPosition 

func (accum *AccumulatorObject) AddToPosition(name string, newShares osmomath.Dec) error

AddToPosition adds newShares of shares to an existing position with the given name. This is functionally equivalent to claiming rewards, closing down the position, and opening a fresh one with the new number of shares. We can represent this behavior by claiming rewards and moving up the accumulator start value to its current value.

An alternative approach is to simply generate an additional position every time an address adds to its position. We do not pursue this path because we want to ensure that withdrawal and claiming functions remain constant time and do not scale with the number of times a user has added to their position.

Returns nil on success. Returns error when: - newShares are negative or zero. - there is no existing position at the given address - other internal or database error occurs.

func (*AccumulatorObject) AddToPositionIntervalAccumulation added in v0.0.5 

func (accum *AccumulatorObject) AddToPositionIntervalAccumulation(name string, newShares osmomath.Dec, intervalAccumulationPerShare sdk.DecCoins) error

AddToPositionIntervalAccumulation adds newShares of shares to an existing position with the given name. This is functionally equivalent to claiming rewards, closing down the position, and opening a fresh one with the new number of shares. The accumulator of the new position is set to given intervalAccumulationPerShare. intervalAccumulationPerShare DecCoin values must be non-negative. They must also be a superset of the old accumulator value associated with the position. Providing intervalAccumulationPerShare is useful for when the accumulation happens at a sub-range of the full accumulator rewards range. For example, a concentrated liquidity narrow range position.

An alternative approach is to simply generate an additional position every time an address adds to its position. We do not pursue this path because we want to ensure that withdrawal and claiming functions remain constant time and do not scale with the number of times a user has added to their position.

Returns nil on success. Returns error when: - newShares are negative or zero. - there is no existing position at the given address - other internal or database error occurs.

func (*AccumulatorObject) AddToUnclaimedRewards added in v0.0.5 

func (accum *AccumulatorObject) AddToUnclaimedRewards(positionName string, rewardsToAddTotal sdk.DecCoins) error

AddToUnclaimedRewards adds the given amount of rewards to the unclaimed rewards for the given position. Returns error if no position exists for the given position name. Returns error if any database errors occur or if neggative rewards are provided.

func (*AccumulatorObject) ClaimRewards 

func (accum *AccumulatorObject) ClaimRewards(positionName string) (sdk.Coins, sdk.DecCoins, error)

ClaimRewards claims the rewards for the given address, and returns the amount of rewards claimed. Upon claiming the rewards, the position at the current address is reset to have no unclaimed rewards. The position's accumulator is also set to the current accumulator value. The position state is removed if the position shares is equal to zero.

Returns error if - no position exists for the given address - any database errors occur.

func (*AccumulatorObject) DeletePosition added in v0.0.5 

func (accum *AccumulatorObject) DeletePosition(positionName string) (sdk.DecCoins, error)

DeletePosition claims rewards and deletes the position from the accumulator state. Prior to deletion, claims rewards and returns them. Decrements total accumulator share counter by the number of shares in the position tracker. Returns error if: - fails to fetch a position - fails to claim rewards - fails to retrieve total accumulator shares

func (AccumulatorObject) GetName added in v0.0.5 

func (accum AccumulatorObject) GetName() string

GetValue returns the current value of the accumulator.

func (AccumulatorObject) GetPosition added in v0.0.5 

func (accum AccumulatorObject) GetPosition(name string) (Record, error)

GetPosition returns the position associated with the given address. If the position does not exist, returns an error.

func (*AccumulatorObject) GetPositionSize 

func (accum *AccumulatorObject) GetPositionSize(name string) (osmomath.Dec, error)

GetPositionSize returns the number of shares the position with the given name has in the accumulator. Returns error if position does not exist or if fails to retrieve position from state.

func (AccumulatorObject) GetTotalShares 

func (accum AccumulatorObject) GetTotalShares() osmomath.Dec

GetTotalShares returns the total number of shares in the accumulator

func (AccumulatorObject) GetValue 

func (accum AccumulatorObject) GetValue() sdk.DecCoins

GetValue returns the current value of the accumulator.

func (AccumulatorObject) HasPosition 

func (accum AccumulatorObject) HasPosition(name string) bool

HasPosition returns true if a position with the given name exists, false otherwise.

func (AccumulatorObject) MustGetPosition added in v0.0.5 

func (accum AccumulatorObject) MustGetPosition(name string) Record

MustGetPosition returns the position associated with the given address. No errors in position retrieval are allowed.

func (*AccumulatorObject) NewPosition 

func (accum *AccumulatorObject) NewPosition(name string, numShareUnits osmomath.Dec, options *Options) error

NewPosition creates a new position for the given name, with the given number of share units. The name can be an owner's address, or any other unique identifier for a position. It takes a snapshot of the current accumulator value, and sets the position's initial value to that. The position is initialized with empty unclaimed rewards If there is an existing position for the given address, it is overwritten.

func (*AccumulatorObject) NewPositionIntervalAccumulation added in v0.0.5 

func (accum *AccumulatorObject) NewPositionIntervalAccumulation(name string, numShareUnits osmomath.Dec, intervalAccumulationPerShare sdk.DecCoins, options *Options) error

NewPositionIntervalAccumulation creates a new position for the given name, with the given number of share units. The name can be an owner's address, or any other unique identifier for a position. It sets the position's accumulator to the given value of intervalAccumulationPerShare. This is useful for when the accumulation happens at a sub-range of the full accumulator rewards range. For example, a concentrated liquidity narrow range position. intervalAccumulationPerShare DecCoin values are allowed to be negative. The position is initialized with empty unclaimed rewards If there is an existing position for the given address, it is overwritten.

func (*AccumulatorObject) RemoveFromPosition 

func (accum *AccumulatorObject) RemoveFromPosition(name string, numSharesToRemove osmomath.Dec) error

RemovePosition removes the specified number of shares from a position. Specifically, it claims the unclaimed and newly accrued rewards and returns them alongside the redeemed shares. Then, it overwrites the position record with the updated number of shares. Since it accrues rewards, it also moves up the position's accumulator value to the current accum val.

func (*AccumulatorObject) RemoveFromPositionIntervalAccumulation added in v0.0.5 

func (accum *AccumulatorObject) RemoveFromPositionIntervalAccumulation(name string, numSharesToRemove osmomath.Dec, intervalAccumulationPerShare sdk.DecCoins) error

RemovePositionIntervalAccumulation removes the specified number of shares from a position. Specifically, it claims the unclaimed and newly accrued rewards and returns them alongside the redeemed shares. Then, it overwrites the position record with the updated number of shares. Since it accrues rewards, it also resets the position's accumulator value to the given intervalAccumulationPerShare. Providing intervalAccumulationPerShare is useful for when the accumulation happens at a sub-range of the full accumulator rewards range. For example, a concentrated liquidity narrow range position. All intervalAccumulationPerShare DecCoin values must be non-negative. They must also be a superset of the old accumulator value associated with the position.

func (*AccumulatorObject) SetPositionIntervalAccumulation added in v0.0.5 

func (accum *AccumulatorObject) SetPositionIntervalAccumulation(name string, intervalAccumulationPerShare sdk.DecCoins) error

SetPositionIntervalAccumulation sets the position's accumulator to the given value. This is useful for when the accumulation happens at a sub-range of the full accumulator rewards range. For example, a concentrated liquidity narrow range position. This method does not update shares or attempt to claim rewards. The new accumulator value must be greater than or equal to the old accumulator value. Returns nil on success, error otherwise.

func (*AccumulatorObject) UpdatePosition 

func (accum *AccumulatorObject) UpdatePosition(name string, numShares osmomath.Dec) error

UpdatePosition updates the position with the given name by adding or removing the given number of shares. If numShares is positive, it is equivalent to calling AddToPosition. If numShares is negative, it is equivalent to calling RemoveFromPosition. Also, it moves up the position's accumulator value to the current accum value. Fails with error if numShares is zero. Returns nil on success.

func (*AccumulatorObject) UpdatePositionIntervalAccumulation added in v0.0.5 

func (accum *AccumulatorObject) UpdatePositionIntervalAccumulation(name string, numShares osmomath.Dec, intervalAccumulationPerShare sdk.DecCoins) error

UpdatePositionIntervalAccumulation updates the position with the given name by adding or removing the given number of shares. If numShares is positive, it is equivalent to calling AddToPositionIntervalAccumulation. If numShares is negative, it is equivalent to calling RemoveFromPositionIntervalAccumulation. Fails with error if numShares is zero. Returns nil on success. It also resets the position's accumulator value to the given intervalAccumulationPerShare. Providing intervalAccumulationPerShare is useful for when the accumulation happens at a sub-range of the full accumulator rewards range. For example, a concentrated liquidity narrow range position. All intervalAccumulationPerShare DecCoin value must be non-negative. They must also be a superset of the old accumulator value associated with the position.

type NegativeAccDifferenceError 

type NegativeAccDifferenceError struct {
	AccumulatorDifference sdk.DecCoins
}

func (NegativeAccDifferenceError) Error 

func (e NegativeAccDifferenceError) Error() string

type NegativeIntervalAccumulationPerShareError added in v0.0.5 

type NegativeIntervalAccumulationPerShareError struct {
	IntervalAccumulationPerShare sdk.DecCoins
}

func (NegativeIntervalAccumulationPerShareError) Error added in v0.0.5 

func (e NegativeIntervalAccumulationPerShareError) Error() string

type NegativeRewardsAdditionError added in v0.0.5 

type NegativeRewardsAdditionError struct {
	AccumName    string
	PositionName string
}

func (NegativeRewardsAdditionError) Error added in v0.0.5 

func (e NegativeRewardsAdditionError) Error() string

type NoPositionError 

type NoPositionError struct {
	Name string
}

func (NoPositionError) Error 

func (e NoPositionError) Error() string

type Options 

type Options struct {
}

func (*Options) Descriptor 

func (*Options) Descriptor() ([]byte, []int)

func (*Options) Marshal 

func (m *Options) Marshal() (dAtA []byte, err error)

func (*Options) MarshalTo 

func (m *Options) MarshalTo(dAtA []byte) (int, error)

func (*Options) MarshalToSizedBuffer 

func (m *Options) MarshalToSizedBuffer(dAtA []byte) (int, error)

func (*Options) ProtoMessage 

func (*Options) ProtoMessage()

func (*Options) Reset 

func (m *Options) Reset()

func (*Options) Size 

func (m *Options) Size() (n int)

func (*Options) String 

func (m *Options) String() string

func (*Options) Unmarshal 

func (m *Options) Unmarshal(dAtA []byte) error

func (*Options) XXX_DiscardUnknown 

func (m *Options) XXX_DiscardUnknown()

func (*Options) XXX_Marshal 

func (m *Options) XXX_Marshal(b []byte, deterministic bool) ([]byte, error)

func (*Options) XXX_Merge 

func (m *Options) XXX_Merge(src proto.Message)

func (*Options) XXX_Size 

func (m *Options) XXX_Size() int

func (*Options) XXX_Unmarshal 

func (m *Options) XXX_Unmarshal(b []byte) error

type Record 

type Record struct {
	// num_shares is the number of shares belonging to the position associated
	// with this record.
	NumShares cosmossdk_io_math.LegacyDec `protobuf:"bytes,1,opt,name=num_shares,json=numShares,proto3,customtype=cosmossdk.io/math.LegacyDec" json:"num_shares"`
	// accum_value_per_share is the subset of coins per shar of the global
	// accumulator value that allows to infer how much a position is entitled to
	// per share that it owns.
	//
	// In the default case with no intervals, this value equals to the global
	// accumulator value at the time of the position creation, the last update or
	// reward claim.
	//
	// In the interval case such as concentrated liquidity, this value equals to
	// the global growth of rewards inside the interval during one of: the time of
	// the position creation, the last update or reward claim. Note, that
	// immediately prior to claiming or updating rewards, this value must be
	// updated to "the growth inside at the time of last update + the growth
	// outside at the time of the current block". This is so that the claiming
	// logic can subtract this updated value from the global accumulator value to
	// get the growth inside the interval from the time of last update up until
	// the current block time.
	AccumValuePerShare github_com_cosmos_cosmos_sdk_types.DecCoins `` /* 166-byte string literal not displayed */
	// unclaimed_rewards_total is the total amount of unclaimed rewards that the
	// position is entitled to. This value is updated whenever shares are added or
	// removed from an existing position. We also expose API for manually updating
	// this value for some custom use cases such as merging pre-existing positions
	// into a single one.
	UnclaimedRewardsTotal github_com_cosmos_cosmos_sdk_types.DecCoins `` /* 173-byte string literal not displayed */
	Options               *Options                                    `protobuf:"bytes,4,opt,name=options,proto3" json:"options,omitempty"`
}

Record corresponds to an individual position value belonging to the global accumulator.

func GetPosition added in v0.0.5 

func GetPosition(accum *AccumulatorObject, name string) (Record, error)

Gets addr's current position from store

func (*Record) Descriptor 

func (*Record) Descriptor() ([]byte, []int)

func (*Record) GetAccumValuePerShare added in v0.0.5 

func (m *Record) GetAccumValuePerShare() github_com_cosmos_cosmos_sdk_types.DecCoins

func (*Record) GetOptions 

func (m *Record) GetOptions() *Options

func (*Record) GetUnclaimedRewardsTotal added in v0.0.5 

func (m *Record) GetUnclaimedRewardsTotal() github_com_cosmos_cosmos_sdk_types.DecCoins

func (*Record) Marshal 

func (m *Record) Marshal() (dAtA []byte, err error)

func (*Record) MarshalTo 

func (m *Record) MarshalTo(dAtA []byte) (int, error)

func (*Record) MarshalToSizedBuffer 

func (m *Record) MarshalToSizedBuffer(dAtA []byte) (int, error)

func (*Record) ProtoMessage 

func (*Record) ProtoMessage()

func (*Record) Reset 

func (m *Record) Reset()

func (*Record) Size 

func (m *Record) Size() (n int)

func (*Record) String 

func (m *Record) String() string

func (*Record) Unmarshal 

func (m *Record) Unmarshal(dAtA []byte) error

func (*Record) XXX_DiscardUnknown 

func (m *Record) XXX_DiscardUnknown()

func (*Record) XXX_Marshal 

func (m *Record) XXX_Marshal(b []byte, deterministic bool) ([]byte, error)

func (*Record) XXX_Merge 

func (m *Record) XXX_Merge(src proto.Message)

func (*Record) XXX_Size 

func (m *Record) XXX_Size() int

func (*Record) XXX_Unmarshal 

func (m *Record) XXX_Unmarshal(b []byte) error

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.