Skip to content

feat: add guarded sol transfer helper#82

Draft
amilz wants to merge 4 commits into
solana-program:mainfrom
amilz:feat/add-transfer-helper
Draft

feat: add guarded sol transfer helper#82
amilz wants to merge 4 commits into
solana-program:mainfrom
amilz:feat/add-transfer-helper

Conversation

@amilz

@amilz amilz commented Jun 15, 2026

Copy link
Copy Markdown
Contributor

Adds a guarded SOL-transfer helper that validates a destination before building the transferSol instruction, preventing common footguns where SOL is sent to an unrecoverable address.

Adds:

  • assertValidTransferSolDestination(rpc, destination, config?) — throws InvalidTransferSolDestinationError if the destination is unsafe.
  • getTransferSolGuardedInstruction(rpc, input, config?) — runs the assertion, then returns a standard transferSol instruction (async, since the owner check needs an RPC).

Updates:

  • systemProgram() plugin — extends the generated System plugin with a transferSolGuarded instruction method on client.system.instructions.

Validation rules

A destination is rejected unless it's an existing account owned by the expected program (default: System Program). Overridable via config:

Option Default Effect
programOwner System Program Expected owner of an existing destination account
allowUnfundedRecipient false Permit a destination with no on-chain account (fund-on-transfer)
allowOffCurve false Permit off-curve (program-derived) destinations

Each rejection carries a reason (unexpected-owner | unfunded-recipient | off-curve) and, where relevant, the actual owner.

Changes

  • clients/js/src/transferSolGuarded.ts — helper + error type
  • clients/js/src/plugin.tssystemProgram() plugin wrapper
  • clients/js/src/index.ts — exports
  • clients/js/test/transferSolGuarded.test.ts — coverage
  • clients/js/README.md — usage docs

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant