feat: escrow contract scaffolding, cancel_and_refund guards, doc updates, and database migration runner (#149, #151, #156, #157)

[GF-Hunter]

Description

This pull request addresses and resolves issues #149, #151, #156, and #157 across the escrow smart contract and server layers:

1. Escrow Contract Scaffolding ([contract] - Create contracts/escrow/ Rust Project Scaffold with Cargo.toml #149):

   • Configured contracts/escrow/Cargo.toml with soroban-sdk = { workspace = true, features = ["alloc"] } to provide the required memory allocator for wasm32-unknown-unknown and wasm32v1-none targets.
   • Added #![no_std] and extern crate alloc; to contracts/escrow/src/lib.rs.
   • Verified contract build passes cleanly with stellar contract build producing the compiled .wasm artifact.

2. Contract Documentation Correction and Function Reordering ([contract] - Fix Incorrect Contract Function Name in contracts/readme.md #151):

   • Corrected canonical function documentation in contracts/readme.md by replacing occurrences of Notesing with create_listing.
   • Updated parameter specifications for create_listing to include expires_at: u64 and documented that expires_at is validated to be in the future.
   • Added return type specifications (Returns: u64 for create_listing, Returns: () for deposit_to_escrow, release_payment, and cancel_and_refund).
   • Reordered ## ⚡ Contract Functions in logical execution order: create_listing → deposit_to_escrow → release_payment → cancel_and_refund.
   • Added Last Updated: August 28, 2026 to the top of contracts/readme.md.

3. Caller Guard & Timelock Validation for cancel_and_refund ([contract] - Add cancel_and_refund Caller Guard (Buyer or Admin Only) #156):

   • Added Unauthorized and TimelockNotExpired variants to ContractError.
   • Enforced caller authorization asserting that only the buyer or the contract admin can invoke cancel_and_refund.
   • Enforced 24-hour timelock check for buyer cancellations (now < trade.expires_at), while bypassing timelock checks for admin cancellations to permit immediate dispute resolution.
   • Documented the caller guard and admin timelock bypass in contracts/readme.md.
   • Added comprehensive unit tests in contracts/escrow/src/lib.rs covering buyer after timelock, buyer before timelock, admin immediate cancellation, and seller rejection.

4. Standalone Database Schema Migration CLI Runner ([server] - Add server/src/db/migrate.ts CLI Script to Run Migrations at Startup #157):

   • Implemented server/src/db/migrate.ts standalone CLI runner that sequentially executes .sql files from server/src/db/migrations/ in lexicographical order against DATABASE_URL.
   • Tracks applied migrations in the schema_migrations table (id SERIAL PRIMARY KEY, filename TEXT UNIQUE NOT NULL, applied_at TIMESTAMPTZ NOT NULL DEFAULT NOW()), skipping already-applied files.
   • Added "db:migrate": "ts-node src/db/migrate.ts" and "db:migrate:rollback": "ts-node src/db/migrate.ts rollback" scripts to server/package.json.
   • Added rollback support removing the most recent migration entry from schema_migrations and outputting the filename for manual SQL reversal.
   • Prints No pending migrations and exits 0 when no migrations are pending.
   • Added unit test suite in server/src/db/migrate.test.ts mocking PostgreSQL pool and asserting migration application, skipping, and rollback behavior.

Issues Closed

Closes #149
Closes #151
Closes #156
Closes #157

[drips-wave]

@GF-Hunter 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