Merge pull request #1683 from 0xProject/feature/pipeline-entities-documentation

Add documentation for some pipeline entities

packages/pipeline/src/entities/block.ts

@@ -2,12 +2,17 @@ import { Column, Entity, PrimaryColumn } from 'typeorm';
 
 import { numberToBigIntTransformer } from '../utils';
 
+// Blocks are pulled directly from an Ethereum node (or from something like
+// Infura).
 @Entity({ name: 'blocks', schema: 'raw' })
 export class Block {
+    // Block hash
     @PrimaryColumn() public hash!: string;
+    // Block number
     @PrimaryColumn({ transformer: numberToBigIntTransformer })
     public number!: number;
 
+    // Timestamp when the block was mined (in ms since Unix Epoch)
     @Column({ name: 'timestamp', transformer: numberToBigIntTransformer })
     public timestamp!: number;
 }

packages/pipeline/src/entities/dex_trade.ts

@@ -3,54 +3,81 @@ import { Column, Entity, PrimaryColumn } from 'typeorm';
 
 import { bigNumberTransformer, numberToBigIntTransformer } from '../utils';
 
+// dex_trades contains on-chain trades that have occurred on a decentralized
+// exchange (including 0x and some competitors).
 @Entity({ name: 'dex_trades', schema: 'raw' })
 export class DexTrade {
+    // Typically an API URL where this trade was obtained.
     @PrimaryColumn({ name: 'source_url' })
     public sourceUrl!: string;
+    // The hash of the transaction this trade was a part of.
     @PrimaryColumn({ name: 'tx_hash' })
     public txHash!: string;
+    // Trade index is a unique identifier for the trade. Not necessarily
+    // supported by all sources.
     @PrimaryColumn({ name: 'trade_index' })
     public tradeIndex!: string;
 
+    // The timestamp at which this transaction occurred (in ms since Unix Epoch).
     @Column({ name: 'tx_timestamp', type: 'bigint', transformer: numberToBigIntTransformer })
     public txTimestamp!: number;
+    // Deprecated. Recently removed from the Bloxy API.
     @Column({ name: 'tx_date' })
     public txDate!: string;
+    // The sender of the on-chain transaction.
     @Column({ name: 'tx_sender' })
     public txSender!: string;
+    // Deprecated? No longer seems to be part of the Bloxy API.
     @Column({ name: 'smart_contract_id', type: 'bigint', transformer: numberToBigIntTransformer })
     public smartContractId!: number;
+    // The address of the smart contract where the trade was executed.
     @Column({ name: 'smart_contract_address' })
     public smartContractAddress!: string;
+    // Deprecated? No longer seems to be part of the Bloxy API.
     @Column({ name: 'contract_type' })
     public contractType!: string;
+    // The address of the maker.
     @Column({ type: 'varchar' })
     public maker!: string;
+    // The address of the taker.
     @Column({ type: 'varchar' })
     public taker!: string;
+    // The amount of asset being bought.
     @Column({ name: 'amount_buy', type: 'numeric', transformer: bigNumberTransformer })
     public amountBuy!: BigNumber;
+    // The fee paid by the maker.
     @Column({ name: 'maker_fee_amount', type: 'numeric', transformer: bigNumberTransformer })
     public makerFeeAmount!: BigNumber;
+    // Deprecated? No longer seems to be part of the Bloxy API.
     @Column({ name: 'buy_currency_id', type: 'bigint', transformer: numberToBigIntTransformer })
     public buyCurrencyId!: number;
+    // The symbol of the asset being bought.
     @Column({ name: 'buy_symbol' })
     public buySymbol!: string;
+    // The amount being sold.
     @Column({ name: 'amount_sell', type: 'numeric', transformer: bigNumberTransformer })
     public amountSell!: BigNumber;
+    // The fee paid by the taker.
     @Column({ name: 'taker_fee_amount', type: 'numeric', transformer: bigNumberTransformer })
     public takerFeeAmount!: BigNumber;
+    // Deprecated? No longer seems to be part of the Bloxy API.
     @Column({ name: 'sell_currency_id', type: 'bigint', transformer: numberToBigIntTransformer })
     public sellCurrencyId!: number;
+    // The symbol of the asset being sold.
     @Column({ name: 'sell_symbol' })
     public sellSymbol!: string;
+    // Annotation for the maker address.
     @Column({ name: 'maker_annotation' })
     public makerAnnotation!: string;
+    // Annotation for the taker address.
     @Column({ name: 'taker_annotation' })
     public takerAnnotation!: string;
+    // String representation of the DEX protocol (e.g. "IDEX")
     @Column() public protocol!: string;
+    // The address of the token being bought.
     @Column({ name: 'buy_address', type: 'varchar', nullable: true })
     public buyAddress!: string | null;
+    // The address of the token being sold.
     @Column({ name: 'sell_address', type: 'varchar', nullable: true })
     public sellAddress!: string | null;
 }

