Add STATE_VERSION to all settlement PDA seeds

[kaze-cow]

Description

Updates the settlement root PDA seed to correspond to the Major and minor cargo package versions. This causes all PDAs to be relocated on every minor or major package version bump.

Contents

Generally speaking the root state PDA is now:

macro_rules! state_version {
    () => { concat!(env!("CARGO_PKG_VERSION_MAJOR"), ".", env!("CARGO_PKG_VERSION_MINOR")) };
}

pub const SETTLEMENT_SEED: &[u8] = concat!("settlement v", state_version!()).as_bytes();

The whole seed is printable ASCII, so it shows up readably in explorers, logs and solana account.

No CU cost. Everything resolves in rustc — strings on the built .so shows settlement .. v0.1 baked into rodata — so nothing happens on-chain.

Other considerations

• User delegations stop working. Users delegate their token accounts to the state PDA, and a bump moves that address, so every user has to delegate again.
• Whatever the buffers still hold is stranded. A buffer's funds are only spendable by the state PDA that is its SPL authority. After a bump the program can no longer sign for the old state PDA, so those funds can never be moved again. Buffers must be drained under the old program version first.

How to test

Check new strategy

🤖 Generated with Claude Code

[linear-code]

SC-287

[fedgiac]

Something missing from the description that I think deserves a mention: this affects all PDAs, not just the state PDA. This is intended behavior, but a distracted reviewer would miss that.

Also, there are some references to fixed lengths, but I don't see it in the code:

At 15 bytes it has ample headroom under the 32-byte MAX_SEED_LEN

15? Maybe under the assumption that the minor/major are 1 byte each?

The four extra seed bytes are free too: sol_create_program_address and sol_try_find_program_address

4? With the same assumption from before, maybe 5 including the extra space?

But anyway, the assumption is wrong, this isn't a fixed bytes and this in principle is a security concern (see comment).

Also, we should clearly write in the readme that we must increase the minor version on each new deployment, this would be very easy to miss.
The fix for that is that the deployment script tries to see if the state PDA exists and, if it already exists, it aborts the deployment suggesting to bump the version.

[kaze-cow]

Also, we should clearly write in the readme that we must increase the minor version on each new deployment, this would be very easy to miss.

Do we want to enforce that its bumped on every version? or its OK to do a deployment without bumping (or only bumping patch) if the storage format hasn't changed?

The fix for that is that the deployment script tries to see if the state PDA exists and, if it already exists, it aborts the deployment suggesting to bump the version.

We don't currently do anything in the deployment script to call Initialize actually, as there was no initialization when the deploy script was first created. It seems we might want to add something to the test-cli before we do the next big release.

[fedgiac]

Do we want to enforce that its bumped on every version? or its OK to do a deployment without bumping (or only bumping patch) if the storage format hasn't changed?

I'd say the default should be enforcing the version bump but that it can be somehow overwritten. I don't have a concrete idea for how though.

We don't currently do anything in the deployment script to call Initialize actually, as there was no initialization when the deploy script was first created. It seems we might want to add something to the test-cli before we do the next big release.

Yep!

[making it permanent]

Mmh, I'm reconsidering the size, maybe 5 bytes (two minor, two major or one major, three minor) are more than enough for now. Maybe even (1, 2).
But yeah, why not making it permanent? I'll review the DESIGN file with this in mind.

[kaze-cow]

I'd say the default should be enforcing the version bump but that it can be somehow overwritten. I don't have a concrete idea for how though.

Ok for now my thought is, when we get the Initialize call added to the deploy script, it will run a check to see if the PDA already exists or not. if it is not creatable, then you have to pass another flag to confirm what you are doing. But since the Initialize step doesn't exist yet, lets focus on getting what we have here merged. Sg?

[fedgiac]

Nice!