feat(svm): allow Phantom and Solflare Lighthouse instructions in transaction verification

[aptum11]

Description

Phantom and Solflare wallets inject Lighthouse program instructions for user protection on Solana mainnet transactions. This causes x402 transaction verification to fail because the facilitator scheme expects exactly 3 instructions (ComputeLimit + ComputePrice + TransferChecked).

This change allows optional 4th and 5th instructions specifically from the Lighthouse program (L2TExMFKdjpN9kozasaurPirfHy9P8sbXoAN1qA3S95):

• 4th instruction: Phantom wallet protection (adds 1 Lighthouse instruction)
• 5th instruction: Solflare wallet protection (adds 2 Lighthouse instructions)

Changes:

• Add LIGHTHOUSE_PROGRAM_ADDRESS / LighthouseProgramAddress constant (TypeScript and Go)
• Update ExactSvmScheme verify to allow 3-5 instructions
• Update ExactSvmSchemeV1 verify to allow 3-5 instructions
• Reject any 4th/5th instruction that is not from the Lighthouse program

Potentially Closes #828

Tests

These changes have been tested in production at PayAI with both Phantom and Solflare wallets on Solana mainnet. PR discussed with @notorious-d-e-v.

The verification logic changes are minimal and defensive:

• Only allows additional instructions from the specific Lighthouse program address
• Rejects unknown programs in the 4th/5th instruction positions
• Does not affect the core payment verification logic (compute budget + transfer)

Checklist

• I have formatted and linted my code
• All new and existing tests pass
• My commits are signed (required for merge) -- you may need to rebase if you initially pushed unsigned commits

[cb-heimdall]

✅ Heimdall Review Status

Requirement	Status	More Info
Reviews	✅ 1/1	Denominator calculation Show calculation 1 if user is bot 0 1 if user is external 0 2 if repo is sensitive 0 From .codeflow.yml 1 Additional review requirements Show calculation Max 0 0 From CODEOWNERS 0 Global minimum 0 Max 1 1 1 if commit is unverified 0 Sum 1

[vercel]

@aptum11 is attempting to deploy a commit to the Coinbase Team on Vercel.

A member of the Team first needs to authorize it.

[phdargen]

Thanks a lot for the contribution @aptum11, looping in @CarsonRoscoe for a review

[phdargen]

Could you please also update scheme_exact_svm.md to reflect the changes?

There is #829 by @notorious-d-e-v but it seems this PR is much stricter than the spec changes suggested in #829. So its my understanding this PR is a temporary, pragmatic workaround, while we figure out how to open up the specs for more stuff like smart wallets?

[phdargen]

Given that we currently aim to specifically support Phantom/Solflare, would it be possible to have an even stricter check for the exact instructions injected by those wallets?

[aptum11]

Thanks for the review.

Could you please also update scheme_exact_svm.md to reflect the changes?

There is #829 by @notorious-d-e-v but it seems this PR is much stricter than the spec changes suggested in #829. So its my understanding this PR is a temporary, pragmatic workaround, while we figure out how to open up the specs for more stuff like smart wallets?

Regarding #829 - you're right that this PR takes a more conservative approach. This PR is narrowly scoped to allow only Lighthouse program instructions as the 4th/5th instruction. This is a pragmatic fix for the immediate problem of Phantom and Solflare wallets failing verification because they inject these protection instructions on mainnet.

My understanding is that this PR serves as a temporary, targeted workaround to unblock Phantom/Solflare users now, while the broader discussion in #829 figures out the right way to generalize the spec for smart wallets and other wallet-injected instructions without compromising security.

Happy to align with the direction from #829 once those spec changes are finalized, but wanted to ship this fix to address the immediate user-facing issue.

Given that we currently aim to specifically support Phantom/Solflare, would it be possible to have an even stricter check for the exact instructions injected by those wallets?

Good question. We considered stricter whitelisting of exact instruction data, but decided against it for a few reasons:

1. Lighthouse is an assertion-only program - it can only verify conditions and fail the transaction, not modify state or transfer funds. The existing fee payer safety checks (fee payer not in accounts, not authority, not source) already protect against financial loss
2. Maintenance burden - Whitelisting exact instruction data would require code updates whenever Phantom or Solflare change their Lighthouse assertions. This creates an ongoing compatibility risk.
3. Limited attack surface - The worst case with allowing any Lighthouse instruction is transaction failure (denial of service), not loss of funds. A malicious actor can't use Lighthouse to drain the fee payer.

We found the current solution to be a good balance of practicality and security.

[phdargen]

Thanks a lot for the explanation @aptum11 and updating the specs!
Agreed with your reasoning, will let @CarsonRoscoe have another look

In the meanwhile, could you please verify your commit? See here for instructions: https://docs.github.com/en/authentication/managing-commit-signature-verification/about-commit-signature-verification

[tenequm]

I was advocating for the outcome-based approach in #828 and still think that's the cleaner long-term architecture. But that discussion has stalled for over a month now.

@aptum11's reasoning here is sound - Lighthouse is assertion-only, worst case is tx failure not fund loss. The pragmatic move is to ship this and revisit if #829 ever lands.

[CarsonRoscoe]

Thank you for the interim fix @aptum11!

Reading through the comms between you and @phdargen, I align with the logic. I would eventually like to roll back these changes once a more generalized solution is found however.

Appreciate the contribution, LGTM

[phdargen]

Forgot we have a python v2 now 😅 you mind following this up with the equivalent changes there @aptum11?