packages/pipeline/src/entities/erc20_approval_event.ts

@@ -3,24 +3,37 @@ import { Column, Entity, PrimaryColumn } from 'typeorm';
 
 import { bigNumberTransformer, numberToBigIntTransformer } from '../utils';
 
+// These events come directly from an ERC20 token contract and are fired
+// whenever someone updates or sets an approval.
+// See: https://github.com/0xProject/0x-protocol-specification/blob/master/v2/v2-specification.md#erc20proxy
 @Entity({ name: 'erc20_approval_events', schema: 'raw' })
 export class ERC20ApprovalEvent {
+    // The address of the token for which allowance has been set.
     @PrimaryColumn({ name: 'token_address' })
     public tokenAddress!: string;
+    // The index of the event log.
     @PrimaryColumn({ name: 'log_index' })
     public logIndex!: number;
+    // The block number where the event occurred.
     @PrimaryColumn({ name: 'block_number', transformer: numberToBigIntTransformer })
     public blockNumber!: number;
+    // The hash of the transaction where this event occurred.
+    @PrimaryColumn({ name: 'transaction_hash' })
+    public transactionHash!: string;
 
+    // The raw data which comes directly from the event.
     @Column({ name: 'raw_data' })
     public rawData!: string;
 
-    @PrimaryColumn({ name: 'transaction_hash' })
-    public transactionHash!: string;
+    // Note: the following fields are parsed from the raw_data.
+
+    // The address of the owner (i.e., the person setting the allowance).
     @Column({ name: 'owner_address' })
     public ownerAddress!: string;
+    // The address of the spender (i.e., our asset proxy).
     @Column({ name: 'spender_address' })
     public spenderAddress!: string;
+    // The amount of the allowance.
     @Column({ name: 'amount', type: 'numeric', transformer: bigNumberTransformer })
     public amount!: BigNumber;
 }

packages/pipeline/src/entities/exchange_cancel_event.ts

@@ -3,49 +3,74 @@ import { Column, Entity, PrimaryColumn } from 'typeorm';
 import { AssetType } from '../types';
 import { numberToBigIntTransformer } from '../utils';
 
