Merge pull request #1077 from input-output-hk/feat/lw-9678-resolve-collateral-return-property

feat(cardano-services): resolve collateralReturn property

Author: renanvalentin

packages/cardano-services/src/ChainHistory/DbSyncChainHistory/ChainHistoryBuilder.ts

@@ -51,7 +51,7 @@ export class ChainHistoryBuilder {
   public async queryTransactionInputsByIds(ids: string[], collateral = false): Promise<TxInput[]> {
     this.#logger.debug(`About to find inputs (collateral: ${collateral}) for transactions with ids:`, ids);
     const result: QueryResult<TxInputModel> = await this.#db.query({
-      name: `tx_${collateral ? 'collateral' : 'inputs'}_by_tx_ids`,
+      name: `tx_${collateral ? 'collateral_' : ''}inputs_by_tx_ids`,
       text: collateral ? Queries.findTxCollateralsByIds : Queries.findTxInputsByIds,
       values: [ids]
     });
@@ -68,11 +68,11 @@ export class ChainHistoryBuilder {
     return mapTxOutTokenMap(result.rows);
   }
 
-  public async queryTransactionOutputsByIds(ids: string[]): Promise<TxOutput[]> {
-    this.#logger.debug('About to find outputs for transactions with ids:', ids);
+  public async queryTransactionOutputsByIds(ids: string[], collateral = false): Promise<TxOutput[]> {
+    this.#logger.debug(`About to find outputs (collateral: ${collateral}) for transactions with ids:`, ids);
     const result: QueryResult<TxOutputModel> = await this.#db.query({
-      name: 'tx_outputs_by_tx_ids',
-      text: Queries.findTxOutputsByIds,
+      name: `tx_${collateral ? 'collateral_' : ''}outputs_by_tx_ids`,
+      text: collateral ? Queries.findCollateralOutputsByTxIds : Queries.findTxOutputsByIds,
       values: [ids]
     });
     if (result.rows.length === 0) return [];

packages/cardano-services/src/ChainHistory/DbSyncChainHistory/DbSyncChainHistoryProvider.ts

@@ -107,29 +107,35 @@ export class DbSyncChainHistoryProvider extends DbSyncProvider() implements Chai
     });
     if (txResults.rows.length === 0) return [];
 
