feat(s3,s4): project scaffolds — S3 Fiat On-Ramp + S4 Blockchain & Custody (STA-119, STA-131) (#117)

Phase 3 kickoff: scaffold both services in parallel.

S3 Fiat On-Ramp (fiat-on-ramp/):
- 3 Gradle modules (api, client, app)
- V1 migration: 7 tables (collection_orders, psp_transactions, refunds,
  reconciliation_records, 3 Namastack outbox)
- 5 domain event records, 2 API DTOs, ApiError, Feign client
- SecurityConfig, FallbackAdaptersConfig, 8 ArchUnit tests

S4 Blockchain & Custody (blockchain-custody/):
- 3 Gradle modules (api, client, app)
- V1 migration: 11 tables (wallets, wallet_balances, chain_transfers,
  transfer_participants, transfer_lifecycle_events, wallet_nonces,
  chain_selection_log, wallet_status_audit_log, 3 Namastack outbox)
- V2 seed: dev wallets for Base Sepolia testnet
- 4 domain event records, 2 API DTOs, ApiError, Feign client
- SecurityConfig, FallbackAdaptersConfig, 8 ArchUnit tests

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: Puneethkumarck

blockchain-custody/blockchain-custody-api/build.gradle.kts

@@ -0,0 +1,16 @@
+plugins {
+    `java-library`
+}
+
+dependencies {
+    api("jakarta.validation:jakarta.validation-api")
+    api("com.fasterxml.jackson.core:jackson-annotations")
+
+    testImplementation("org.junit.jupiter:junit-jupiter")
+    testImplementation("org.assertj:assertj-core")
+    testRuntimeOnly("org.junit.platform:junit-platform-launcher")
+}
+
+tasks.withType<Test> {
+    useJUnitPlatform()
+}

blockchain-custody/blockchain-custody-api/src/main/java/com/stablecoin/payments/custody/api/ApiError.java

@@ -0,0 +1,20 @@
+package com.stablecoin.payments.custody.api;
+
+import java.util.List;
+import java.util.Map;
+
+public record ApiError(
+        String code,
+        String status,
+        String message,
+        Map<String, List<String>> errors
+) {
+    public static ApiError of(String code, String status, String message) {
+        return new ApiError(code, status, message, Map.of());
+    }
+
+    public static ApiError withErrors(String code, String status, String message,
+                                      Map<String, List<String>> errors) {
+        return new ApiError(code, status, message, errors);
+    }
+}

blockchain-custody/blockchain-custody-api/src/main/java/com/stablecoin/payments/custody/api/TransferResponse.java

@@ -0,0 +1,23 @@
+package com.stablecoin.payments.custody.api;
+
+import java.time.Instant;
+import java.util.UUID;
+
+public record TransferResponse(
+        UUID transferId,
+        UUID paymentId,
+        String status,
+        String chainId,
+        String stablecoin,
+        String amount,
+        String fromAddress,
+        String toAddress,
+        String txHash,
+        String blockNumber,
+        Integer confirmations,
+        String gasUsed,
+        String gasPriceGwei,
+        Integer estimatedConfirmationS,
+        Instant confirmedAt,
+        Instant createdAt
+) {}

blockchain-custody/blockchain-custody-api/src/main/java/com/stablecoin/payments/custody/api/WalletBalanceResponse.java

@@ -0,0 +1,21 @@
+package com.stablecoin.payments.custody.api;
+
+import java.time.Instant;
+import java.util.List;
+import java.util.UUID;
+
+public record WalletBalanceResponse(
+        UUID walletId,
+        String address,
+        String chainId,
+        List<BalanceEntry> balances,
+        Instant updatedAt
+) {
+    public record BalanceEntry(
+            String stablecoin,
+            String availableBalance,
+            String reservedBalance,
+            String blockchainBalance,
+            String lastIndexedBlock
+    ) {}
+}

blockchain-custody/blockchain-custody-api/src/main/java/com/stablecoin/payments/custody/api/events/ChainReturnConfirmed.java

@@ -0,0 +1,20 @@
+package com.stablecoin.payments.custody.api.events;
+
+import java.time.Instant;
+import java.util.UUID;
+
+public record ChainReturnConfirmed(
+        String schemaVersion,
+        UUID eventId,
+        String eventType,
+        UUID transferId,
+        UUID parentTransferId,
+        UUID paymentId,
+        UUID correlationId,
+        String chainId,
+        String txHash,
+        Instant confirmedAt
+) {
+    public static final String EVENT_TYPE = "chain.return.confirmed";
+    public static final String SCHEMA_VERSION = "1.0";
+}

blockchain-custody/blockchain-custody-api/src/main/java/com/stablecoin/payments/custody/api/events/ChainTransferConfirmed.java

@@ -0,0 +1,22 @@
+package com.stablecoin.payments.custody.api.events;
+
+import java.time.Instant;
+import java.util.UUID;
+
+public record ChainTransferConfirmed(
+        String schemaVersion,
+        UUID eventId,
+        String eventType,
+        UUID transferId,
+        UUID paymentId,
+        UUID correlationId,
+        String chainId,
+        String txHash,
+        String blockNumber,
+        Integer confirmations,
+        String gasUsed,
+        Instant confirmedAt
+) {
+    public static final String EVENT_TYPE = "chain.transfer.confirmed";
+    public static final String SCHEMA_VERSION = "1.0";
+}

blockchain-custody/blockchain-custody-api/src/main/java/com/stablecoin/payments/custody/api/events/ChainTransferFailed.java

@@ -0,0 +1,20 @@
+package com.stablecoin.payments.custody.api.events;
+
+import java.time.Instant;
+import java.util.UUID;
+
+public record ChainTransferFailed(
+        String schemaVersion,
+        UUID eventId,
+        String eventType,
+        UUID transferId,
+        UUID paymentId,
+        UUID correlationId,
+        String chainId,
+        String reason,
+        String errorCode,
+        Instant failedAt
+) {
+    public static final String EVENT_TYPE = "chain.transfer.failed";
+    public static final String SCHEMA_VERSION = "1.0";
+}

blockchain-custody/blockchain-custody-api/src/main/java/com/stablecoin/payments/custody/api/events/ChainTransferSubmitted.java

@@ -0,0 +1,23 @@
+package com.stablecoin.payments.custody.api.events;
+
+import java.time.Instant;
+import java.util.UUID;
+
+public record ChainTransferSubmitted(
+        String schemaVersion,
+        UUID eventId,
+        String eventType,
+        UUID transferId,
+        UUID paymentId,
+        UUID correlationId,
+        String chainId,
+        String stablecoin,
+        String amount,
+        String txHash,
+        String fromAddress,
+        String toAddress,
+        Instant submittedAt
+) {
+    public static final String EVENT_TYPE = "chain.transfer.submitted";
+    public static final String SCHEMA_VERSION = "1.0";
+}

blockchain-custody/blockchain-custody-client/build.gradle.kts

@@ -0,0 +1,16 @@
+plugins {
+    `java-library`
+}
+
+dependencies {
+    api(project(":blockchain-custody:blockchain-custody-api"))
+    implementation("org.springframework.cloud:spring-cloud-starter-openfeign")
+
+    testImplementation("org.junit.jupiter:junit-jupiter")
+    testImplementation("org.assertj:assertj-core")
+    testRuntimeOnly("org.junit.platform:junit-platform-launcher")
+}
+
+tasks.withType<Test> {
+    useJUnitPlatform()
+}

blockchain-custody/blockchain-custody-client/src/main/java/com/stablecoin/payments/custody/client/BlockchainCustodyClient.java

@@ -0,0 +1,19 @@
+package com.stablecoin.payments.custody.client;
+
+import com.stablecoin.payments.custody.api.TransferResponse;
+import com.stablecoin.payments.custody.api.WalletBalanceResponse;
+import org.springframework.cloud.openfeign.FeignClient;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.PathVariable;
+
+import java.util.UUID;
+
+@FeignClient(name = "blockchain-custody-service", url = "${app.services.blockchain-custody.url}")
+public interface BlockchainCustodyClient {
+
+    @GetMapping(value = "/v1/transfers/{transferId}", produces = "application/json")
+    TransferResponse getTransfer(@PathVariable("transferId") UUID transferId);
+
+    @GetMapping(value = "/v1/wallets/{walletId}/balance", produces = "application/json")
+    WalletBalanceResponse getWalletBalance(@PathVariable("walletId") UUID walletId);
+}