+// These events come directly from the Exchange contract and are fired whenever
+// someone cancels an order.
+// See https://github.com/0xProject/0x-protocol-specification/blob/master/v2/v2-specification.md#cancelorder
 @Entity({ name: 'exchange_cancel_events', schema: 'raw' })
 export class ExchangeCancelEvent {
+    // The address of the smart contract where this event was fired.
     @PrimaryColumn({ name: 'contract_address' })
     public contractAddress!: string;
+    // The index of the event log.
     @PrimaryColumn({ name: 'log_index' })
     public logIndex!: number;
+    // The block number where the event occurred.
     @PrimaryColumn({ name: 'block_number', transformer: numberToBigIntTransformer })
     public blockNumber!: number;
+    // The hash of the transaction where this event occurred.
+    @PrimaryColumn({ name: 'transaction_hash' })
+    public transactionHash!: string;
 
+    // The raw data which comes directly from the event.
     @Column({ name: 'raw_data' })
     public rawData!: string;
 
-    @PrimaryColumn({ name: 'transaction_hash' })
-    public transactionHash!: string;
+    // Note: the following fields are parsed from the raw_data.
+
+    // The address of the maker.
     @Column({ name: 'maker_address' })
     public makerAddress!: string;
+    // The address of the taker (may be null).
     @Column({ nullable: true, type: String, name: 'taker_address' })
     public takerAddress!: string;
+    // The address of the fee recepient. Can be used to identify the relayer.
     @Column({ name: 'fee_recipient_address' })
     public feeRecipientAddress!: string;
+    // The address of the sender (used for extension contracts).
     @Column({ name: 'sender_address' })
     public senderAddress!: string;
+    // The hash of the order that was cancelled.
     @Column({ name: 'order_hash' })
     public orderHash!: string;
 
+    // The raw maker asset data.
     @Column({ name: 'raw_maker_asset_data' })
     public rawMakerAssetData!: string;
+    // The maker asset type (e.g. 'erc20' or 'erc721').
     @Column({ name: 'maker_asset_type' })
     public makerAssetType!: AssetType;
+    // The id of the AssetProxy used for the maker asset.
     @Column({ name: 'maker_asset_proxy_id' })
     public makerAssetProxyId!: string;
+    // The address of the maker token.
     @Column({ name: 'maker_token_address' })
     public makerTokenAddress!: string;
+    // The id of the maker token (always null for ERC20 tokens).
     @Column({ nullable: true, type: String, name: 'maker_token_id' })
     public makerTokenId!: string | null;
+    // The raw taker asset data.
     @Column({ name: 'raw_taker_asset_data' })
     public rawTakerAssetData!: string;
+    // The taker asset type (e.g. 'erc20' or 'erc721').
     @Column({ name: 'taker_asset_type' })
     public takerAssetType!: AssetType;
+    // The id of the AssetProxy used for the taker asset.
     @Column({ name: 'taker_asset_proxy_id' })
     public takerAssetProxyId!: string;
+    // The address of the taker token.
     @Column({ name: 'taker_token_address' })
     public takerTokenAddress!: string;
+    // The id of the taker token (always null for ERC20 tokens).
     @Column({ nullable: true, type: String, name: 'taker_token_id' })
     public takerTokenId!: string | null;
 }

packages/pipeline/src/entities/exchange_cancel_up_to_event.ts

@@ -3,24 +3,37 @@ import { Column, Entity, PrimaryColumn } from 'typeorm';
 
 import { bigNumberTransformer, numberToBigIntTransformer } from '../utils';
 
+// These events come directly from the Exchange contract and are fired whenever
+// someone cancels orders using the cancelOrdersUpTo function.
+// See https://github.com/0xProject/0x-protocol-specification/blob/master/v2/v2-specification.md#cancelordersupto
 @Entity({ name: 'exchange_cancel_up_to_events', schema: 'raw' })
 export class ExchangeCancelUpToEvent {
+    // The address of the smart contract where this event was fired.
     @PrimaryColumn({ name: 'contract_address' })
     public contractAddress!: string;
+    // The index of the event log.
     @PrimaryColumn({ name: 'log_index' })
     public logIndex!: number;
+    // The block number where the event occurred.
     @PrimaryColumn({ name: 'block_number', transformer: numberToBigIntTransformer })
     public blockNumber!: number;
+    // The hash of the transaction where this event occurred.
+    @PrimaryColumn({ name: 'transaction_hash' })
+    public transactionHash!: string;
 
+    // The raw data which comes directly from the event.
     @Column({ name: 'raw_data' })
     public rawData!: string;
 
-    @PrimaryColumn({ name: 'transaction_hash' })
-    public transactionHash!: string;
+    // Note: the following fields are parsed from the raw_data.
+
+    // The address of the maker.
     @Column({ name: 'maker_address' })
     public makerAddress!: string;
+    // The address of the sender (used for extension contracts).
     @Column({ name: 'sender_address' })
     public senderAddress!: string;
+    // Orders with a salt less than or equal to this value will be cancelled.
     @Column({ name: 'order_epoch', type: 'numeric', transformer: bigNumberTransformer })
     public orderEpoch!: BigNumber;
 }

