feat(stellar): attach unique snippet memo references and link transactions to snippets

[ajetunmobiabdulsamad]

Overview

Stellar transactions that touch a snippet now carry a unique snippet reference in the transaction memo, and every submitted transaction is linked back to its snippet in the database. References respect Stellar's 28-byte memo_text limit and are validated: an over-long or malformed memo is rejected rather than silently truncated.

Related Issue

Issue #194 — Implement Stellar Memo-Based Snippet References.

Changes

Snippet memo references

• [ADD] lib/snippet-memo.ts

  • generateSnippetMemoRef(snippetId) produces a deterministic snip:<12 hex> reference (17 bytes) — one reference per snippet, so references cannot collide.
  • buildSnippetMemo(snippetId, contentHash?) produces snip:<ref> / snip:<ref>:<hash8> (26 bytes max); buildBatchSnippetMemo(batchHash) produces snipb:<12 hex> (18 bytes) for batch anchors.
  • assertMemoWithinStellarLimit enforces the 28-byte limit in bytes (multi-byte aware) and throws instead of truncating; assertSnippetMemoRef rejects malformed references.
  • parseSnippetMemo / parseBatchSnippetMemo resolve a reference back from an on-chain memo.

• [ADD] lib/snippet-memo.test.ts

  • Unit tests for determinism, per-snippet uniqueness, byte-limit enforcement (including a 30-byte multi-byte value) and rejection of legacy s: / lic: / tr: memos and malformed references.

Transaction ↔ snippet association

• [ADD] lib/snippet-transaction.types.ts

  • SnippetTransaction (pending / confirmed / failed), its row shape and link params.

• [ADD] lib/snippet-transaction.repository.ts

  • linkPending upserts the association (unique per snippet_id + transaction_hash) and validates the memo reference before writing.
  • markConfirmed (records the ledger sequence), markFailed, findBySnippetId, findByTransactionHash, findByMemoRef.

• [ADD] scripts/add-snippet-transactions.sql

  • snippet_transactions table plus lookup indexes, matching the schema in the issue.

• [ADD] lib/snippet-transaction-association.test.ts

  • Service-level tests for linking, batch linking, a missing memo reference, association persistence failure and failed submission.

Wiring

• [MODIFY] lib/stellar.ts

  • StellarSubmitResult exposes memoRef from every submit helper.
  • Hash anchoring, ownership transfer, license mint and batch paths build memos with buildSnippetMemo / buildBatchSnippetMemo; the previous buildMemo and buildOwnershipTransferMemo helpers (which trimmed the tr: memo with .slice(0, 28)) are removed.

• [MODIFY] lib/stellar-recovery.service.ts

  • After a successful submission the returned memoRef is linked to every referenced snippet (snippetId, or every snippets[].id for a batch).
  • Confirmation flips the association to confirmed with the ledger sequence; a dead transaction flips an existing association to failed.
  • Association writes are best-effort and never abort the transaction flow, and no row is written when the memo reference is missing — so no orphaned associations.
  • getSnippetTransactions(snippetId) exposes the association history.

• [MODIFY] lib/activity-logger.ts

  • New audit actions: stellar.memo.attached, snippet.transaction.linked, snippet.transaction.confirmed, snippet.transaction.failed.

• [MODIFY] app/api/snippets/[id]/transaction-status/route.ts

  • Returns snippetTransactions (memo reference, transaction hash, ledger sequence, status) alongside the existing recovery transactions.

Verification Results

Implemented through the GitHub Git Data API only (no local clone). The author did not run pnpm lint or pnpm test --runInBand locally, so the repository's checks are reported by CI rather than by this PR body. The new tests are limited to pure memo helpers and a mocked StellarRecoveryService, so no database or network access is required.

Acceptance criteria mapping:
- Transaction memo includes snippet reference — snip:<ref> memo on anchor / license / transfer / batch paths
- Confirmed transactions linked to snippets — linkPending on submit, markConfirmed with ledger sequence
- Failed transactions handled — markFailed, and nothing written when no memo reference is returned
- No duplicate references — deterministic per-snippet reference + unique (snippet_id, transaction_hash)
- Traceability — GET /api/snippets/[id]/transaction-status returns snippetTransactions
- Audit logging — stellar.memo.attached, snippet.transaction.linked/.confirmed/.failed

Acceptance Criteria	Status
Transaction memo includes snippet reference	✅ buildSnippetMemo used by every snippet submit path
Confirmed transactions linked to snippets	✅ linkPending then markConfirmed with ledger sequence
Failed transactions handled	✅ markFailed; no association without a memo reference
No duplicate references	✅ deterministic snip:<ref> + unique (snippet_id, transaction_hash)
Traceability supported	✅ snippetTransactions array on the snippet transaction-status endpoint
Audit logging	✅ four new appendActivityLog actions

Closes #194

[vercel]

@ajetunmobiabdulsamad is attempting to deploy a commit to the Sudipta 's projects Team on Vercel.

A member of the Team first needs to authorize it.

[drips-wave]

@ajetunmobiabdulsamad 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