Introduce the concept of 'entity' in decoded TX. (#65)

An entity groups related ERC standards, providing an abstraction on what
kind of concept they refer to. In this way, different token interfaces
can co-exist while making it easy to filter for all token transactions
in a block, regardless of the underlying ERC interface (e.g. ERC20,
ERC777 or ERC20+ERC777).

Resolves #58.

Author: Raúl Kripalani

.prettierignore

@@ -1,3 +1,3 @@
+src/abi/*.json
 src/__tests__/data
-src/abi/
 dist/

src/abi/README.md

@@ -0,0 +1,30 @@
+## What's here?
+
+This directory contains the ABIs (Application Binary Interfaces) for all the contract types ethql supports.
+
+We classify supported ABIs in two types:
+
+- Entity: introduces a new application-level concept.
+- Extension: enhances an existing entity with new or modified behaviour. Changes introduced could be public (visible on
+  the ABI) or private.
+
+## Supported ABIs
+
+| Standard | Type      | Entity | Specification | Comments                                                        |
+| -------- | --------- | ------ | ------------- | --------------------------------------------------------------- |
+| ERC20    | Entity    |  Token | [link][1]     |                                                                 |
+| ERC223   | Extension |  Token | [link][2]     | Private ERC20 implementation change. No action needed in ethql. |
+
+## ethql naming scheme
+
+When it comes to transaction decoding and transaction logs, ethql types names explicitly mention the ERC standard of
+entity they refer to. Normally this is the ERC that introduced the entity in the first place.
+
+For example, in the case of ERC20 tokens: `ERC20TokenTransfer`, `ERC20TokenApproval`. This helps avoid ambiguity when
+more than one standard exists for the same entity class, e.g. ERC777 in the case of tokens.
+
+Typed queries (e.g. block -> tokenTransfers) may not refer to specific standards, instead conflating transactions and
+logs pertaining to several standards that relate to the same entity.
+
+[1]: https://github.com/ethereum/EIPs/blob/master/EIPS/eip-20.md
+[2]: https://github.com/ethereum/EIPs/issues/223

src/schema/core.graphql

@@ -196,7 +196,12 @@ input TransactionFilter {
   contractCreation: Boolean
 }
 
+enum Entity {
+  token
+}
+
 interface DecodedTransaction {
+  entity: Entity
   standard: String
   operation: String
 }

src/schema/erc20.graphql

@@ -1,21 +1,12 @@
-# import Account, DecodedTransaction from "core.graphql"
-
-type TokenContract {
-  account: Account
-  symbol: String
-  totalSupply: Long
-}
+# import Account, DecodedTransaction, Entity from "core.graphql"
+# import * from "token.graphql"
 
 interface ERC20Transaction {
   tokenContract: TokenContract
 }
 
-type TokenHolder {
-  account: Account!
-  tokenBalance: Long
-}
-
 type ERC20Transfer implements DecodedTransaction & ERC20Transaction {
+  entity: Entity
   standard: String
   operation: String
   from: TokenHolder
@@ -25,6 +16,7 @@ type ERC20Transfer implements DecodedTransaction & ERC20Transaction {
 }
 
 type ERC20TransferFrom implements DecodedTransaction & ERC20Transaction {
+  entity: Entity
   standard: String
   operation: String
   from: TokenHolder
@@ -35,6 +27,7 @@ type ERC20TransferFrom implements DecodedTransaction & ERC20Transaction {
 }
 
 type ERC20Approve implements DecodedTransaction {
+  entity: Entity
   standard: String
   operation: String
   from: TokenHolder

src/schema/token.graphql

@@ -0,0 +1,10 @@
+type TokenHolder {
+  account: Account!
+  tokenBalance: Long
+}
+
+type TokenContract {
+  account: Account
+  symbol: String
+  totalSupply: Long
+}

src/txdec/decoders/Erc20.ts renamed to src/txdec/decoders/Erc20Token.ts

@@ -73,9 +73,10 @@ type Erc20Bindings = {
 };
 
 /**
- * ERC20 transaction decoder.
+ * ERC20 token transaction decoder.
  */
-class Erc20 implements TxDecoderDefinition<Erc20Bindings> {
+class Erc20Token implements TxDecoderDefinition<Erc20Bindings> {
+  public readonly entity = 'token';
   public readonly standard = 'ERC20';
   public readonly decoder = createAbiDecoder(__dirname + '../../../abi/erc20.json');
 
@@ -118,4 +119,4 @@ class Erc20 implements TxDecoderDefinition<Erc20Bindings> {
   };
 }
 
-export default Erc20;
+export default Erc20Token;

src/txdec/engines/SimpleTxDecodingEngine.ts

@@ -17,7 +17,7 @@ class SimpleTxDecodingEngine implements TxDecodingEngine {
    * Decodes the transaction as a known type, or returns undefined if unable to.
    * @param tx The transaction to decode.
    */
-  public decodeTransaction<T extends DecodedTx>(tx: EthqlTransaction, context: EthqlContext): T | undefined {
+  public decodeTransaction(tx: EthqlTransaction, context: EthqlContext): DecodedTx | undefined {
     const { inputData } = tx;
     if (!inputData || inputData === '0x') {
       return;
@@ -29,6 +29,7 @@ class SimpleTxDecodingEngine implements TxDecodingEngine {
         return {
           standard: txType.standard,
           operation: decoded.name,
+          entity: txType.entity,
           __typename: `${txType.standard}${_.upperFirst(decoded.name)}`,
           ...txType.transformers[decoded.name](decoded, tx, context),
         };

src/txdec/index.ts

@@ -1,12 +1,12 @@
-import Erc20 from './decoders/Erc20';
+import Erc20Token from './decoders/Erc20Token';
 import { SimpleTxDecodingEngine } from './engines/SimpleTxDecodingEngine';
 import { TxDecodingEngine } from './types';
 
 // Create the engine.
 const engine = new SimpleTxDecodingEngine();
 
 // Register all decoders.
-engine.register(new Erc20());
+engine.register(new Erc20Token());
 
 // Export the engine, making only the decodeTransaction method visible.
 export default engine as Pick<TxDecodingEngine, 'decodeTransaction'>;

src/txdec/types.ts

@@ -1,13 +1,18 @@
 import EthqlTransaction from '../model/core/EthqlTransaction';
 import { EthqlContext } from '../model/EthqlContext';
 
+// Defines the entity to which the standard belongs.
+// As we support new standards, this union type will expand.
+type Entity = 'token' | undefined;
+
 /**
  * A definition for a transaction decoder, where TBindings is a dictionary of ABI
  * function names mapped to their decoded types, and transformers is a dictionary of
  * functions that transform the raw transaction into a typed transaction, for each function
  * in the ABI.
  */
 export interface TxDecoderDefinition<TBindings> {
+  readonly entity: Entity;
   readonly standard: string;
   readonly decoder: any;
   readonly transformers: {
@@ -19,6 +24,7 @@ export interface TxDecoderDefinition<TBindings> {
  * A decoded transaction.
  */
 export type DecodedTx = {
+  entity: Entity;
   standard: string;
   operation: string;
   __typename: string;
@@ -28,5 +34,5 @@ export type DecodedTx = {
  * A decoding engine.
  */
 export type TxDecodingEngine = {
-  decodeTransaction<T extends DecodedTx>(tx: EthqlTransaction, context: EthqlContext): T;
+  decodeTransaction(tx: EthqlTransaction, context: EthqlContext): DecodedTx;
 };