packages/pipeline/src/entities/exchange_fill_event.ts

@@ -4,57 +4,86 @@ import { Column, Entity, PrimaryColumn } from 'typeorm';
 import { AssetType } from '../types';
 import { bigNumberTransformer, numberToBigIntTransformer } from '../utils';
 
+// These events come directly from the Exchange contract and are fired whenever
+// someone fills an order.
+// See https://github.com/0xProject/0x-protocol-specification/blob/master/v2/v2-specification.md#filling-orders
 @Entity({ name: 'exchange_fill_events', schema: 'raw' })
 export class ExchangeFillEvent {
+    // The address of the smart contract where this event was fired.
     @PrimaryColumn({ name: 'contract_address' })
     public contractAddress!: string;
+    // The index of the event log.
     @PrimaryColumn({ name: 'log_index' })
     public logIndex!: number;
+    // The block number where the event occurred.
     @PrimaryColumn({ name: 'block_number', transformer: numberToBigIntTransformer })
     public blockNumber!: number;
+    // The hash of the transaction where this event occurred.
+    @PrimaryColumn({ name: 'transaction_hash' })
+    public transactionHash!: string;
 
+    // The raw data which comes directly from the event.
     @Column({ name: 'raw_data' })
     public rawData!: string;
 
-    @PrimaryColumn({ name: 'transaction_hash' })
-    public transactionHash!: string;
+    // Note: the following fields are parsed from the raw_data.
+
+    // The address of the maker.
     @Column({ name: 'maker_address' })
     public makerAddress!: string;
+    // The address of the taker (may be null).
     @Column({ name: 'taker_address' })
     public takerAddress!: string;
+    // The address of the fee recepient. Can be used to identify the relayer.
     @Column({ name: 'fee_recipient_address' })
     public feeRecipientAddress!: string;
+    // The address of the sender (used for extension contracts).
     @Column({ name: 'sender_address' })
     public senderAddress!: string;
+    // The amount of the maker asset which was filled.
     @Column({ name: 'maker_asset_filled_amount', type: 'numeric', transformer: bigNumberTransformer })
     public makerAssetFilledAmount!: BigNumber;
+    // The amount of the taker asset which was filled.
     @Column({ name: 'taker_asset_filled_amount', type: 'numeric', transformer: bigNumberTransformer })
     public takerAssetFilledAmount!: BigNumber;
+    // The fee paid by the maker.
     @Column({ name: 'maker_fee_paid', type: 'numeric', transformer: bigNumberTransformer })
     public makerFeePaid!: BigNumber;
+    // The fee paid by the taker.
     @Column({ name: 'taker_fee_paid', type: 'numeric', transformer: bigNumberTransformer })
     public takerFeePaid!: BigNumber;
+    // The hash of the order which was filled.
     @Column({ name: 'order_hash' })
     public orderHash!: string;
 
+    // The raw maker asset data.
     @Column({ name: 'raw_maker_asset_data' })
     public rawMakerAssetData!: string;
+    // The maker asset type (e.g. 'erc20' or 'erc721').
     @Column({ name: 'maker_asset_type' })
     public makerAssetType!: AssetType;
+    // The id of the AssetProxy used for the maker asset.
     @Column({ name: 'maker_asset_proxy_id' })
     public makerAssetProxyId!: string;
+    // The address of the maker token.
     @Column({ name: 'maker_token_address' })
     public makerTokenAddress!: string;
+    // The id of the maker token (always null for ERC20 tokens).
     @Column({ nullable: true, type: String, name: 'maker_token_id' })
     public makerTokenId!: string | null;
+    // The raw taker asset data.
     @Column({ name: 'raw_taker_asset_data' })
     public rawTakerAssetData!: string;
+    // The taker asset type (e.g. 'erc20' or 'erc721').
     @Column({ name: 'taker_asset_type' })
     public takerAssetType!: AssetType;
+    // The id of the AssetProxy used for the taker asset.
     @Column({ name: 'taker_asset_proxy_id' })
     public takerAssetProxyId!: string;
+    // The address of the taker token.
     @Column({ name: 'taker_token_address' })
     public takerTokenAddress!: string;
+    // The id of the taker token (always null for ERC20 tokens).
     @Column({ nullable: true, type: String, name: 'taker_token_id' })
     public takerTokenId!: string | null;
 }

