Bank Tiers and Interest

Bank Tiers & Interest

The levels: block in config.yml defines the account ladder. Each level sets a max balance, an interest cap, the interest brackets, and the cost to unlock it.

A single level

levels:
  2:
    name: "Gold Account"
    max-balance: 100000000.0
    daily-interest-percent: 2.0
    max-interest: 300000.0
    interest-tranches:
      1:
        from: 0.0
        to: 10000000.0
        percent: 2.0
      2:
        from: 10000000.0
        to: 20000000.0
        percent: 1.0
    upgrade-cost:
      money: 5000000.0
      items:
        - "minecraft:GOLD_BLOCK:64"

Key	Meaning
name	Display name of the tier.
max-balance	The most a player at this tier can hold in the bank.
max-interest	Per-claim interest cap for this tier. 0 disables interest for the tier; a negative value means no per-tier cap.
daily-interest-percent	Flat fallback rate, only used when a level has no interest-tranches block. Ignored when tranches are defined.
interest-tranches	Bracketed interest — see below.
upgrade-cost	What it costs to unlock this tier. See Upgrade Costs.

Levels are numbered 1, 2, 3, … and you can add as many as you like. Give each a bigger max-balance and a meaningful upgrade-cost.

How interest is calculated (tranches)

Interest is progressive, like income-tax brackets. Each tranche applies its percent only to the portion of the balance that falls inside its from–to band. The results are summed, then the total is capped by the level's max-interest.

Worked example — Gold Account, balance of 15,000,000:

Tranche	Band	Portion in band	Rate	Interest
1	0 – 10,000,000	10,000,000	2.0%	200,000
2	10,000,000 – 20,000,000	5,000,000	1.0%	50,000
Total				250,000

250,000 is below the tier's max-interest of 300,000, so the full amount is paid. If the calculation had exceeded 300,000, it would be clamped to 300,000.

Design tip: make the top tranche's to reach the level's max-balance, so large balances keep earning (up to the cap) instead of hitting a band with no rate above it.

Tranches are what let you reward saving while stopping the richest accounts from snowballing — high balances earn a shrinking marginal rate, and the max-interest cap is the hard ceiling.

When interest is paid

Interest is claim-driven — there is no background timer quietly compounding balances.

A player receives interest:

• On join, if settings.interest-on-join is true, and
• Via /bank interest or the GUI interest button, if settings.interest-command-enabled is true.

Either path is subject to settings.interest-cooldown-hours. Crucially, the cooldown is only consumed when interest is actually paid — an empty bank, a tier with interest disabled, or a claim that rounds to nothing does not burn the cooldown, so players never "waste" a claim.

Where interest lands (bank vs purse) is controlled by settings.pay-interest-to-bank.

The global cap vs the per-tier cap

There are two ceilings, and both apply:

• settings.max-daily-interest.amount — a server-wide ceiling on every claim.
• levels.<n>.max-interest — a per-tier ceiling.

The smaller of the two wins for any given claim. Set the global one negative to rely purely on per-tier caps.

Upgrading

A player upgrades with /bank upgrade (or the GUI). To upgrade they must:

1. Meet settings.upgrade-unlock-combined-balance (bank + purse), and
2. Pay the next tier's upgrade-cost — money and/or items.

See Upgrade Costs for the item format and how vanilla-vs-custom items are matched.