Skip to content

Commit 2fc6c1b

Browse files
authored
Settle finished proposal deposits over multiple blocks (#4707)
On the incremental tally path, `EndBlocker` burns or refunds every deposit record of a proposal in the block where the proposal expires or finishes tallying, so the work in that block grows with the number of deposit records. The rest of the per-block governance work, vote tallying and tally cleanup, already runs within a fixed budget. `EndBlocker` now records the outcome with `ScheduleDepositSettlement` under the new `DepositSettlementKeyPrefix` (`0x46`). `SettleDeposits` then burns or refunds at most `MaxDepositsSettledPerBlock` (1000) records per block, lowest proposal ID first. A proposal without deposits is not queued, and a queued proposal with no records left counts as one record, so each block handles at most 1000 queue entries. It resumes from a stored cursor, so records kept for depositors that cannot receive funds are skipped rather than scanned again. It runs at the end of `EndBlocker` on every return path, so tally work cannot starve it, and a proposal with up to 1000 deposits still settles in the block it finishes. Each record is burned or refunded and then deleted in one step, so `ModuleAccountInvariant` holds after every block. Proposal status, handler execution and expiry are unchanged. `DeleteDeposits` and `RefundDeposits` behave as before on the legacy path and now share the per-record helpers. This breaks the app hash: it adds store state and changes the block in which large deposit sets are burned or refunded. It only affects the incremental tally path, which is enabled by the v6.8 upgrade, so no migration is needed. The existing gov tests pass unchanged. New tests cover the budget across proposals, resuming past a blocked depositor, supply and balance accounting, an expiry with 1,001 deposits that settles over two blocks, skipping proposals without deposits, and counting queue entries with no records.
1 parent 7839d4d commit 2fc6c1b

5 files changed

Lines changed: 259 additions & 30 deletions

File tree

‎sei-cosmos/x/gov/abci.go‎

Lines changed: 8 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,9 @@ var logger = seilog.NewLogger("cosmos", "x", "gov")
1515
// MaxVotesProcessedPerBlock is the governance record-work budget shared by delegation updates, backfill, tallying, and cleanup.
1616
const MaxVotesProcessedPerBlock = 1000
1717

18+
// MaxDepositsSettledPerBlock is the number of finished proposals' deposit records burned or refunded per block.
19+
const MaxDepositsSettledPerBlock = 1000
20+
1821
// minTallyCleanupVotesPerBlock reserves part of the budget for completed tally archives.
1922
const minTallyCleanupVotesPerBlock = 100
2023

@@ -34,11 +37,13 @@ func EndBlocker(ctx sdk.Context, keeper keeper.Keeper) {
3437
return
3538
}
3639
keeper.CaptureExactTallyBoundary(ctx)
40+
// Settle after this block's expiries and tallies, including when tally work uses up its budget.
41+
defer keeper.SettleDeposits(ctx, MaxDepositsSettledPerBlock)
3742

38-
// delete inactive proposal from store and its deposits
43+
// delete inactive proposal from store and schedule its deposits to be burned
3944
keeper.IterateInactiveProposalsQueue(ctx, ctx.BlockHeader().Time, func(proposal types.Proposal) bool {
4045
keeper.DeleteProposal(ctx, proposal.ProposalId)
41-
keeper.DeleteDeposits(ctx, proposal.ProposalId)
46+
keeper.ScheduleDepositSettlement(ctx, proposal.ProposalId, true)
4247

4348
// called when proposal become inactive
4449
keeper.AfterProposalFailedMinDeposit(ctx, proposal.ProposalId)
@@ -85,11 +90,7 @@ func EndBlocker(ctx sdk.Context, keeper keeper.Keeper) {
8590
// As a result, the deposits are either deleted or refunded in all casses
8691
// EXCEPT when an expedited proposal fails.
8792
if !proposal.IsExpedited || passes {
88-
if burnDeposits {
89-
keeper.DeleteDeposits(ctx, proposal.ProposalId)
90-
} else {
91-
keeper.RefundDeposits(ctx, proposal.ProposalId)
92-
}
93+
keeper.ScheduleDepositSettlement(ctx, proposal.ProposalId, burnDeposits)
9394
}
9495

9596
keeper.RemoveFromActiveProposalQueue(ctx, proposal.ProposalId, proposal.VotingEndTime)

‎sei-cosmos/x/gov/abci_test.go‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -934,3 +934,31 @@ func getDepositMultiplier(isExpedited bool) int64 {
934934
}
935935
return types.DefaultMinExpeditedDepositTokens.Quo(types.DefaultMinDepositTokens).Int64()
936936
}
937+
938+
func TestEndBlockerSettlesExpiredDepositsAcrossBlocks(t *testing.T) {
939+
app := seiapp.Setup(t, false, false, false)
940+
ctx := app.BaseApp.NewContext(false, tmproto.Header{})
941+
depositors := seiapp.AddTestAddrs(app, ctx, gov.MaxDepositsSettledPerBlock+1, sdk.NewInt(1))
942+
proposal, err := app.GovKeeper.SubmitProposal(ctx, types.ContentFromProposalType("test", "test", types.ProposalTypeText, false))
943+
require.NoError(t, err)
944+
for _, depositor := range depositors {
945+
_, err = app.GovKeeper.AddDeposit(ctx, proposal.ProposalId, depositor, sdk.NewCoins(sdk.NewInt64Coin(sdk.DefaultBondDenom, 1)))
946+
require.NoError(t, err)
947+
}
948+
requireDepositsBacked := func() {
949+
msg, broken := govkeeper.ModuleAccountInvariant(app.GovKeeper, app.BankKeeper)(ctx)
950+
require.False(t, broken, msg)
951+
}
952+
953+
ctx = ctx.WithBlockTime(proposal.DepositEndTime)
954+
gov.EndBlocker(ctx, app.GovKeeper)
955+
_, found := app.GovKeeper.GetProposal(ctx, proposal.ProposalId)
956+
require.False(t, found)
957+
require.Len(t, app.GovKeeper.GetDeposits(ctx, proposal.ProposalId), 1)
958+
requireDepositsBacked()
959+
960+
ctx = ctx.WithBlockTime(ctx.BlockTime().Add(time.Second))
961+
gov.EndBlocker(ctx, app.GovKeeper)
962+
require.Empty(t, app.GovKeeper.GetDeposits(ctx, proposal.ProposalId))
963+
requireDepositsBacked()
964+
}

‎sei-cosmos/x/gov/keeper/deposit.go‎

Lines changed: 118 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -52,17 +52,8 @@ func (keeper Keeper) GetDeposits(ctx sdk.Context, proposalID uint64) (deposits t
5252

5353
// DeleteDeposits deletes all the deposits on a specific proposal without refunding them
5454
func (keeper Keeper) DeleteDeposits(ctx sdk.Context, proposalID uint64) {
55-
store := ctx.KVStore(keeper.storeKey)
56-
5755
keeper.IterateDeposits(ctx, proposalID, func(deposit types.Deposit) bool {
58-
err := keeper.bankKeeper.BurnCoins(ctx, types.ModuleName, deposit.Amount)
59-
if err != nil {
60-
panic(err)
61-
}
62-
63-
depositor := sdk.MustAccAddressFromBech32(deposit.Depositor)
64-
65-
store.Delete(types.DepositKey(proposalID, depositor))
56+
keeper.burnDeposit(ctx, deposit)
6657
return false
6758
})
6859
}
@@ -170,23 +161,127 @@ func (keeper Keeper) AddDeposit(ctx sdk.Context, proposalID uint64, depositorAdd
170161
// their records. Deposits for unpayable recipients remain recorded and backed by
171162
// the governance module balance.
172163
func (keeper Keeper) RefundDeposits(ctx sdk.Context, proposalID uint64) {
164+
keeper.IterateDeposits(ctx, proposalID, func(deposit types.Deposit) bool {
165+
keeper.refundDeposit(ctx, deposit)
166+
return false
167+
})
168+
}
169+
170+
// ScheduleDepositSettlement queues a finished proposal's deposits to be burned or
171+
// refunded by SettleDeposits. A proposal without deposits is not queued.
172+
func (keeper Keeper) ScheduleDepositSettlement(ctx sdk.Context, proposalID uint64, burn bool) {
173+
if !keeper.hasDeposits(ctx, proposalID) {
174+
return
175+
}
176+
ctx.KVStore(keeper.storeKey).Set(types.DepositSettlementKey(proposalID), encodeDepositSettlement(burn, nil))
177+
}
178+
179+
// hasDeposits reports whether a proposal has any deposit record.
180+
func (keeper Keeper) hasDeposits(ctx sdk.Context, proposalID uint64) bool {
181+
iterator := sdk.KVStorePrefixIterator(ctx.KVStore(keeper.storeKey), types.DepositsKey(proposalID))
182+
defer func() { _ = iterator.Close() }()
183+
return iterator.Valid()
184+
}
185+
186+
// SettleDeposits burns or refunds up to maxDeposits queued deposit records, oldest
187+
// proposal first, and returns how many records it processed. A queued proposal
188+
// with no records left counts as one record.
189+
func (keeper Keeper) SettleDeposits(ctx sdk.Context, maxDeposits int) (settled int) {
173190
store := ctx.KVStore(keeper.storeKey)
191+
iterator := sdk.KVStorePrefixIterator(store, types.DepositSettlementKeyPrefix)
192+
defer func() { _ = iterator.Close() }()
174193

175-
keeper.IterateDeposits(ctx, proposalID, func(deposit types.Deposit) bool {
176-
depositor := sdk.MustAccAddressFromBech32(deposit.Depositor)
177-
if keeper.bankKeeper.BlockedAddr(depositor) || !keeper.bankKeeper.CanSendTo(ctx, depositor) {
178-
// Retain the deposit so its record continues to account for the backing
179-
// module balance. Recovering a permanently unreceivable deposit requires
180-
// a migration.
181-
return false
194+
for ; iterator.Valid() && settled < maxDeposits; iterator.Next() {
195+
proposalID := types.SplitDepositSettlementKey(iterator.Key())
196+
burn, cursor := decodeDepositSettlement(iterator.Value())
197+
count, complete, nextCursor := keeper.settleProposalDeposits(ctx, proposalID, burn, maxDeposits-settled, cursor)
198+
settled += max(count, 1)
199+
200+
settlementKey := types.DepositSettlementKey(proposalID)
201+
if complete {
202+
store.Delete(settlementKey)
203+
} else {
204+
store.Set(settlementKey, encodeDepositSettlement(burn, nextCursor))
182205
}
206+
}
207+
return settled
208+
}
209+
210+
func (keeper Keeper) settleProposalDeposits(
211+
ctx sdk.Context,
212+
proposalID uint64,
213+
burn bool,
214+
maxDeposits int,
215+
after []byte,
216+
) (settled int, complete bool, cursor []byte) {
217+
store := ctx.KVStore(keeper.storeKey)
218+
depositsPrefix := types.DepositsKey(proposalID)
219+
start := depositsPrefix
220+
if len(after) != 0 {
221+
start = sdk.PrefixEndBytes(after)
222+
}
223+
iterator := store.Iterator(start, sdk.PrefixEndBytes(depositsPrefix))
224+
defer func() { _ = iterator.Close() }()
183225

184-
err := keeper.bankKeeper.SendCoinsFromModuleToAccount(ctx, types.ModuleName, depositor, deposit.Amount)
185-
if err != nil {
186-
panic(err)
226+
for ; iterator.Valid() && settled < maxDeposits; iterator.Next() {
227+
cursor = append(cursor[:0], iterator.Key()...)
228+
var deposit types.Deposit
229+
keeper.cdc.MustUnmarshal(iterator.Value(), &deposit)
230+
if burn {
231+
keeper.burnDeposit(ctx, deposit)
232+
} else {
233+
keeper.refundDeposit(ctx, deposit)
187234
}
235+
settled++
236+
}
188237

189-
store.Delete(types.DepositKey(proposalID, depositor))
190-
return false
191-
})
238+
complete = !iterator.Valid()
239+
return settled, complete, cursor
240+
}
241+
242+
// burnDeposit burns a deposit's amount and deletes its record.
243+
func (keeper Keeper) burnDeposit(ctx sdk.Context, deposit types.Deposit) {
244+
if err := keeper.bankKeeper.BurnCoins(ctx, types.ModuleName, deposit.Amount); err != nil {
245+
panic(err)
246+
}
247+
depositor := sdk.MustAccAddressFromBech32(deposit.Depositor)
248+
ctx.KVStore(keeper.storeKey).Delete(types.DepositKey(deposit.ProposalId, depositor))
249+
}
250+
251+
// refundDeposit returns a deposit to its depositor and deletes its record. A
252+
// deposit whose depositor cannot receive funds stays recorded, backed by the
253+
// governance module balance; recovering it requires a migration.
254+
func (keeper Keeper) refundDeposit(ctx sdk.Context, deposit types.Deposit) {
255+
depositor := sdk.MustAccAddressFromBech32(deposit.Depositor)
256+
if keeper.bankKeeper.BlockedAddr(depositor) || !keeper.bankKeeper.CanSendTo(ctx, depositor) {
257+
return
258+
}
259+
if err := keeper.bankKeeper.SendCoinsFromModuleToAccount(ctx, types.ModuleName, depositor, deposit.Amount); err != nil {
260+
panic(err)
261+
}
262+
ctx.KVStore(keeper.storeKey).Delete(types.DepositKey(deposit.ProposalId, depositor))
263+
}
264+
265+
const (
266+
depositSettlementBurn byte = 0
267+
depositSettlementRefund byte = 1
268+
)
269+
270+
func encodeDepositSettlement(burn bool, cursor []byte) []byte {
271+
mode := depositSettlementRefund
272+
if burn {
273+
mode = depositSettlementBurn
274+
}
275+
return append([]byte{mode}, cursor...)
276+
}
277+
278+
func decodeDepositSettlement(value []byte) (burn bool, cursor []byte) {
279+
switch value[0] {
280+
case depositSettlementBurn:
281+
burn = true
282+
case depositSettlementRefund:
283+
default:
284+
panic(fmt.Sprintf("invalid deposit settlement mode %d", value[0]))
285+
}
286+
return burn, append([]byte(nil), value[1:]...)
192287
}

‎sei-cosmos/x/gov/keeper/deposit_test.go‎

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@ import (
1414
seiapp "github.com/sei-protocol/sei-chain/app"
1515
sdk "github.com/sei-protocol/sei-chain/sei-cosmos/types"
1616
bankkeeper "github.com/sei-protocol/sei-chain/sei-cosmos/x/bank/keeper"
17+
govkeeper "github.com/sei-protocol/sei-chain/sei-cosmos/x/gov/keeper"
1718
)
1819

1920
func TestDeposits(t *testing.T) {
@@ -242,3 +243,90 @@ func TestRefundDepositsLeavesBlockedRecipientPending(t *testing.T) {
242243
require.Equal(t, expectedBalance, app.BankKeeper.GetBalance(ctx, blockedDepositor, sdk.DefaultBondDenom).Amount)
243244
require.Equal(t, depositAmount, app.BankKeeper.GetAllBalances(ctx, app.AccountKeeper.GetModuleAddress(types.ModuleName)))
244245
}
246+
247+
func TestSettleDepositsResumesWithinBudget(t *testing.T) {
248+
app := seiapp.Setup(t, false, false, false)
249+
ctx := app.BaseApp.NewContext(false, tmproto.Header{})
250+
depositors := seiapp.AddTestAddrsIncremental(app, ctx, 3, sdk.NewInt(100))
251+
blockedDepositor := sdk.AccAddress(append(append([]byte{}, bankkeeper.CoinbaseAddressPrefix...), make([]byte, 8)...))
252+
require.NoError(t, app.BankKeeper.AddCoins(ctx, blockedDepositor, sdk.NewCoins(sdk.NewInt64Coin(sdk.DefaultBondDenom, 100)), true))
253+
254+
burned, err := app.GovKeeper.SubmitProposal(ctx, TestProposal)
255+
require.NoError(t, err)
256+
refunded, err := app.GovKeeper.SubmitProposal(ctx, TestProposal)
257+
require.NoError(t, err)
258+
amount := sdk.NewCoins(sdk.NewInt64Coin(sdk.DefaultBondDenom, 10))
259+
for _, depositor := range depositors {
260+
_, err = app.GovKeeper.AddDeposit(ctx, burned.ProposalId, depositor, amount)
261+
require.NoError(t, err)
262+
_, err = app.GovKeeper.AddDeposit(ctx, refunded.ProposalId, depositor, amount)
263+
require.NoError(t, err)
264+
}
265+
_, err = app.GovKeeper.AddDeposit(ctx, refunded.ProposalId, blockedDepositor, amount)
266+
require.NoError(t, err)
267+
supply := app.BankKeeper.GetSupply(ctx, sdk.DefaultBondDenom).Amount
268+
requireDepositsBacked := func() {
269+
msg, broken := govkeeper.ModuleAccountInvariant(app.GovKeeper, app.BankKeeper)(ctx)
270+
require.False(t, broken, msg)
271+
}
272+
273+
app.GovKeeper.ScheduleDepositSettlement(ctx, refunded.ProposalId, false)
274+
app.GovKeeper.ScheduleDepositSettlement(ctx, burned.ProposalId, true)
275+
276+
require.Equal(t, 2, app.GovKeeper.SettleDeposits(ctx, 2))
277+
require.Len(t, app.GovKeeper.GetDeposits(ctx, burned.ProposalId), 1)
278+
require.Len(t, app.GovKeeper.GetDeposits(ctx, refunded.ProposalId), 4)
279+
requireDepositsBacked()
280+
281+
require.Equal(t, 2, app.GovKeeper.SettleDeposits(ctx, 2))
282+
require.Empty(t, app.GovKeeper.GetDeposits(ctx, burned.ProposalId))
283+
requireDepositsBacked()
284+
285+
require.Equal(t, 3, app.GovKeeper.SettleDeposits(ctx, 10))
286+
remaining := app.GovKeeper.GetDeposits(ctx, refunded.ProposalId)
287+
require.Len(t, remaining, 1)
288+
require.Equal(t, blockedDepositor.String(), remaining[0].Depositor)
289+
require.Zero(t, app.GovKeeper.SettleDeposits(ctx, 10))
290+
requireDepositsBacked()
291+
292+
require.Equal(t, supply.SubRaw(30), app.BankKeeper.GetSupply(ctx, sdk.DefaultBondDenom).Amount)
293+
for _, depositor := range depositors {
294+
require.Equal(t, sdk.NewInt(90), app.BankKeeper.GetBalance(ctx, depositor, sdk.DefaultBondDenom).Amount)
295+
}
296+
}
297+
298+
func TestScheduleDepositSettlementSkipsProposalsWithoutDeposits(t *testing.T) {
299+
app := seiapp.Setup(t, false, false, false)
300+
ctx := app.BaseApp.NewContext(false, tmproto.Header{})
301+
proposal, err := app.GovKeeper.SubmitProposal(ctx, TestProposal)
302+
require.NoError(t, err)
303+
304+
app.GovKeeper.ScheduleDepositSettlement(ctx, proposal.ProposalId, true)
305+
require.Zero(t, queuedDepositSettlements(ctx, app))
306+
}
307+
308+
func TestSettleDepositsCountsProposalsWithoutRecords(t *testing.T) {
309+
app := seiapp.Setup(t, false, false, false)
310+
ctx := app.BaseApp.NewContext(false, tmproto.Header{})
311+
depositor := seiapp.AddTestAddrsIncremental(app, ctx, 1, sdk.NewInt(100))[0]
312+
for range 3 {
313+
proposal, err := app.GovKeeper.SubmitProposal(ctx, TestProposal)
314+
require.NoError(t, err)
315+
_, err = app.GovKeeper.AddDeposit(ctx, proposal.ProposalId, depositor, sdk.NewCoins(sdk.NewInt64Coin(sdk.DefaultBondDenom, 1)))
316+
require.NoError(t, err)
317+
app.GovKeeper.ScheduleDepositSettlement(ctx, proposal.ProposalId, true)
318+
app.GovKeeper.DeleteDeposits(ctx, proposal.ProposalId)
319+
}
320+
321+
require.Equal(t, 2, app.GovKeeper.SettleDeposits(ctx, 2))
322+
require.Equal(t, 1, queuedDepositSettlements(ctx, app))
323+
}
324+
325+
func queuedDepositSettlements(ctx sdk.Context, app *seiapp.App) (queued int) {
326+
iterator := sdk.KVStorePrefixIterator(ctx.KVStore(app.GetKey(types.StoreKey)), types.DepositSettlementKeyPrefix)
327+
defer func() { _ = iterator.Close() }()
328+
for ; iterator.Valid(); iterator.Next() {
329+
queued++
330+
}
331+
return queued
332+
}

‎sei-cosmos/x/gov/types/keys.go‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -82,6 +82,8 @@ const (
8282
// - 0x44<proposalID_Bytes><tallyRound_Byte><validatorAddrLen (1 Byte)><validatorAddr_Bytes>: Tally validator accumulator
8383

8484
// - 0x45<proposalID_Bytes><tallyRound_Byte>: Tally validator accumulator cleanup cursor
85+
86+
// - 0x46<proposalID_Bytes>: Finished proposal's pending deposit settlement
8587
var (
8688
ProposalsKeyPrefix = []byte{0x00}
8789
ActiveProposalQueuePrefix = []byte{0x01}
@@ -117,6 +119,7 @@ var (
117119
ModernTallyRoundKeyPrefix = []byte{0x43}
118120
TallyValidatorAccumulatorsKeyPrefix = []byte{0x44}
119121
TallyAccumulatorCleanupKeyPrefix = []byte{0x45}
122+
DepositSettlementKeyPrefix = []byte{0x46}
120123
)
121124

122125
var lenTime = len(sdk.FormatTimeBytes(time.Now()))
@@ -306,6 +309,11 @@ func TallyAccumulatorCleanupKey(proposalID uint64, expedited bool) []byte {
306309
return append(append(TallyAccumulatorCleanupKeyPrefix, GetProposalIDBytes(proposalID)...), tallyRound(expedited))
307310
}
308311

312+
// DepositSettlementKey returns the key for a finished proposal's pending deposit settlement.
313+
func DepositSettlementKey(proposalID uint64) []byte {
314+
return append(append([]byte(nil), DepositSettlementKeyPrefix...), GetProposalIDBytes(proposalID)...)
315+
}
316+
309317
func tallyRound(expedited bool) byte {
310318
if expedited {
311319
return 0
@@ -361,6 +369,15 @@ func SplitTallyAccumulatorCleanupKey(key []byte) (proposalID uint64, expedited b
361369
return GetProposalIDFromBytes(key[1:9]), decodeTallyRound(key[9])
362370
}
363371

372+
// SplitDepositSettlementKey returns the proposal encoded in a deposit settlement key.
373+
func SplitDepositSettlementKey(key []byte) (proposalID uint64) {
374+
kv.AssertKeyLength(key, 9)
375+
if key[0] != DepositSettlementKeyPrefix[0] {
376+
panic(fmt.Sprintf("invalid deposit settlement key prefix %d", key[0]))
377+
}
378+
return GetProposalIDFromBytes(key[1:])
379+
}
380+
364381
// SplitKeyDeposit split the deposits key and returns the proposal id and depositor address
365382
func SplitKeyDeposit(key []byte) (proposalID uint64, depositorAddr sdk.AccAddress) {
366383
return splitKeyWithAddress(key)

0 commit comments

Comments
 (0)