# 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