Buy Native SOL

[kaze-cow]

Stacked on #163, which adds OrderIntentAccessor and its optimizations. This PR adds buying native SOL and restructures the OrderIntent buy/sell fields into TokenAsset/Asset.

Description

Adds the ability for a trader to specify the system account rather than a token mint as the buy_mint, and in doing so, receive native SOL directly from the settlement program.

Motivation

Being able to buy and sell native tokens from the settlement program is known to improve. Its relatively simple to support this from the settlement program side.

Changes overview

The OrderIntent buy_mint field may be set to 11111..1111 (the system program). When this is the case, buy_token_account is treated as a regular account that receives native lamports rather than a token account that receives tokens.

Elsewhere in the solana ecosystem the system program seems to be treated for this very purpose.

Note that the settlement program itself doesn't actually need to be supplied as an input account since its only used as a data marker. Instead, the source_buffer is set to the state_pda.

Before an account can receive lamports, it must have been created. This requires the user to create the account if it doesn't exist already, the same as they would need to with a token account.

The source "buffer" for lamports is the settlement state pda. Its the most natural choice since it will already be loaded during execution and can be directly debited using lamport math. The solana runtime will prevent the withdrawal of more lamports than are required for rent exemption, so this prevents solvers from withdrawing too much.

To prevent issues with creating orders on the settlement program itself (which is expected to come soon), the move_lamports function will do nothing if the sender is the same as the receiver. So if the buy_token_account is set to state_pda it works as expected (funds remain in the state pda)

Default derive was removed from Asset to prevent "accidents" with using Default for some reason and just ending up with a 0 address. But I still wanted to be able to use Default in the tests, so it became a cfg.

This propogated up the chain, all the way to the client lib, so we are still using cfg test fixtures to prevent default from being used outside that case. So if you are seeing cfg sections added for default, that is why.

Gas Impact

Looking at the correct bench report, it seems very small. Unrelated orders use about ~20 more CU on settle, whereas just about every other function somehow saved 1 CU.

Out of scope

For fee collection, lamports cannot directly be taken from the state pda, so a separate instruction will likely need to be created.

Questions

Should we rename buy_token_account to simply buy_account? should we do the same for sell side?

[linear-code]

SC-275

[fedgiac]

Very interesting bug spotted when preparing the prerelease, see failing test here. It seems our understanding of accounts in an instruction is incorrect.

Claude summary of the bug

The working tree is clean again (instrumentation removed, clean .so rebuilt). Note: git diff shows HEAD currently contains the debug block in settle_native_sol.rs — so when you commit, include this revert so the
  instrumentation doesn't linger in history.

  Why it fails now

  It's a latent bug in FinalizeSettle's native-SOL payout, newly triggered by the release-prep changes (new declare_id + v0.5 seed) — not caused by the cancel work.

  The bug. In a settlement that mixes a token payout and a native-SOL payout, the state PDA appears twice in the finalize: once as the fixed state_pda_account, and once as the native push's source_buffer. push_funds processes
  pushes in order:

  1. native push first: move_lamports directly debits the state PDA (−1,000,000) and credits the destination (+1,000,000) — the logs show state_pda 5_789_232 → 4_789_232, dest 0 → 1_000_000. Balanced so far.
  2. token push next: an SPL Transfer CPI that passes the state PDA (the other handle, state_pda_account) as the authority.

  When the CPI returns, the runtime writes the state PDA's lamports back from the handle it was given for the CPI — which never saw the −1M — so the debit is undone, while the destination keeps its +1M. Net result: 1,000,000
  lamports created from nothing → UnbalancedInstruction ("sum of account balances before and after instruction do not match").

  Why only now, and only this test. push_funds runs pushes in order-PDA-sorted order. That order depends on the program id and the version-stamped SETTLEMENT_SEED — both of which just changed. At the old id/v0.4, the token
  push sorted first, so the native move_lamports ran last, with no CPI after it to clobber the debit (which is why pure-native settlements and the old mixed case pass). At the new id/v0.5, the native push sorts first, so it's
  now followed by the token CPI → the clobber. happy_path_with_token_payout is the only test that mixes a CPI push and a native push in one finalize, so it's the only one affected.

  Fix options

  The robust fix is to make the direct lamport moves never precede a CPI on the state PDA. Either:

  - Two passes in push_funds: do all SPL (CPI) pushes first, then all native move_lamports last. Matches the ordering that already works, order-independent. Simplest and safest.
  - Or use the same state_pda_account handle for the native move instead of the separate push.source_buffer handle, so there's no stale second view for the CPI to write back.

  I'd recommend the two-pass approach, plus a regression test that pins the native-before-token ordering (e.g. a mixed settlement asserted to settle regardless of order-PDA sort) so this can't silently reappear on a future
  address/version change.

[fedgiac]

Suggested test (sorry if it's already there, it's more of a reminder for my review): make sure that if filling a buy order would leave less than the needed rent in the settle PDA.

[kaze-cow]

Very interesting bug spotted when preparing the prerelease,

I see it happens because the order that the order pdas are supplied changes. Would be nice to have proptests which would cover something like this!

Ok probably easiest way to test that this issue is sure to appear is by increasing the number of different orders tested with, so will add that.

And for the fix itself, I tried following the second suggestion, but . The first suggestion works pretty simply, but it impacts CU a bit more. Maybe I am over optimizing, but ended up splitting the lamport math into two separate

This would still create a arithmetic issue for the unlikely case where the token account being paid out on buy-sol order is the same account being paid on a buy SOL order (ex. the token account's native balance is funded). I think this edge case is minescule

[fedgiac]

Reviewed everything, to the best of my knowledge the comments below are everything that needs to be addressed before merging, and all of them are easy.
One exception:
#151 (comment)
Example code here.

[fedgiac]

Nice, great work!