Add basic contract event parsing into a human-readable structure

src/events.js

@@ -0,0 +1,44 @@
+import xdr from './xdr';
+
+import { StrKey } from './strkey';
+import { scValToNative } from './scval';
+
+/**
+ * Converts raw diagnostic or contract events into something with a flatter,
+ * human-readable, and understandable structure.
+ *
+ * @param {xdr.DiagnosticEvent[] | xdr.ContractEvent[]} events  either contract
+ *    events or diagnostic events to parse into a friendly format
+ *
+ * @returns {SorobanEvent[]}  a list of human-readable event structures, where
+ *    each element has the following properties:
+ *  - type: a string of one of 'system', 'contract', 'diagnostic
+ *  - contractId?: optionally, a `C...` encoded strkey
+ *  - topics: a list of {@link scValToNative} invocations on the topics
+ *  - data: similarly, a {@link scValToNative} invocation on the raw event data
+ */
+export function humanizeEvents(events) {
+  return events.map((e) => {
+    if (e instanceof xdr.DiagnosticEvent) {
+      return extractEvent(e.event());
+    }
+
+    return extractEvent(e);
+  });
+}
+
+function extractEvent(event) {
+  return {
+    contractId:
+      event.contractId() === null
+        ? ''
+        : StrKey.encodeContract(event.contractId()),
+    type: event.type().name,
+    topics: event
+      .body()
+      .value()
+      .topics()
+      .map((t) => scValToNative(t)),
+    data: scValToNative(event.body().value().data())
+  };
+}

src/index.js

@@ -53,6 +53,7 @@ export { Contract } from './contract';
 export { Address } from './address';
 export * from './numbers';
 export * from './scval';
+export * from './events';
 export * from './sorobandata_builder';
 
 export default module.exports;

test/unit/events_test.js

@@ -0,0 +1,54 @@
+const [nativeToScVal, scValToNative, ScInt, humanizeEvents, xdr] = [
+  StellarBase.nativeToScVal,
+  StellarBase.scValToNative,
+  StellarBase.ScInt,
+  StellarBase.humanizeEvents,
+  StellarBase.xdr
+]; // shorthand
+
+describe('humanizing raw events', function () {
+  const contractId = 'CA3D5KRYM6CB7OWQ6TWYRR3Z4T7GNZLKERYNZGGA5SOAOPIFY6YQGAXE';
+  const topics1 = nativeToScVal([1, 2, 3]).value();
+  const data1 = nativeToScVal({ hello: 'world' });
+
+  // workaround for xdr.ContractEventBody.0(...) being invalid lol
+  const bodyModel = xdr.ContractEventBody.fromXDR('AAAAAAAAAAAAAAAB', 'base64');
+  const cloneAndSet = (newBody) => {
+    const clone = xdr.ContractEventBody.fromXDR(bodyModel.toXDR());
+    clone.v0().topics(newBody.topics);
+    clone.v0().data(newBody.data);
+    return clone;
+  };
+
+  const events = [
+    new xdr.DiagnosticEvent({
+      inSuccessfulContractCall: true,
+      event: new xdr.ContractEvent({
+        ext: new xdr.ExtensionPoint(0),
+        contractId: StellarBase.StrKey.decodeContract(contractId),
+        type: xdr.ContractEventType.contract(),
+        body: cloneAndSet({
+          topics: topics1,
+          data: data1
+        })
+      })
+    })
+  ];
+
+  it('built valid events for testing', function () {
+    // sanity check: valid xdr
+    events.map((e) => e.toXDR());
+  });
+
+  it('makes diagnostic events human-readable', function () {
+    const readable = StellarBase.humanizeEvents(events);
+
+    expect(readable.length).to.equal(events.length, `${events} != ${readable}`);
+    expect(readable[0]).to.eql({
+      type: 'contract',
+      contractId: contractId,
+      topics: topics1.map(scValToNative),
+      data: scValToNative(data1)
+    });
+  });
+});

types/index.d.ts

@@ -1117,6 +1117,18 @@ export function scValToBigInt(scv: xdr.ScVal): bigint;
 export function nativeToScVal(val: any, opts?: { type: ScIntType }): xdr.ScVal;
 export function scValToNative(scv: xdr.ScVal): any;
 
+interface SorobanEvent {
+  type: 'system'|'contract'|'diagnostic';   // xdr.ContractEventType.name
+  contractId?: string;                      // C... encoded strkey
+
+  topics: any[];  // essentially a call of map(event.body.topics, scValToNative)
+  data: any;      // similarly, scValToNative(rawEvent.data);
+}
+
+export function humanizeEvents(
+  events: xdr.DiagnosticEvent[] | xdr.ContractEvent[]
+): SorobanEvent[];
+
 export class SorobanDataBuilder {
   constructor(data?: string | xdr.SorobanTransactionData | null);