feat: support for Stacks 2.1 stx-transfer event memo field (#1285)

* feat: support for Stacks 2.1 stx-transfer event memo field (the `stx-transfer-memo` Clarity2 function)

* fix: remove null memo field from different asset transfer events

* test: unit tests for Stacks 2.1 stx-transfer event memo field

Author: zone117x

docs/entities/transaction-events/asset-types/transaction-event-asset.schema.json

@@ -20,6 +20,9 @@
     },
     "value": {
       "type": "string"
+    },
+    "memo": {
+      "type": "string"
     }
   }
 }

docs/generated.d.ts

@@ -747,6 +747,7 @@ export interface TransactionEventAsset {
   recipient?: string;
   amount?: string;
   value?: string;
+  memo?: string;
 }
 /**
  * GET request that returns address balances

src/api/controllers/db-controller.ts

@@ -243,6 +243,9 @@ export function parseDbEvent(dbEvent: DbEvent): TransactionEvent {
           amount: dbEvent.amount.toString(10),
         },
       };
+      if (dbEvent.asset_event_type_id === DbAssetEventTypeId.Transfer && dbEvent.memo) {
+        event.asset.memo = dbEvent.memo;
+      }
       return event;
     }
     case DbEventTypeId.FungibleTokenAsset: {

src/datastore/common.ts

@@ -325,6 +325,7 @@ interface DbAssetEvent extends DbEventBase {
 export interface DbStxEvent extends DbAssetEvent {
   event_type: DbEventTypeId.StxAsset;
   amount: bigint;
+  memo?: string;
 }
 
 interface DbContractAssetEvent extends DbAssetEvent {
@@ -1009,6 +1010,7 @@ export interface StxEventInsertValues {
   sender: string | null;
   recipient: string | null;
   amount: bigint;
+  memo: PgBytea | null;
 }
 
 export interface MinerRewardInsertValues {

src/datastore/helpers.ts

@@ -398,6 +398,7 @@ export function parseDbEvents(
     sender?: string | undefined;
     recipient?: string | undefined;
     amount: string;
+    memo?: string;
   }[],
   ftResults: {
     event_index: number;
@@ -469,6 +470,9 @@ export function parseDbEvents(
       event_type: DbEventTypeId.StxAsset,
       amount: BigInt(result.amount),
     };
+    if (result.memo) {
+      event.memo = result.memo;
+    }
     events[rowIndex++] = event;
   }
   for (const result of ftResults) {
@@ -554,6 +558,7 @@ export function parseTxsWithAssetTransfers(
     event_recipient?: string | undefined;
     event_asset_identifier?: string | undefined;
     event_value?: string | undefined;
+    event_memo?: string | undefined;
   })[],
   stxAddress: string
 ) {
@@ -567,6 +572,7 @@ export function parseTxsWithAssetTransfers(
         amount: bigint;
         sender?: string;
         recipient?: string;
+        memo?: string;
       }[];
       ft_transfers: {
         asset_identifier: string;
@@ -606,6 +612,7 @@ export function parseTxsWithAssetTransfers(
             amount: eventAmount,
             sender: r.event_sender,
             recipient: r.event_recipient,
+            memo: r.event_memo,
           });
           if (r.event_sender === stxAddress) {
             txResult.stx_sent += eventAmount;

src/datastore/pg-store.ts

@@ -959,6 +959,9 @@ export class PgStore {
     includeUnanchored: boolean;
     includePruned?: boolean;
   }): Promise<DbMempoolTx[]> {
+    if (args.txIds.length === 0) {
+      return [];
+    }
     return this.sql.begin(async client => {
       const result = await this.sql<MempoolTxQueryResult[]>`
         SELECT ${unsafeCols(this.sql, [...MEMPOOL_TX_COLUMNS, abiColumn('mempool_txs')])}
@@ -1441,10 +1444,11 @@ export class PgStore {
           sender?: string;
           recipient?: string;
           amount: string;
+          memo?: string;
         }[]
       >`
         SELECT
-          event_index, tx_id, tx_index, block_height, canonical, asset_event_type_id, sender, recipient, amount
+          event_index, tx_id, tx_index, block_height, canonical, asset_event_type_id, sender, recipient, amount, memo
         FROM stx_events
         WHERE (tx_id, index_block_hash) IN (VALUES ${sql.unsafe(transactionValues)})
           AND microblock_canonical = true AND event_index BETWEEN ${eventIndexStart} AND ${eventIndexEnd}
@@ -1554,10 +1558,11 @@ export class PgStore {
           sender?: string;
           recipient?: string;
           amount: string;
+          memo?: string;
         }[]
       >`
         SELECT
-          event_index, tx_id, tx_index, block_height, canonical, asset_event_type_id, sender, recipient, amount
+          event_index, tx_id, tx_index, block_height, canonical, asset_event_type_id, sender, recipient, amount, memo
         FROM stx_events
         WHERE tx_id = ${args.txId} AND index_block_hash = ${args.indexBlockHash}
           AND microblock_canonical = true AND event_index BETWEEN ${eventIndexStart} AND ${eventIndexEnd}
@@ -1643,7 +1648,7 @@ export class PgStore {
     return this.sql.begin(async sql => {
       const refValue = args.addressOrTxId.address ?? args.addressOrTxId.txId;
       const isAddress = args.addressOrTxId.address !== undefined;
-      const emptyEvents = sql`SELECT NULL,NULL,NULL,NULL,NULL,NULL,NULL,NULL,NULL,NULL,NULL,NULL,NULL,NULL`;
+      const emptyEvents = sql`SELECT NULL,NULL,NULL,NULL,NULL,NULL,NULL,NULL,NULL,NULL,NULL,NULL,NULL,NULL,NULL`;
       const eventsResult = await sql<
         {
           tx_id: string;
@@ -1653,6 +1658,7 @@ export class PgStore {
           sender: string;
           recipient: string;
           amount: number;
+          memo: string;
           unlock_height: number;
           asset_identifier: string;
           contract_identifier: string;
@@ -1669,7 +1675,7 @@ export class PgStore {
                 SELECT
                   tx_id, event_index, tx_index, block_height, locked_address as sender, NULL as recipient,
                   locked_amount as amount, unlock_height, NULL as asset_identifier, NULL as contract_identifier,
-                  '0'::bytea as value, NULL as topic,
+                  '0'::bytea as value, NULL as topic, null::bytea as memo,
                   ${DbEventTypeId.StxLock}::integer as event_type_id, 0 as asset_event_type_id
                 FROM stx_lock_events
                 WHERE ${isAddress ? sql`locked_address = ${refValue}` : sql`tx_id = ${refValue}`}
@@ -1684,7 +1690,7 @@ export class PgStore {
                 SELECT
                   tx_id, event_index, tx_index, block_height, sender, recipient,
                   amount, 0 as unlock_height, NULL as asset_identifier, NULL as contract_identifier,
-                  '0'::bytea as value, NULL as topic,
+                  '0'::bytea as value, NULL as topic, memo,
                   ${DbEventTypeId.StxAsset}::integer as event_type_id, asset_event_type_id
                 FROM stx_events
                 WHERE ${
@@ -1703,7 +1709,7 @@ export class PgStore {
                 SELECT
                   tx_id, event_index, tx_index, block_height, sender, recipient,
                   amount, 0 as unlock_height, asset_identifier, NULL as contract_identifier,
-                  '0'::bytea as value, NULL as topic,
+                  '0'::bytea as value, NULL as topic, null::bytea as memo,
                   ${DbEventTypeId.FungibleTokenAsset}::integer as event_type_id, asset_event_type_id
                 FROM ft_events
                 WHERE ${
@@ -1722,7 +1728,7 @@ export class PgStore {
                 SELECT
                   tx_id, event_index, tx_index, block_height, sender, recipient,
                   0 as amount, 0 as unlock_height, asset_identifier, NULL as contract_identifier,
-                  value, NULL as topic,
+                  value, NULL as topic, null::bytea as memo,
                   ${DbEventTypeId.NonFungibleTokenAsset}::integer as event_type_id,
                   asset_event_type_id
                 FROM nft_events
@@ -1742,7 +1748,7 @@ export class PgStore {
                 SELECT
                   tx_id, event_index, tx_index, block_height, NULL as sender, NULL as recipient,
                   0 as amount, 0 as unlock_height, NULL as asset_identifier, contract_identifier,
-                  value, topic,
+                  value, topic, null::bytea as memo,
                   ${DbEventTypeId.SmartContractLog}::integer as event_type_id,
                   0 as asset_event_type_id
                 FROM contract_logs
@@ -1783,6 +1789,9 @@ export class PgStore {
             canonical: true,
             asset_event_type_id: r.asset_event_type_id,
           };
+          if (event.event_type === DbEventTypeId.StxAsset && r.memo) {
+            event.memo = r.memo;
+          }
           return event;
         });
       }
@@ -2191,6 +2200,7 @@ export class PgStore {
         recipient?: string;
         asset_identifier: string;
         amount?: string;
+        memo?: string;
         unlock_height?: string;
         value?: string;
       } & { count: number })[]
@@ -2199,25 +2209,25 @@ export class PgStore {
       FROM(
         SELECT
           'stx_lock' as asset_type, event_index, tx_id, microblock_sequence, tx_index, block_height, canonical, 0 as asset_event_type_id,
-          locked_address as sender, '' as recipient, '<stx>' as asset_identifier, locked_amount as amount, unlock_height, null::bytea as value
+          locked_address as sender, '' as recipient, '<stx>' as asset_identifier, locked_amount as amount, unlock_height, null::bytea as value, null::bytea as memo
         FROM stx_lock_events
         WHERE canonical = true AND microblock_canonical = true AND locked_address = ${stxAddress} AND block_height <= ${blockHeight}
         UNION ALL
         SELECT
           'stx' as asset_type, event_index, tx_id, microblock_sequence, tx_index, block_height, canonical, asset_event_type_id,
-          sender, recipient, '<stx>' as asset_identifier, amount::numeric, null::numeric as unlock_height, null::bytea as value
+          sender, recipient, '<stx>' as asset_identifier, amount::numeric, null::numeric as unlock_height, null::bytea as value, memo
         FROM stx_events
         WHERE canonical = true AND microblock_canonical = true AND (sender = ${stxAddress} OR recipient = ${stxAddress}) AND block_height <= ${blockHeight}
         UNION ALL
         SELECT
           'ft' as asset_type, event_index, tx_id, microblock_sequence, tx_index, block_height, canonical, asset_event_type_id,
-          sender, recipient, asset_identifier, amount, null::numeric as unlock_height, null::bytea as value
+          sender, recipient, asset_identifier, amount, null::numeric as unlock_height, null::bytea as value, null::bytea as memo
         FROM ft_events
         WHERE canonical = true AND microblock_canonical = true AND (sender = ${stxAddress} OR recipient = ${stxAddress}) AND block_height <= ${blockHeight}
         UNION ALL
         SELECT
           'nft' as asset_type, event_index, tx_id, microblock_sequence, tx_index, block_height, canonical, asset_event_type_id,
-          sender, recipient, asset_identifier, null::numeric as amount, null::numeric as unlock_height, value
+          sender, recipient, asset_identifier, null::numeric as amount, null::numeric as unlock_height, value, null::bytea as memo
         FROM nft_events
         WHERE canonical = true AND microblock_canonical = true AND (sender = ${stxAddress} OR recipient = ${stxAddress}) AND block_height <= ${blockHeight}
       ) asset_events
@@ -2253,6 +2263,9 @@ export class PgStore {
           event_type: DbEventTypeId.StxAsset,
           amount: BigInt(row.amount ?? 0),
         };
+        if (row.memo) {
+          event.memo = row.memo;
+        }
         return event;
       } else if (row.asset_type === 'ft') {
         const event: DbFtEvent = {
@@ -2468,6 +2481,7 @@ export class PgStore {
         event_amount?: string;
         event_sender?: string;
         event_recipient?: string;
+        event_memo?: string;
       })[]
     >`
       WITH transactions AS (
@@ -2508,6 +2522,7 @@ export class PgStore {
         events.amount as event_amount,
         events.sender as event_sender,
         events.recipient as event_recipient,
+        events.memo as event_memo,
         ${this.sql.unsafe(abiColumn('transactions'))}
       FROM transactions
       LEFT JOIN events ON transactions.tx_id = events.tx_id

src/datastore/pg-write-store.ts

@@ -709,6 +709,7 @@ export class PgWriteStore extends PgStore {
         sender: event.sender ?? null,
         recipient: event.recipient ?? null,
         amount: event.amount,
+        memo: event.memo ?? null,
       }));
       const res = await sql`
         INSERT INTO stx_events ${sql(values)}
@@ -874,6 +875,7 @@ export class PgWriteStore extends PgStore {
       sender: event.sender ?? null,
       recipient: event.recipient ?? null,
       amount: event.amount,
+      memo: event.memo ?? null,
     };
     await sql`
       INSERT INTO stx_events ${sql(values)}

src/event-stream/core-node-message.ts

@@ -43,6 +43,8 @@ export interface StxTransferEvent extends CoreNodeEventBase {
     recipient: string;
     sender: string;
     amount: string;
+    /** Hex-encoded string. Only provided when a memo was specified in the Clarity `stx-transfer?` function (requires a Stacks 2.1 contract). */
+    memo?: string;
   };
 }
 

src/event-stream/event-server.ts

@@ -453,6 +453,7 @@ function parseDataStoreTxEventData(
           sender: event.stx_transfer_event.sender,
           recipient: event.stx_transfer_event.recipient,
           amount: BigInt(event.stx_transfer_event.amount),
+          memo: event.stx_transfer_event.memo ? '0x' + event.stx_transfer_event.memo : undefined,
         };
         dbTx.stxEvents.push(entry);
         break;

src/migrations/1588252682585_stx_events.ts

@@ -56,6 +56,7 @@ export async function up(pgm: MigrationBuilder): Promise<void> {
     },
     sender: 'string',
     recipient: 'string',
+    memo: 'bytea',
   });
 
   pgm.createIndex('stx_events', 'tx_id', { method: 'hash' });