# jupiter-perps-transaction-confirmation Specification

## Purpose

Defines independent Solana confirmation and outcome reporting for completed Jupiter Perps increase and decrease submissions.

## Requirements

### Requirement: Confirmed Perps operation completion
After the existing Perps increase or decrease flow produces a valid non-blank transaction signature, the service SHALL independently await that signature at `CONFIRMED`. It SHALL return the existing signature result only for `SUCCEEDED`; provider response validation and financial validation SHALL remain distinct prerequisites and SHALL not themselves constitute on-chain confirmation.

#### Scenario: Increase reaches confirmed success
- **WHEN** an increase submission returns a valid signature and its independent `CONFIRMED` outcome is `SUCCEEDED`
- **THEN** the service returns that signature

#### Scenario: Decrease reaches confirmed success
- **WHEN** a decrease submission returns a valid signature and its independent `CONFIRMED` outcome is `SUCCEEDED`
- **THEN** the service returns that signature

### Requirement: Structured exceptional outcomes
The shared Jupiter API SHALL expose a checked outcome exception containing the known non-blank transaction signature, requested commitment, and complete transaction outcome. Construction SHALL reject null or blank signatures, null commitments, null outcomes, and `SUCCEEDED` outcomes. `FAILED` SHALL identify a definitive on-chain failure including its slot and compact Solana error, while `TIMED_OUT` SHALL identify an unknown outcome and explicitly warn against automatic equivalent resubmission.

#### Scenario: Confirmed on-chain failure
- **WHEN** an increase or decrease signature reaches `CONFIRMED` with a `FAILED` outcome
- **THEN** the service throws the checked outcome exception preserving the signature, `CONFIRMED`, slot, and complete compact Solana failure details

#### Scenario: Confirmation timeout
- **WHEN** an increase or decrease signature produces a `TIMED_OUT` outcome
- **THEN** the service throws the checked outcome exception preserving the signature, `CONFIRMED`, and unknown outcome without automatically resubmitting

#### Scenario: Successful outcome is supplied to exception
- **WHEN** a caller attempts to construct the outcome exception with `SUCCEEDED` or inconsistent null or blank data
- **THEN** construction fails immediately

### Requirement: Perps confirmation timeout policy
The reference service SHALL accept a constructor-injected, non-null, strictly positive confirmation timeout and SHALL preserve its existing constructor with a two-minute default. The configured duration SHALL be forwarded unchanged and SHALL begin governing only when awaiting the already submitted signature starts. Increase and decrease SHALL apply the same confirmation and outcome policy.

#### Scenario: Existing constructor is used
- **WHEN** the reference service is constructed without a confirmation timeout
- **THEN** each submitted increase or decrease uses a two-minute confirmation timeout

#### Scenario: Custom timeout is used
- **WHEN** the reference service is constructed with a positive duration
- **THEN** each submitted increase or decrease forwards exactly that duration to `CONFIRMED` awaiting

#### Scenario: Invalid timeout is supplied
- **WHEN** the reference service is constructed with a null, zero, or negative duration
- **THEN** construction fails before any Perps operation can be submitted

### Requirement: Post-submission communication and interruption policy
If independent confirmation throws an I/O error after a signature is known, the service SHALL throw an `IOException` whose message identifies the increase or decrease operation, includes the signature, and states that the on-chain outcome is unknown, retaining the original error as cause. `InterruptedException` SHALL propagate directly without another RPC or Jupiter request. Confirmation SHALL never submit, rebuild, re-sign, retry, or resubmit a transaction.

#### Scenario: Confirmation communication fails
- **WHEN** independent confirmation throws an I/O error for a known Perps signature
- **THEN** the service reports the operation, signature, and unknown outcome, preserves the original error, and performs no retry or resubmission

#### Scenario: Confirmation is interrupted
- **WHEN** independent confirmation throws `InterruptedException`
- **THEN** interruption propagates directly and no subsequent request occurs

### Requirement: Outcome-aware Perps alarm reporting
Perps increase and decrease alarm actions SHALL rely on the Perps service for confirmation and SHALL distinguish structured `FAILED`, structured `TIMED_OUT`, and other errors. A failed report SHALL include operation, signature, confirmation slot, and compact Solana failure details. A timed-out report SHALL include operation, signature, unknown-outcome status, and that no equivalent transaction was automatically resubmitted. Alarm actions SHALL NOT invoke transaction awaiting themselves.

#### Scenario: Alarm operation fails on-chain
- **WHEN** a Perps alarm action receives a structured `FAILED` outcome exception
- **THEN** it reports the operation, signature, confirmation slot, and compact on-chain failure details distinctly from generic errors

#### Scenario: Alarm operation remains unknown
- **WHEN** a Perps alarm action receives a structured `TIMED_OUT` outcome exception
- **THEN** it reports the operation, signature, unknown outcome, and absence of automatic equivalent resubmission distinctly from generic errors