feat(server): chain submission store, sendTransaction and tracker for create_job and fund

[TOMOKI977]

Update: #102 (the tracker, approved) was squash-merged into this branch as ee3babd, so this PR now ships the store, sendTransaction and the tracker together. PULS3_TRACKER_ENABLED stays off until #96.

Refs #97 (foundation; the tracker itself follows in a second PR)

Summary

Foundation for the escrow relay tracker, split out so #96 can build on it now:

• Submission values (lib/src/chain/submission_values.dart): SubmissionPurpose, SubmissionState and outcome codes, with wire names exactly as in docs/architecture/api.md.
• SorobanRpcClient.sendTransaction: returns a typed SendTransactionResult (PENDING, DUPLICATE, TRY_AGAIN_LATER, ERROR); transport errors become LedgerUnavailable.
• chain_submission model and migration (additive only). Server-only columns (signedEnvelopeXdr, validUntil, hireId, send counters) never reach the client protocol.
• ChainSubmissionStore: interface, Postgres implementation and an in-memory fake, with one contract test suite run against both. It's named Store because Serverpod already generates a ChainSubmissionRepository.

API for #96

abstract interface class ChainSubmissionStore {
  Future<StoredSubmission> insertSubmitted({required SubmissionPurpose purpose, required String transactionHash, required String signedEnvelopeXdr, required DateTime validUntil, String? preparationId, int? hireId, String? explorerUrl}); // throws ChainSubmissionConflict
  Future<StoredSubmission?> findByPreparation(String preparationId);
  Future<List<StoredSubmission>> listSubmitted({int limit = 100});
  Future<bool> markConfirmed(int id);           // only from submitted
  Future<bool> markFailed(int id, String code); // only from submitted
  Future<bool> recordSend(int id, DateTime at);
}

submitEscrowCall should call insertSubmitted (state submitted) before sendTransaction, per relay step 4.

Acceptance criteria (from #97, partial)

• Submissions are persisted durably, one per preparation and one per transaction hash
• A final state (confirmed / failed) is never overwritten (single conditional update)
• Tracker polling, resend and restart recovery: next PR
• create_job / fund confirmation effects: next PR

Verification evidence

• dart analyze --fatal-infos: clean (server and client).
• dart test: 195 passed (181 unit, 14 integration against Postgres via docker compose).
• A second serverpod generate leaves no diff.
• Pre-PR review: risk, reliability, resilience and readability lenses, no blocking findings. Non-blocking notes (JSON-RPC error classification, listSubmitted starvation, per-row isolation, recordSend guard) are addressed in the tracker PR, where they apply.

Notes for reviewers

• Migration order: feat(server): hire and pay endpoint with on-chain payment verification #93/feat(server): escrow relay prepare and submit endpoints for hires #96 will also add a migration. Merging this first avoids a migration_registry.txt conflict; the later branch recreates its migration on top.
• Size: ~500 lines of code and ~600 of tests; the rest is generated (migration definition, protocol, client).

[cloudflare-workers-and-pages]

Deploying puls3 with    Cloudflare Pages

Latest commit:	c1c81de
Status:	✅  Deploy successful!
Preview URL:	https://77cb4116.puls3-4lw.pages.dev
Branch Preview URL:	https://feat-97-chain-submission-tra.puls3-4lw.pages.dev

View logs

[moises-cisneros]

Checked out the branch and ran it locally: dart analyze is clean and dart test passes (195 tests), including the integration suite against Postgres/Redis.

The migration is additive, duplicate-insert conflicts are mapped by index name, and the conditional UPDATE ... WHERE state='submitted' keeps a final state from being overwritten. No blockers from my side. Suggestions:

• recordSend has no state='submitted' guard (serverpod_chain_submission_store.dart). A tracker holding a stale submitted row can bump sendAttempts / lastSentAt on a row that just became confirmed. It could be one UPDATE ... SET sendAttempts = sendAttempts + 1 WHERE id = $1 AND state = 'submitted' instead of read-then-write.
• sendTransaction (soroban_rpc_client.dart) returns the node's hash without comparing it to the persisted transaction hash. Worth documenting that callers must check it, or taking the expected hash as a parameter.
• markFailed(id, code) accepts any string, and it is returned to the client as errorCode. I see #102 adds the isKnown check, so this only matters if #100 lands alone.
• Question on scope: SubmissionOutcomeCode.all has no AuthorizationExpired or HireAlreadyRated, which api.md lists for setAgentWallet / giveFeedback. I assume those arrive with their purposes, just confirming.
• Starvation of listSubmitted (ordered by updatedAt, which recordSend does not bump) is already named in the PR as deferred. #102 addresses it with recordCheck.

[TOMOKI977]

Thanks for running the suites locally, that's really helpful.

• recordSend guard: good catch, fixed in 526f3ad. It now returns false unless the row is still submitted (row lock + state check, same as feat(server): chain submission tracker for create_job and fund #102 already had). The shared store contract test "recordSend changes only a submitted record" runs against both the in-memory fake and the Serverpod store, and it failed before the fix.
• sendTransaction hash: agreed. The tracker resends a persisted envelope, so the hash can only differ if the node is misbehaving. I'll take it into chore(server): harden the chain submission tracker after the Stellar Elite demo #101 (pass the expected hash in and fail loudly on a mismatch) rather than grow this PR.
• markFailed free string: right, feat(server): chain submission tracker for create_job and fund #102 closes that with isKnown, and feat(server): chain submission store, sendTransaction and tracker for create_job and fund #100 won't land alone.
• AuthorizationExpired / HireAlreadyRated: confirmed, they arrive with their purposes (setAgentWallet / giveFeedback). This PR only covers create_job and fund.
• Starvation: handled in feat(server): chain submission tracker for create_job and fund #102 with recordCheck.

Suite after the fix: 197 passed (integration included).

[moises-cisneros]

Re-checked the updated branch locally: dart analyze is clean and dart test passes (197 tests, integration included). The recordSend guard in 526f3ad does what I asked, and the shared contract test covers both the in-memory fake and the Serverpod store. Thanks for the quick fix.

Approving. The sendTransaction hash check moving to #101 is fine with me.

[TOMOKI977]

Merged into main as c549139 (squash), with #102 included. Thanks @moises-cisneros for the two review rounds.

Before merging I added a narrow gitleaks allowlist for "key_hash": "<64 hex>" (c1c81de). The recorded testnet getTransaction fixtures carry public ledger key hashes that the generic-api-key rule flagged once this code reached a PR against main.

What this means for #96: the store, sendTransaction, the tracker and the EscrowEffects port are now on main, so you can build on them directly. Rebase onto main and recreate your migration on top of chain_submission's to avoid a migration_registry.txt conflict. PULS3_TRACKER_ENABLED stays off until #96 provides real, idempotent effects. #97 stays open for submit, release, claim_refund and the domain effects, and the hardening items are in #101.