com_r35157_nenjim-hubd-impl_ref/openspec/specs/solana-wallet-signing/spec.md

solana-wallet-signing Specification

Purpose

Define how a reference Solana wallet proves during construction that its external signer is compatible, available, and bound to the configured wallet address.

Requirements

Requirement: Wallet signing configuration is complete

The reference Solana wallet SHALL require a non-blank wallet address, a non-blank signer key name, and a non-null Solana blockchain dependency before validating any external signer state. Invalid direct inputs SHALL fail construction with an argument or null exception that identifies the invalid field.

Scenario: Complete direct configuration

• WHEN construction receives a non-blank wallet address, a non-blank signer key name, and a Solana blockchain dependency
• THEN external signer validation begins

Scenario: Invalid direct configuration

• WHEN the wallet address or signer key name is null or blank, or the Solana blockchain dependency is null
• THEN construction fails before executing an external signer command and identifies the invalid field

Requirement: Construction requires the supported jup version

The reference Solana wallet SHALL execute jup --version during every construction, SHALL require that command to start and exit successfully, and SHALL accept exactly version 0.10.1. A missing executable, process I/O failure, non-zero exit, blank or malformed version, unsupported version, or interruption SHALL prevent construction with an actionable IllegalStateException; interruption SHALL also restore the constructing thread's interrupted status.

Scenario: Supported jup version

• WHEN jup --version starts successfully, exits with zero, and reports 0.10.1
• THEN construction proceeds to signer-key validation

Scenario: jup cannot execute successfully

• WHEN jup --version cannot be started, its output cannot be read, or it exits with a non-zero status
• THEN construction fails with a diagnostic identifying the command, signer key name, expected version, and available exit or error details

Scenario: jup version output is invalid

• WHEN jup --version exits successfully but reports a blank or malformed semantic version
• THEN construction fails with a diagnostic containing the expected version and reported output

Scenario: jup version is unsupported

• WHEN jup --version reports a valid semantic version other than 0.10.1
• THEN construction fails with a diagnostic containing both expected and actual versions

Scenario: Version check is interrupted

• WHEN the constructing thread is interrupted while awaiting jup --version
• THEN construction fails, the child process is terminated, and the thread's interrupted status is restored

Requirement: Construction validates signer identity

After validating the supported CLI version, the reference Solana wallet SHALL obtain the jup key catalogue as JSON, require a key whose name exactly matches the configured signer key name, require that key to contain a non-blank public address, and require that address to equal the configured wallet address. Command, I/O, JSON, missing-key, missing-address, and address-mismatch failures SHALL prevent construction with an actionable IllegalStateException.

Scenario: Configured signer matches the wallet

• WHEN the key catalogue contains the configured signer key name with a public address equal to the configured wallet address
• THEN wallet construction succeeds

Scenario: Key catalogue cannot be obtained

• WHEN the key-list command cannot be started, read, or completed successfully
• THEN construction fails with a diagnostic identifying the command, signer key name, and available exit or error details

Scenario: Key catalogue is malformed

• WHEN the key-list command succeeds but does not return a JSON array that can be decoded
• THEN construction fails with a diagnostic identifying the configured signer key name

Scenario: Configured signer is unavailable

• WHEN the key catalogue does not contain a key whose name exactly matches the configured signer key name
• THEN construction fails with a diagnostic identifying that signer key name

Scenario: Signer address is missing

• WHEN the matching key has no non-blank public address
• THEN construction fails with a diagnostic containing the signer key name and expected wallet address

Scenario: Signer address differs from the wallet

• WHEN the matching key's public address differs from the configured wallet address
• THEN construction fails with a diagnostic containing the signer key name, expected wallet address, and actual public address

Scenario: Validation diagnostics protect key material

• WHEN any signer validation fails
• THEN its diagnostic contains only the relevant command, name, public address, version, exit status, and stderr context and does not disclose private key material

Requirement: Signing retains runtime identity validation

The reference Solana wallet SHALL continue to require every successful signing response to identify the configured wallet address before accepting its signed transaction, even after construction-time signer validation has succeeded.

Scenario: Signing response identifies another wallet

• WHEN a later signing response contains a signer address different from the configured wallet address
• THEN signing fails without accepting the returned signed transaction