WIP: Add cow CLI settle command

[kaze-cow]

Description

Adds a command settle to the existing settlement CLI which, given a list of order UIDs/PDAs, attempts

Summary

The settle command completes all the required operations to complete a settlement. This generally breaks down to:

• Ensuring the required buffers/internal solver token accounts are created prior to trade
• Calls BeginSettle to pull in the required funds from the user into the solver's token ATA
• Execute swaps on Orca (currently stubbed) to fullfill any required funding for demand outputs
• Calls FinalizeSettle to push the resulting funds to the user, including surplus based on the available funds

It can serve as an example of what is needed in order to complete a settlement.

Other design considerations:

• If more than one order demanding a particular output token is given, the the output tokens will be distributed proportionally to the buy demand. This is naive and not intended for production, just convenience.
• buy orders have not yet been tested and should be considered unsupportod for this initial release
• `

NOTE: this branch assumes that #26 is merged already in its changes, which is why it appears there are many more changes than actually happening. Please disregard any changes already in that PR for now.

Out of Scope

• Orca Whirlpool swap integration: orca_swap() in settle.rs is stubbed out and will error if a settlement requires a swap (i.e. non-CoW case where no counterpart order exists for a given token pair). Since the priority is to demonstrate the most basic settlement the extra step of swapping as a interaction is currently not included.

Run a test settlement on DevNet!

Prerequisites:

• Solana CLI installed and 3 funded devnet keypairs:

• trader-usdc.json: the trader that has USDC and wants to buy SOL; use https://faucet.circle.com/ to get USDC for the trade on devnet. Needs a bit of SOL for gas.
• trader-sol.json: the trader that has SOL and wants to buy USDC; needs SOL for both the order (0.1 SOL in the example below) and some gas.
• solver.json: the solver for the order, needs a bit of SOL for gas.

# Build (includes the CLI)
just build

# Create an order for USDC to WSOL
./target/debug/cow sell 20 USDC for WSOL --keypair trader-usdc.json
# → prints: order PDA: <PDA_A>

# Create an order going the opposite direction
./target/debug/cow sell 0.1 SOL for USDC --keypair trader-sol.json
# → prints: order PDA: <PDA_B>

# Settle both orders atomically via CoW — no swap required
./target/debug/cow settle <PDA_A> <PDA_B> --keypair solver.json

Expected output:

settle: <signature>
  order 0: pulled 100000000 (sell So11...), pushed 20000000 (buy 4zMM...) [+19999999 surplus]
  order 1: pulled 20000000 (sell 4zMM...), pushed 100000000 (buy So11...) [+99999999 surplus]

The [+N surplus] annotation confirms that proportional surplus was distributed back to each order beyond their minimum requested amount.

If the supplied order is expired (defaults to 5 minutes), you may see an error like ...Program MooohhPEAAHwAwEozL7JPEmnDvaahuUpccYN4Yb8ccK failed: custom program error: 0xf (0xf corresponds to 15, the settlement contract's error for expired order). If this happens, recreate the orders and try again.

Example settle generated by the CLI: https://solscan.io/tx/4YuY3MGV1w4GKRFnL8oDjmqz79ALNTC8c7i1t9UMifWuFhVCSRaA2t2ECweG9GfWttv9nz3Xu15dx5sDbw9GZsCS?cluster=devnet

🤖 Generated with Claude Code

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	anyhow@​1.0.103
	clap@​4.6.1
	solana-commitment-config@​3.1.1
	solana-rpc-client@​3.1.14
	pinocchio@​0.11.1 ⏵ 0.11.2
	solana-hash@​4.3.0 ⏵ 4.4.0

View full report

[socket-security]

Warning

Review the following alerts detected in dependencies.

According to your organization's Security Policy, it is recommended to resolve "Warn" alerts. Learn more about Socket for GitHub.

Action	Severity	Alert  (click "▶" to expand/collapse)
Warn		Obfuscated code: cargo hyper-util is 90.0% likely obfuscated Confidence: 0.90 Location: Package overview From: ? → cargo/solana-rpc-client@3.1.14 → cargo/hyper-util@0.1.20 ℹ Read more on: This package | This alert | What is obfuscated code? Next steps: Take a moment to review the security alert above. Review the linked package source code to understand the potential risk. Ensure the package is not malicious before proceeding. If you're unsure how to proceed, reach out to your security team or ask the Socket team for help at support@socket.dev. Suggestion: Packages should not obfuscate their code. Consider not using packages with obfuscated code. Mark the package as acceptable risk. To ignore this alert only in this pull request, reply with the comment @SocketSecurity ignore cargo/hyper-util@0.1.20. You can also ignore all packages with @SocketSecurity ignore-all. To ignore an alert for all future pull requests, use Socket's Dashboard to change the triage state of this alert.
Warn		Obfuscated code: cargo tokio is 90.0% likely obfuscated Confidence: 0.90 Location: Package overview From: ? → cargo/solana-rpc-client@3.1.14 → cargo/tokio@1.52.3 ℹ Read more on: This package | This alert | What is obfuscated code? Next steps: Take a moment to review the security alert above. Review the linked package source code to understand the potential risk. Ensure the package is not malicious before proceeding. If you're unsure how to proceed, reach out to your security team or ask the Socket team for help at support@socket.dev. Suggestion: Packages should not obfuscate their code. Consider not using packages with obfuscated code. Mark the package as acceptable risk. To ignore this alert only in this pull request, reply with the comment @SocketSecurity ignore cargo/tokio@1.52.3. You can also ignore all packages with @SocketSecurity ignore-all. To ignore an alert for all future pull requests, use Socket's Dashboard to change the triage state of this alert.
Warn		Obfuscated code: cargo writeable is 90.0% likely obfuscated Confidence: 0.90 Location: Package overview From: ? → cargo/solana-rpc-client@3.1.14 → cargo/writeable@0.6.3 ℹ Read more on: This package | This alert | What is obfuscated code? Next steps: Take a moment to review the security alert above. Review the linked package source code to understand the potential risk. Ensure the package is not malicious before proceeding. If you're unsure how to proceed, reach out to your security team or ask the Socket team for help at support@socket.dev. Suggestion: Packages should not obfuscate their code. Consider not using packages with obfuscated code. Mark the package as acceptable risk. To ignore this alert only in this pull request, reply with the comment @SocketSecurity ignore cargo/writeable@0.6.3. You can also ignore all packages with @SocketSecurity ignore-all. To ignore an alert for all future pull requests, use Socket's Dashboard to change the triage state of this alert.
Warn		Obfuscated code: cargo zerocopy is 90.0% likely obfuscated Confidence: 0.90 Location: Package overview From: ? → cargo/proptest@1.11.0 → cargo/solana-rpc-client@3.1.14 → cargo/litesvm@0.12.0 → cargo/litesvm-token@0.12.0 → cargo/solana-address@2.6.1 → cargo/solana-sdk@3.0.0 → cargo/solana-pubkey@3.0.0 → cargo/zerocopy@0.8.52 ℹ Read more on: This package | This alert | What is obfuscated code? Next steps: Take a moment to review the security alert above. Review the linked package source code to understand the potential risk. Ensure the package is not malicious before proceeding. If you're unsure how to proceed, reach out to your security team or ask the Socket team for help at support@socket.dev. Suggestion: Packages should not obfuscate their code. Consider not using packages with obfuscated code. Mark the package as acceptable risk. To ignore this alert only in this pull request, reply with the comment @SocketSecurity ignore cargo/zerocopy@0.8.52. You can also ignore all packages with @SocketSecurity ignore-all. To ignore an alert for all future pull requests, use Socket's Dashboard to change the triage state of this alert.

View full report