delegation.gno

  1package staker
  2
  3import bptree "gno.land/p/nt/bptree/v0"
  4
  5// DelegationType represents the type of delegation operation
  6type DelegationType string
  7
  8const (
  9	DelegateType   DelegationType = "DELEGATE"
 10	UnDelegateType DelegationType = "UNDELEGATE"
 11)
 12
 13// String returns the textual operation name represented by the delegation type.
 14//
 15// Returns:
 16//   - string: "DELEGATE", "UNDELEGATE", or the underlying value for another type.
 17func (d DelegationType) String() string { return string(d) }
 18
 19// IsDelegate reports whether the operation type is DelegateType.
 20//
 21// Returns:
 22//   - bool: true only when d represents a delegation operation.
 23func (d DelegationType) IsDelegate() bool { return d == DelegateType }
 24
 25// IsUnDelegate reports whether the operation type is UnDelegateType.
 26//
 27// Returns:
 28//   - bool: true only when d represents an undelegation operation.
 29func (d DelegationType) IsUnDelegate() bool { return d == UnDelegateType }
 30
 31// Delegation represents a delegation between two addresses
 32type Delegation struct {
 33	id               int64
 34	delegateAmount   int64
 35	unDelegateAmount int64
 36	collectedAmount  int64
 37	delegateFrom     address
 38	delegateTo       address
 39	createdHeight    int64
 40	createdAt        int64
 41	withdraws        []DelegationWithdraw
 42}
 43
 44// NewDelegation creates a delegation record with no undelegated or collected amount.
 45//
 46// Parameters:
 47//   - id: unique identifier assigned to this delegation record.
 48//   - delegateFrom: address whose tokens are delegated.
 49//   - delegateTo: address receiving the delegated voting power.
 50//   - delegateAmount: initial delegated token amount in the smallest token unit.
 51//   - createdHeight: block height at which the delegation was created.
 52//   - createdAt: Unix timestamp at which the delegation was created.
 53//
 54// Returns:
 55//   - *Delegation: initialized delegation with empty withdrawal history.
 56func NewDelegation(
 57	id int64,
 58	delegateFrom, delegateTo address,
 59	delegateAmount, createdHeight, createdAt int64,
 60) *Delegation {
 61	return &Delegation{
 62		id:               id,
 63		delegateFrom:     delegateFrom,
 64		delegateTo:       delegateTo,
 65		delegateAmount:   delegateAmount,
 66		createdHeight:    createdHeight,
 67		createdAt:        createdAt,
 68		unDelegateAmount: 0,
 69		collectedAmount:  0,
 70		withdraws:        make([]DelegationWithdraw, 0),
 71	}
 72}
 73
 74// Basic getters
 75// ID returns the unique identifier of the delegation record.
 76//
 77// Returns:
 78//   - int64: delegation identifier assigned at creation.
 79func (d *Delegation) ID() int64 { return d.id }
 80
 81// DelegateFrom returns the address that supplied the delegated tokens.
 82//
 83// Returns:
 84//   - address: delegator address recorded on the delegation.
 85func (d *Delegation) DelegateFrom() address { return d.delegateFrom }
 86
 87// DelegateTo returns the address receiving the delegated voting power.
 88//
 89// Returns:
 90//   - address: delegatee address recorded on the delegation.
 91func (d *Delegation) DelegateTo() address { return d.delegateTo }
 92
 93// CreatedAt returns the Unix timestamp recorded when the delegation was created.
 94//
 95// Returns:
 96//   - int64: creation timestamp in Unix seconds.
 97func (d *Delegation) CreatedAt() int64 { return d.createdAt }
 98
 99// Amount getters
100// TotalDelegatedAmount returns the current amount still actively delegated.
101//
102// Returns:
103//   - int64: active delegated token amount in the smallest token unit.
104func (d *Delegation) TotalDelegatedAmount() int64 { return d.delegateAmount }
105
106// UnDelegatedAmount returns the amount moved into undelegation lockup.
107//
108// Returns:
109//   - int64: token amount awaiting collection after its lockup period.
110func (d *Delegation) UnDelegatedAmount() int64 { return d.unDelegateAmount }
111
112// CollectedAmount returns the amount already collected from undelegation.
113//
114// Returns:
115//   - int64: token amount released from this delegation.
116func (d *Delegation) CollectedAmount() int64 { return d.collectedAmount }
117
118// Withdraws getters
119// Withdraws returns the delegation's withdrawal records.
120//
121// Returns:
122//   - []DelegationWithdraw: withdrawal entries tracked for this delegation.
123func (d *Delegation) Withdraws() []DelegationWithdraw { return d.withdraws }
124
125// Setters
126// SetUnDelegateAmount replaces the amount currently in undelegation lockup.
127//
128// Parameters:
129//   - amount: token amount awaiting collection in the smallest token unit.
130func (d *Delegation) SetUnDelegateAmount(amount int64) {
131	d.unDelegateAmount = amount
132}
133
134// SetCollectedAmount replaces the amount already collected from this delegation.
135//
136// Parameters:
137//   - amount: released token amount in the smallest token unit.
138func (d *Delegation) SetCollectedAmount(amount int64) {
139	d.collectedAmount = amount
140}
141
142// AddWithdraw appends a withdrawal record to the delegation history.
143//
144// Parameters:
145//   - withdraw: withdrawal record to append, including its amount and unlock timing.
146func (d *Delegation) AddWithdraw(withdraw DelegationWithdraw) {
147	d.withdraws = append(d.withdraws, withdraw)
148}
149
150// SetWithdraw replaces one withdrawal record at the supplied slice index.
151//
152// Parameters:
153//   - index: zero-based index of the withdrawal entry to replace.
154//   - withdraw: replacement withdrawal record.
155func (d *Delegation) SetWithdraw(index int, withdraw DelegationWithdraw) {
156	d.withdraws[index] = withdraw
157}
158
159// SetWithdraws replaces the complete withdrawal history.
160//
161// Parameters:
162//   - withdraws: withdrawal records to store for this delegation.
163func (d *Delegation) SetWithdraws(withdraws []DelegationWithdraw) {
164	d.withdraws = withdraws
165}
166
167// Clone returns a deep copy of the delegation and its withdrawal slice.
168//
169// Returns:
170//   - *Delegation: copied delegation, or nil when the receiver is nil.
171func (d *Delegation) Clone() *Delegation {
172	if d == nil {
173		return nil
174	}
175
176	clonedWithdraws := make([]DelegationWithdraw, len(d.withdraws))
177	copy(clonedWithdraws, d.withdraws)
178
179	return &Delegation{
180		id:               d.id,
181		delegateAmount:   d.delegateAmount,
182		unDelegateAmount: d.unDelegateAmount,
183		collectedAmount:  d.collectedAmount,
184		delegateFrom:     d.delegateFrom,
185		delegateTo:       d.delegateTo,
186		createdHeight:    d.createdHeight,
187		createdAt:        d.createdAt,
188		withdraws:        clonedWithdraws,
189	}
190}
191
192// NewDelegationTree creates an empty tree for delegatee-to-delegation-ID mappings.
193//
194// Returns:
195//   - *bptree.BPTree: empty tree configured for delegation lookup entries.
196func NewDelegationTree() *bptree.BPTree {
197	return bptree.NewBPTreeN(16)
198}
199
200// NewUserDelegationTree creates an empty tree for user delegation mappings.
201// Returns:
202//   - *bptree.BPTree: empty tree configured for user delegation entries.
203func NewUserDelegationTree() *bptree.BPTree {
204	return bptree.NewBPTreeN(16)
205}