packages/pipeline/src/entities/nonfungible_dot_com_trade.ts

@@ -3,33 +3,47 @@ import { Column, Entity, PrimaryColumn } from 'typeorm';
 
 import { bigNumberTransformer, numberToBigIntTransformer } from '../utils';
 
+// Contains trades that come from the Nonfungible.com API.
 @Entity({ name: 'nonfungible_dot_com_trades', schema: 'raw' })
 export class NonfungibleDotComTrade {
+    // The hash of the transaction where the trade occurred.
     @PrimaryColumn({ name: 'transaction_hash' })
     public transactionHash!: string;
+    // The publisher for the trade (e.g. "cryptopunks", "etherbots")
     @PrimaryColumn({ name: 'publisher' })
     public publisher!: string;
+    // The block number where the trade occurred.
     @PrimaryColumn({ name: 'block_number', type: 'bigint', transformer: numberToBigIntTransformer })
     public blockNumber!: number;
+    // The index of the event log.
     @PrimaryColumn({ name: 'log_index' })
     public logIndex!: number;
+    // A unique identifier for the asset.
     @PrimaryColumn({ name: 'asset_id' })
     public assetId!: string;
 
+    // The timestmap of the block where the trade occurred. (In ms since Unix Epoch)
     @Column({ name: 'block_timestamp', type: 'bigint', transformer: numberToBigIntTransformer })
     public blockTimestamp!: number;
+    // An arbitrary string describing the asset (may be empty).
     @Column({ name: 'asset_descriptor' })
     public assetDescriptor!: string;
+    // The address of the market/smart contract where the trade occurred.
     @Column({ name: 'market_address' })
     public marketAddress!: string;
+    // The total price in base units for the asset.
     @Column({ name: 'total_price', type: 'numeric', transformer: bigNumberTransformer })
     public totalPrice!: BigNumber;
+    // The estimated USD price for the asset.
     @Column({ name: 'usd_price', type: 'numeric', transformer: bigNumberTransformer })
     public usdPrice!: BigNumber;
+    // The address of the buyer.
     @Column({ name: 'buyer_address' })
     public buyerAddress!: string;
+    // The address of the seller.
     @Column({ name: 'seller_address' })
     public sellerAddress!: string;
+    // Arbitrary, market-specific data corresponding to the trade.
     @Column({ type: 'jsonb' })
     public meta!: object;
 }

packages/pipeline/src/entities/relayer.ts

@@ -1,21 +1,30 @@
 import { Column, Entity, PrimaryColumn } from 'typeorm';
 