-    const [inputs, outputs, mints, withdrawals, redeemers, metadata, collaterals, certificates] = await Promise.all([
-      this.#builder.queryTransactionInputsByIds(ids),
-      this.#builder.queryTransactionOutputsByIds(ids),
-      this.#builder.queryTxMintByIds(ids),
-      this.#builder.queryWithdrawalsByTxIds(ids),
-      this.#builder.queryRedeemersByIds(ids),
-      // Missing witness datums
-      this.#metadataService.queryTxMetadataByRecordIds(ids),
-      this.#builder.queryTransactionInputsByIds(ids, true),
-      this.#builder.queryCertificatesByIds(ids)
-    ]);
+    const [inputs, outputs, mints, withdrawals, redeemers, metadata, collaterals, certificates, collateralOutputs] =
+      await Promise.all([
+        this.#builder.queryTransactionInputsByIds(ids),
+        this.#builder.queryTransactionOutputsByIds(ids),
+        this.#builder.queryTxMintByIds(ids),
+        this.#builder.queryWithdrawalsByTxIds(ids),
+        this.#builder.queryRedeemersByIds(ids),
+        // Missing witness datums
+        this.#metadataService.queryTxMetadataByRecordIds(ids),
+        this.#builder.queryTransactionInputsByIds(ids, true),
+        this.#builder.queryCertificatesByIds(ids),
+        this.#builder.queryTransactionOutputsByIds(ids, true)
+      ]);
 
     return txResults.rows.map((tx) => {
       const txId = tx.id.toString('hex') as unknown as Cardano.TransactionId;
       const txInputs = orderBy(inputs.filter((input) => input.txInputId === txId).map(mapTxIn), ['index']);
       const txCollaterals = orderBy(collaterals.filter((col) => col.txInputId === txId).map(mapTxIn), ['index']);
       const txOutputs = orderBy(outputs.filter((output) => output.txId === txId).map(mapTxOut), ['index']);
+      const txCollateralOutputs = orderBy(collateralOutputs.filter((output) => output.txId === txId).map(mapTxOut), [
+        'index'
+      ]);
       const inputSource: Cardano.InputSource = tx.valid_contract
         ? Cardano.InputSource.inputs
         : Cardano.InputSource.collaterals;
 
       return mapTxAlonzo(tx, {
         certificates: certificates.get(txId),
+        collateralOutputs: txCollateralOutputs,
         collaterals: txCollaterals,
         inputSource,
         inputs: txInputs,

packages/cardano-services/src/ChainHistory/DbSyncChainHistory/mappers.ts

@@ -185,11 +185,23 @@ interface TxAlonzoData {
   metadata?: Cardano.TxMetadata;
   collaterals?: Cardano.HydratedTxIn[];
   certificates?: Cardano.Certificate[];
+  collateralOutputs?: Cardano.TxOut[];
 }
 
 export const mapTxAlonzo = (
   txModel: TxModel,
-  { inputSource, inputs, outputs, mint, withdrawals, redeemers, metadata, collaterals, certificates }: TxAlonzoData
+  {
+    inputSource,
+    inputs,
+    outputs,
+    mint,
+    withdrawals,
+    redeemers,
+    metadata,
+    collaterals,
+    certificates,
+    collateralOutputs = []
+  }: TxAlonzoData
 ): Cardano.HydratedTx => ({
   auxiliaryData:
     metadata && metadata.size > 0
@@ -204,6 +216,7 @@ export const mapTxAlonzo = (
   },
   body: {
     certificates,
+    collateralReturn: collateralOutputs.length > 0 ? collateralOutputs[0] : undefined,
     collaterals,
     fee: BigInt(txModel.fee),
     inputs,

packages/cardano-services/src/ChainHistory/DbSyncChainHistory/queries.ts

@@ -15,15 +15,15 @@ const selectTxInput = (collateral?: boolean) => `
 	JOIN tx AS source_tx
   		ON tx_out.tx_id = source_tx.id`;
 
-const selectTxOutput = `
+const selectTxOutput = (collateral = false) => `
 	SELECT
 		tx_out.id AS id,
 		tx_out.address AS address,
 		tx_out."index" AS "index",
 		tx_out.value AS coin_value,
 		tx_out.data_hash AS datum,
 		tx.hash AS tx_id
-	FROM tx_out
+	FROM ${collateral ? 'collateral_tx_out' : 'tx_out'} AS tx_out 
 	JOIN tx ON tx_out.tx_id = tx.id`;
 
 export const findTxInputsByIds = `
@@ -45,18 +45,23 @@ export const findTxInputsByAddresses = `
 	ORDER BY tx_in.id ASC`;
 
 export const findTxOutputsByIds = `
-  	${selectTxOutput}
+  	${selectTxOutput()}
   	WHERE tx.id = ANY($1)
 	ORDER BY tx_out.id ASC`;
 
 export const findTxOutputsByAddresses = `
-  ${selectTxOutput}
+  ${selectTxOutput()}
 	JOIN block ON tx.block_id = block.id
   WHERE tx_out.address = ANY($1)
 	AND block.block_no >= $2
 	AND block.block_no <= $3
 	ORDER BY tx_out.id ASC`;
 
+export const findCollateralOutputsByTxIds = `
+	${selectTxOutput(true)}
+	WHERE tx.id = ANY($1)
+  ORDER BY tx_out.id ASC`;
+
 export const findTip = `
 	SELECT 
 		block_no,

packages/cardano-services/test/ChainHistory/ChainHistoryHttpService.test.ts

@@ -324,6 +324,16 @@ describe('ChainHistoryHttpService', () => {
           expect(tx.body.collaterals?.length).toEqual(1);
         });
 
+        it('has collateral outputs', async () => {
+          const response = await provider.transactionsByHashes({
+            ids: await fixtureBuilder.getTxHashes(1, { with: [TxWith.CollateralOutput] })
+          });
+          const tx: Cardano.HydratedTx = response[0];
+          expect(response.length).toEqual(1);
+
+          expect(tx.body.collateralReturn).toMatchShapeOf(DataMocks.Tx.collateralReturn);
+        });
+
         it('has certificates', async () => {
           const response = await provider.transactionsByHashes({
             ids: await fixtureBuilder.getTxHashes(2, { with: [TxWith.DelegationCertificate] })

packages/cardano-services/test/ChainHistory/DbSyncChainHistoryProvider/ChainHistoryBuilder.test.ts

@@ -101,7 +101,7 @@ describe('ChainHistoryBuilder', () => {
       const result = await builder.queryTransactionOutputsByIds(ids);
       expect(result.length).toBeGreaterThanOrEqual(2);
       expect(result[0]).toMatchShapeOf(DataMocks.Tx.txOut);
-      checkLoggedTxIds('About to find outputs for transactions with ids', true);
+      checkLoggedTxIds('About to find outputs \\(collateral: false\\) for transactions with ids', true);
     });
     test('query transaction outputs with empty array', async () => {
       const result = await builder.queryTransactionOutputsByIds([]);

packages/cardano-services/test/ChainHistory/DbSyncChainHistoryProvider/mappers.test.ts

@@ -374,6 +374,7 @@ describe('chain history mappers', () => {
     test('map TxModel to Cardano.HydratedTx with extra data', () => {
       const result = mappers.mapTxAlonzo(txModel, {
         certificates,
+        collateralOutputs: [txOutput],
         collaterals: inputs,
         inputSource,
         inputs,
@@ -386,7 +387,14 @@ describe('chain history mappers', () => {
       expect(result).toEqual<Cardano.HydratedTx>({
         ...expected,
         auxiliaryData: { blob: metadata },
-        body: { ...expected.body, certificates, collaterals: inputs, mint: assets, withdrawals },
+        body: {
+          ...expected.body,
+          certificates,
+          collateralReturn: txOutput,
+          collaterals: inputs,
+          mint: assets,
+          withdrawals
+        },
         witness: { ...expected.witness, redeemers }
       });
     });

packages/cardano-services/test/ChainHistory/fixtures/FixtureBuilder.ts

@@ -17,7 +17,8 @@ export enum TxWith {
   Mint = 'mint',
   MultiAsset = 'multiAsset',
   Redeemer = 'redeemer',
-  Withdrawal = 'withdrawal'
+  Withdrawal = 'withdrawal',
+  CollateralOutput = 'collateralOutput'
 }
 
 export type AddressesInBlockRange = {
@@ -120,6 +121,7 @@ export class ChainHistoryFixtureBuilder {
       if (options.with.includes(TxWith.DelegationCertificate)) query += Queries.latestTxHashesWithDelegationCerts;
       if (options.with.includes(TxWith.MirCertificate)) query += Queries.latestTxHashesWithMirCerts;
       if (options.with.includes(TxWith.Withdrawal)) query += Queries.latestTxHashesWithWithdrawal;
+      if (options.with.includes(TxWith.CollateralOutput)) query += Queries.latestTxHashesWithCollateralOutput;
 
       query += Queries.endLatestTxHashes;
     }

packages/cardano-services/test/ChainHistory/fixtures/queries.ts

@@ -57,6 +57,9 @@ export const latestTxHashesWithMirCerts = `
 export const latestTxHashesWithWithdrawal = `
   JOIN withdrawal ON withdrawal.tx_id = tx.id`;
 
+export const latestTxHashesWithCollateralOutput = `
+  JOIN collateral_tx_out ON collateral_tx_out.tx_id = tx.id`;
+
 export const endLatestTxHashes = `
   GROUP BY tx.id
   ORDER BY tx.id DESC
@@ -101,6 +104,7 @@ const Queries = {
   latestTxHashes,
   latestTxHashesWithAuxiliaryData,
   latestTxHashesWithCollateral,
+  latestTxHashesWithCollateralOutput,
   latestTxHashesWithDelegationCerts,
   latestTxHashesWithMint,
   latestTxHashesWithMirCerts,

packages/cardano-services/test/data-mocks/tx.ts

@@ -114,6 +114,13 @@ export const collateralInputs = [
   }
 ];
 
+export const collateralReturn: Cardano.TxOut = {
+  address: Cardano.PaymentAddress('addr_test1wqnp362vmvr8jtc946d3a3utqgclfdl5y9d3kn849e359hst7hkqk'),
+  value: {
+    coins: 3_681_817_479_100_950n
+  }
+};
+
 export const withValidityInterval: Cardano.HydratedTx = merge(withAssets, {
   body: {
     validityInterval: {