com_r35157_nenjim-hubd-impl_ref/openspec/specs/jupiter-perps-transaction-confirmation/spec.md

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