+// Contains relayers along with some metadata about them.
 @Entity({ name: 'relayers', schema: 'raw' })
 export class Relayer {
+    // A unique identifier for the relayer. Never changes.
     @PrimaryColumn() public uuid!: string;
 
+    // A human-readable name for the relayer.
     @Column() public name!: string;
+    // The URL for the relayer's home page.
     @Column({ name: 'homepage_url', type: 'varchar' })
     public homepageUrl!: string;
+    // HTTP SRA endpoint for the relayer (null for relayers that don't support it).
     @Column({ name: 'sra_http_endpoint', type: 'varchar', nullable: true })
     public sraHttpEndpoint!: string | null;
+    // WebSocket SRA endpoint for the relayer (null for relayers that don't support it).
     @Column({ name: 'sra_ws_endpoint', type: 'varchar', nullable: true })
     public sraWsEndpoint!: string | null;
+    // Application URL (null for relayers without a separate app url).
     @Column({ name: 'app_url', type: 'varchar', nullable: true })
     public appUrl!: string | null;
 
+    // An array of known fee recipient addresses used by this relayer.
     @Column({ name: 'fee_recipient_addresses', type: 'varchar', array: true })
     public feeRecipientAddresses!: string[];
+    // An array of known taker addresses used by this relayer.
     @Column({ name: 'taker_addresses', type: 'varchar', array: true })
     public takerAddresses!: string[];
 }

packages/pipeline/src/entities/sra_order.ts

@@ -4,60 +4,87 @@ import { Column, Entity, PrimaryColumn } from 'typeorm';
 import { AssetType } from '../types';
 import { bigNumberTransformer } from '../utils';
 
+// Contains orders obtained from an SRA endpoint.
 @Entity({ name: 'sra_orders', schema: 'raw' })
 export class SraOrder {
+    // The address of the exchange contract for this order (e.g. might be the
+    // address of the V1 exchange or the V2 one).
     @PrimaryColumn({ name: 'exchange_address' })
     public exchangeAddress!: string;
+    // The hash of the order.
     @PrimaryColumn({ name: 'order_hash_hex' })
     public orderHashHex!: string;
+    // The URL of an SRA endpoint where this order was found.
     @PrimaryColumn({ name: 'source_url' })
     public sourceUrl!: string;
 
+    // The adddress of the maker.
     @Column({ name: 'maker_address' })
     public makerAddress!: string;
+    // The address of the taker (may be null).
     @Column({ name: 'taker_address' })
     public takerAddress!: string;
+    // The address of the fee recepient. Can be used to identify the relayer.
     @Column({ name: 'fee_recipient_address' })
     public feeRecipientAddress!: string;
+    // The address of the sender (used for extension contracts).
     @Column({ name: 'sender_address' })
     public senderAddress!: string;
+    // The amount of maker_maker asset provided by the maker.
     @Column({ name: 'maker_asset_amount', type: 'numeric', transformer: bigNumberTransformer })
     public makerAssetAmount!: BigNumber;
+    // The amount of taker_asset provided by the taker.
     @Column({ name: 'taker_asset_amount', type: 'numeric', transformer: bigNumberTransformer })
     public takerAssetAmount!: BigNumber;
+    // The fee paid by the maker.
     @Column({ name: 'maker_fee', type: 'numeric', transformer: bigNumberTransformer })
     public makerFee!: BigNumber;
+    // The fee paid by the taker.
     @Column({ name: 'taker_fee', type: 'numeric', transformer: bigNumberTransformer })
     public takerFee!: BigNumber;
+    // Timestamp in seconds when the order should be considered expired.
     @Column({ name: 'expiration_time_seconds', type: 'numeric', transformer: bigNumberTransformer })
     public expirationTimeSeconds!: BigNumber;
+    // A monotonically increasing unique number (typically a timestamp).
     @Column({ name: 'salt', type: 'numeric', transformer: bigNumberTransformer })
     public salt!: BigNumber;
+    // The signature for this order (used for verification).
     @Column({ name: 'signature' })
     public signature!: string;
 
+    // The raw maker asset data.
     @Column({ name: 'raw_maker_asset_data' })
     public rawMakerAssetData!: string;
+    // The maker asset type (e.g. 'erc20' or 'erc721').
     @Column({ name: 'maker_asset_type' })
     public makerAssetType!: AssetType;
+    // The id of the AssetProxy used for the maker asset.
     @Column({ name: 'maker_asset_proxy_id' })
     public makerAssetProxyId!: string;
+    // The address of the maker token.
     @Column({ name: 'maker_token_address' })
     public makerTokenAddress!: string;
+    // The id of the maker token (always null for ERC20 tokens).;
     @Column({ nullable: true, type: String, name: 'maker_token_id' })
     public makerTokenId!: string | null;
+    // The raw taker asset data.
     @Column({ name: 'raw_taker_asset_data' })
     public rawTakerAssetData!: string;
+    // The taker asset type (e.g. 'erc20' or 'erc721').
     @Column({ name: 'taker_asset_type' })
     public takerAssetType!: AssetType;
+    // The id of the AssetProxy used for the taker asset.
     @Column({ name: 'taker_asset_proxy_id' })
     public takerAssetProxyId!: string;
+    // The address of the taker token.
     @Column({ name: 'taker_token_address' })
     public takerTokenAddress!: string;
+    // The id of the taker token (always null for ERC20 tokens).
     @Column({ nullable: true, type: String, name: 'taker_token_id' })
     public takerTokenId!: string | null;
 
     // TODO(albrow): Make this optional?
+    // Arbitrary metadata associated with the order.
     @Column({ name: 'metadata_json' })
     public metadataJson!: string;
 }

