Add contract address validation, transaction verification, comprehensive error codes, and recovery strategies (#1065, #1066, #1067, #1068)

[dev-kiki0]

What this fixes

Four related gaps in the SDK's validation and error-handling surface:

• Add contract address validation #1065 – Contract address validation: the SDK had no dedicated way to validate Soroban contract IDs; a mistyped or corrupt C... address only failed later, during config validation or on-chain submission.
• Implement transaction verification #1066 – Transaction verification: transactions could be submitted without any local pre-flight check of integrity/authenticity (signatures, fee, sequence, time bounds, hash), so tampered or stale transactions surfaced as opaque on-chain failures.
• Comprehensive error codes #1067 – Comprehensive error codes: SdkErrorCode only covered 8 failure modes, with no per-code descriptions and no way to tell whether a failure was transient.
• Add error recovery strategies #1068 – Error recovery strategies: there was no mapping from errors to concrete recovery actions (retry, refresh-and-rebuild, fix input, wait, abort), and no automatic way to apply them.

What changed

#1065 – src/contractAddressValidator.ts

• validateContractAddress() checks the documented StrKey rules and reports format (type, 56-char length, C prefix, uppercase base32 alphabet) and checksum (CRC16 via StrKey.decodeContract) failures separately.
• isValidContractAddress() boolean shorthand and assertValidContractAddress() which throws the new typed InvalidContractAddressError (code INVALID_CONTRACT_ADDRESS).
• Validation rules documented in the module JSDoc and in docs/ERROR_CODES.md.

#1066 – src/transactionVerifier.ts

• verifyTransaction(tx, options) runs six independent checks: structure, fee (maxFee), sequence (expectedSequence), timebounds, signatures (ed25519 over the tx hash for each required signers key, plus minSignatures), and hash (expectedHash, hex or base64). Options that aren't supplied are skipped, never passed vacuously.
• verifyTransactionSignatures() classifies keys as valid / missing / invalid; hints are advisory only — a signature counts only when ed25519 verification succeeds.
• assertTransactionVerified() throws the new typed TransactionVerificationError (code VERIFICATION_FAILED) listing the failed checks.

#1067 – src/errors.ts + src/errorSuggestions.ts

• SdkErrorCode extended from 8 to 38 codes across seven categories (invoice lifecycle, accounts/funds, input validation, network, transaction lifecycle, contract execution, authorization, operational/state); all existing codes preserved.
• Added exhaustive SDK_ERROR_CODE_DESCRIPTIONS, describeSdkErrorCode(), conservative RETRYABLE_ERROR_CODES, and isRetryableErrorCode().
• getSuggestion() coverage extended to every code — the Record<SdkErrorCode, string> table makes all three maps compile-time exhaustive, so future codes can't ship without descriptions, suggestions, or recovery strategies.

#1068 – src/errorRecovery.ts

• Exhaustive RECOVERY_STRATEGY_TABLE mapping every code to a RecoveryAction (retry, retry_with_backoff, refresh_and_retry, correct_input, use_fallback, wait_for_resolution, abort) with maxAttempts/backoffMs where retryable.
• getRecoveryStrategy() (code / string / Error) and getRecoveryPlan() (strategy + human suggestion).
• executeWithRecovery(op) applies the mapped strategy: bounded retries with exponential backoff for transient failures, immediate rethrow for non-retryable ones, abort-signal support.
• Runnable example in examples/error-recovery-example.ts and full reference in docs/ERROR_CODES.md.

Public API: all new symbols exported from src/index.ts.

Testing

• npx vitest run test/contractAddressValidator.test.ts test/errorCodes.test.ts test/transactionVerifier.test.ts test/errorRecovery.test.ts test/errorSuggestions.test.ts test/sdkError.test.ts → 6 files, 108 tests passed.
  • Known contract addresses (generated via StrKey.encodeContract) accepted; broken-checksum/format/case/alphabet/length/prefix mutations rejected.
  • Real offline transactions built with TransactionBuilder exercise every verification check (pass and fail paths, forged signatures, hash mismatch).
  • Exhaustive enum/description/suggestion/strategy coverage checks; retry executor behavior (backoff, maxAttempts, non-retryable, abort signal).
• npm test (core suite) → passed.
• Full suite npx vitest run → 269 files: 246 passed, 21 failed, 2 skipped (3447 tests passed, 168 failed) — identical (same 21 files, same 168 tests) to a clean upstream/main baseline run, i.e. all failures are pre-existing and unrelated.
• npm run lint (tsc --noEmit): 561 errors — identical to the pre-change baseline; zero errors in any file added or modified by this PR.

Issues

closes #1065
closes #1066
closes #1067
closes #1068

[drips-wave]

@dev-kiki0 Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits