80 lines
5.4 KiB
Markdown
80 lines
5.4 KiB
Markdown
# 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
|