feat: add onChainTransaction to transaction source/destination

openapi/components/schemas/common/ReconciliationInstructions.yaml

@@ -1,5 +1,9 @@
 type: object
 minProperties: 1
+description: >-
+  Instructions for reconciling a payment with this transaction. For the on-chain
+  transaction to or from an external crypto wallet that is the transaction's own source or
+  destination, use the `onChainTransaction` on the relevant source or destination instead.
 properties:
   reference:
     type: string
@@ -10,6 +14,8 @@ properties:
   transactionHash:
     type: string
     description: >-
-      Transaction hash for the crypto transfer that delivered funds to the
-      transaction destination, when available.
+      Transaction hash of the internal settlement transfer used to deliver a UMA payment —
+      the inter-VASP settlement leg (e.g. USDC on Solana to the receiving partner), when
+      available. This is not a transfer to a customer's own wallet; for that, see the
+      `onChainTransaction` on the transaction's source or destination.
     example: "0x9f2c6b6f4b6c8f2a8d9e0b1c2d3e4f5061728394a5b6c7d8e9f00112233445566"

openapi/components/schemas/crypto/CryptoNetwork.yaml

@@ -0,0 +1,19 @@
+type: string
+enum:
+  - ETHEREUM_MAINNET
+  - ETHEREUM_TESTNET
+  - SOLANA_MAINNET
+  - SOLANA_DEVNET
+  - BASE_MAINNET
+  - BASE_TESTNET
+  - POLYGON_MAINNET
+  - POLYGON_TESTNET
+  - TRON_MAINNET
+  - TRON_TESTNET
+  - SPARK_MAINNET
+  - SPARK_REGTEST
+description: >-
+  A blockchain network, including the environment (mainnet vs devnet/testnet/regtest) so an
+  on-chain transaction can be looked up on the correct explorer. Sandbox transactions report
+  the devnet/testnet/regtest variant (e.g. SOLANA_DEVNET).
+example: SOLANA_MAINNET

openapi/components/schemas/transactions/BaseTransactionDestination.yaml

@@ -8,3 +8,10 @@ properties:
     type: string
     description: Currency code for the destination
     example: EUR
+  onChainTransaction:
+    $ref: ./OnChainTransaction.yaml
+    description: >-
+      On-chain transaction that delivered funds to this destination, when the destination is
+      an external crypto wallet. Populated once the crypto transfer has settled; absent for
+      fiat/UMA destinations and for the internal settlement leg of a UMA payment (see
+      `reconciliationInstructions`).

openapi/components/schemas/transactions/BaseTransactionSource.yaml

@@ -8,3 +8,10 @@ properties:
     type: string
     description: Currency code for the source
     example: USD
+  onChainTransaction:
+    $ref: ./OnChainTransaction.yaml
+    description: >-
+      On-chain transaction that delivered funds from this source, when the source is an
+      external crypto wallet. Populated once the crypto transfer has settled; absent for
+      fiat/UMA sources and for the internal settlement leg of a UMA payment (see
+      `reconciliationInstructions`).

openapi/components/schemas/transactions/OnChainTransaction.yaml

@@ -0,0 +1,12 @@
+type: object
+required:
+  - transactionHash
+  - network
+properties:
+  transactionHash:
+    type: string
+    description: On-chain transaction hash of the crypto transfer for this leg of the transaction.
+    example: '4Nd1m6Qkq7RfKuE5vQ9qP9Tn6H94Ueqb4xXHzsAbd8WgpD9k6oRnJm2pQ7sT1uV3wX5yZ6aB8cD9eF0gH1i'
+  network:
+    $ref: ../crypto/CryptoNetwork.yaml
+    description: Blockchain network (incl. environment) the transaction settled on.