packages/pipeline/src/entities/sra_order_observed_timestamp.ts

@@ -4,15 +4,24 @@ import { numberToBigIntTransformer } from '../utils';
 
 import { SraOrder } from './sra_order';
 
+// Contains observed timestamps for SRA orders in the sra_orders table. This can
+// be used to determine when an order first appeard on the order book and how
+// long it was there.
 @Entity({ name: 'sra_orders_observed_timestamps', schema: 'raw' })
 export class SraOrdersObservedTimeStamp {
+    // The address of the exchange contract for this order (e.g. might be the
+    // address of the V1 exchange or the V2 one).
     @PrimaryColumn({ name: 'exchange_address' })
     public exchangeAddress!: string;
+    // The hash of the order.
     @PrimaryColumn({ name: 'order_hash_hex' })
     public orderHashHex!: string;
+    // The URL of an SRA endpoint where this order was found.
     @PrimaryColumn({ name: 'source_url' })
     public sourceUrl!: string;
 
+    // The time that the order was observed in the order book. Each order may
+    // have been observed multiple times.
     @PrimaryColumn({ name: 'observed_timestamp', transformer: numberToBigIntTransformer })
     public observedTimestamp!: number;
 }

packages/pipeline/src/entities/token_metadata.ts

@@ -3,20 +3,28 @@ import { Column, Entity, PrimaryColumn } from 'typeorm';
 
 import { bigNumberTransformer } from '../utils/transformers';
 
+// Contains metadata about ERC20 tokens.
+// See: https://theethereum.wiki/w/index.php/ERC20_Token_Standard
 @Entity({ name: 'token_metadata', schema: 'raw' })
 export class TokenMetadata {
+    // The address of the token contract.
     @PrimaryColumn({ type: 'varchar', nullable: false })
     public address!: string;
 
+    // The "authority" or where this metadata was obtained. Either "0x" for the
+    // 0x token registry or "metamask" for the MetaMask "Contract Map" list.
     @PrimaryColumn({ type: 'varchar', nullable: false })
     public authority!: string;
 
+    // The number of decimals which determines the "base unit" for the token.
     @Column({ type: 'numeric', transformer: bigNumberTransformer, nullable: true })
     public decimals!: BigNumber | null;
 
+    // A human-readable symbol for the token (e.g. "ZRX")
     @Column({ type: 'varchar', nullable: true })
     public symbol!: string | null;
 
+    // A hunam-readable name for the token (e.g. "0x Protocol")
     @Column({ type: 'varchar', nullable: true })
     public name!: string | null;
 }

packages/pipeline/src/entities/token_order.ts

