PR: Transaction Memo & Metadata Storage

[clintjeff2]

PR: Transaction Memo & Metadata Storage

Branch: feature/issue-45-transaction-metadata
Target: develop
Issue: #89 — Transaction Memo & Metadata Storage

---

Summary

Extends the transaction model to support a human-readable memo field, a memo_type classifier, and an arbitrary metadata JSONB column. This allows richer context from the Anchor Platform (memo, memo_type) and partner-defined key-value data (reference IDs, customer notes, compliance tags) to flow through the bridge pipeline.

All new fields are nullable — existing integrations are fully backward-compatible.

---

Changes

Migration

• migrations/20260222000000_transaction_memo_metadata.sql — Adds memo (TEXT), memo_type (VARCHAR(10)), and metadata (JSONB) columns to the transactions table, all nullable.

Model Layer

• src/db/models.rs — Added memo, memo_type, metadata fields to the Transaction struct. Updated Transaction::new() to accept the new parameters. Updated all existing unit tests.
• src/domain/transaction.rs — Mirrored the new fields in the domain-layer Transaction entity. Updated Transaction::new().
• src/schemas.rs — Added memo, memo_type, metadata to TransactionSchema for OpenAPI documentation.

Data Access

• src/db/queries.rs — Updated insert_transaction to persist the new columns. Updated audit log payload to include memo and metadata.
• src/adapters/postgres_transaction_repository.rs — Updated TransactionRow, INSERT query, and into_domain() conversion to include the new fields.

Handler Layer

• src/handlers/webhook.rs — Introduced CallbackPayload struct with memo, memo_type, and metadata fields. Implemented the callback handler to parse, validate memo_type (must be text, hash, or id), create and persist a Transaction, and return 201 Created. Updated get_transaction to expose all fields including memo/metadata in responses.

Service / Use Case Layer

• src/use_cases/process_deposit.rs — Added memo, memo_type, metadata to DepositInput and passed through to Transaction::new().
• src/services/processor.rs — Updated the explicit SELECT column list in the background processor to include the new columns.

Configuration

• Cargo.toml — Added "json" feature to sqlx for JSONB serialization/deserialization.

Tests

• tests/integration_test.rs — Added five new integration test cases:
  • test_callback_with_memo_and_metadata — full payload with memo, memo_type, and metadata; verifies persistence and retrieval.
  • test_callback_with_hash_memo_type — validates hash memo_type acceptance.
  • test_callback_with_invalid_memo_type — verifies 400 rejection for invalid memo_type values.
  • test_callback_with_metadata_only — metadata without memo fields; confirms partial payloads work.
  • Existing test_valid_deposit_flow updated to assert null memo/metadata on plain payloads.

---

Proof of Implementation

Build Success

---

How to Verify

# 1. Run the migration
sqlx migrate run

# 2. Build
cargo build

# 3. Run tests
cargo test

# 4. Manual test — POST /callback with memo + metadata
curl -X POST http://localhost:3000/callback \
  -H "Content-Type: application/json" \
  -H "X-App-Signature: valid-signature" \
  -d '{
    "stellar_account": "GABC1234567890",
    "amount": "250.00",
    "asset_code": "USDC",
    "callback_type": "deposit",
    "callback_status": "completed",
    "memo": "payment for invoice #1042",
    "memo_type": "text",
    "metadata": {"reference_id": "INV-1042", "customer_note": "Monthly sub"}
  }'

# 5. Retrieve and verify fields are present
curl http://localhost:3000/transactions/<id-from-step-4>

Closes #89