@@ -3,28 +3,49 @@ import { Column, Entity, PrimaryColumn } from 'typeorm';
 
 import { bigNumberTransformer, numberToBigIntTransformer } from '../utils';
 
+// Contains orders from an order book snapshot. A "snapshot" is a view of some
+// order book at a specific point in time. For most sources, the snapshots use
+// "Level 2 Aggregation", which means that orders at the same price are grouped
+// together. However, RadarRelay orders use something in between "Level 2
+// Aggregation" and "Level 3 Aggregation" where orders are grouped by price and
+// maker address. See
+// https://datafireball.com/2017/11/29/gdax-orderbook-data-api-level123/ for
+// more information about aggregation levels.
 @Entity({ name: 'token_orderbook_snapshots', schema: 'raw' })
 export class TokenOrderbookSnapshot {
+    // The timestamp (in ms since Unix Epoch) at which the snapshot that
+    // contains this order was taken.
     @PrimaryColumn({ name: 'observed_timestamp', type: 'bigint', transformer: numberToBigIntTransformer })
     public observedTimestamp!: number;
+    // The source where the orders came from (e.g. "idex", "paradex").
     @PrimaryColumn({ name: 'source' })
     public source!: string;
+    // The type of the aggregated orders (either "bid" or "ask").
     @PrimaryColumn({ name: 'order_type' })
     public orderType!: string;
+    // The price of the aggregated orders.
     @PrimaryColumn({ name: 'price', type: 'numeric', transformer: bigNumberTransformer })
     public price!: BigNumber;
+    // The base asset for the agregated orders.
     @PrimaryColumn({ name: 'base_asset_symbol' })
     public baseAssetSymbol!: string;
+    // The quote asset for the agregated orders.
     @PrimaryColumn({ name: 'quote_asset_symbol' })
     public quoteAssetSymbol!: string;
+    // The maker address for the aggregated orders. "unknown" for all sources
+    // except RadarRelay.
     @PrimaryColumn({ type: String, name: 'maker_address', default: 'unknown' })
     public makerAddress!: string;
+    // The address of the base asset for the aggregated orders.
     @Column({ nullable: true, type: String, name: 'base_asset_address' })
     public baseAssetAddress!: string | null;
+    // The total base volume across all aggregated orders.
     @Column({ name: 'base_volume', type: 'numeric', transformer: bigNumberTransformer })
     public baseVolume!: BigNumber;
+    // The address of the quote asset for the aggregated orders.
     @Column({ nullable: true, type: String, name: 'quote_asset_address' })
     public quoteAssetAddress!: string | null;
+    // The total quote volume across all aggregated orders.
     @Column({ name: 'quote_volume', type: 'numeric', transformer: bigNumberTransformer })
     public quoteVolume!: BigNumber;
 }

packages/pipeline/src/entities/transaction.ts

@@ -3,17 +3,24 @@ import { Column, Entity, PrimaryColumn } from 'typeorm';
 
 import { bigNumberTransformer, numberToBigIntTransformer } from '../utils';
 
+// Transactions are pulled directly from an Ethereum node (or from something
+// like Infura).
 @Entity({ name: 'transactions', schema: 'raw' })
 export class Transaction {
+    // The hash of the transaction.
     @PrimaryColumn({ name: 'transaction_hash' })
     public transactionHash!: string;
+    // The hash of the block this transsaction is a part of.
     @PrimaryColumn({ name: 'block_hash' })
     public blockHash!: string;
+    // The number of the block this transaction is a part of.
     @PrimaryColumn({ name: 'block_number', transformer: numberToBigIntTransformer })
     public blockNumber!: number;
 
+    // The amount of gas used for the transaction.
     @Column({ type: 'numeric', name: 'gas_used', transformer: bigNumberTransformer })
     public gasUsed!: BigNumber;
+    // The gas price paid for the transaction.
     @Column({ type: 'numeric', name: 'gas_price', transformer: bigNumberTransformer })
     public gasPrice!: BigNumber;
 }