Data Model and Events and Docs

[adamkrellenstein]

We need a better and more formal data model, which we should be able to represent clearly with the events API (which downstream users should be working off of). There should be a hierarchy of which events are at the top level (NEW_BLOCK), which events are sub-events of each of those (NEW_TRANSACTION, ORDER_MATCH_EXPIRED), and so forth (NEW_FAIRMINTER) till the end (CREDIT).

It should also be clear when we use asset_events. And which events are associated with each transactions, per #2796

An example use case is "I want to get a list of all recent transactions sorted by type (dividend, bet, send, fair minter, issuance, dispenser, dispense, order, etc.) that's comprehensive and with no duplicates."

The trick is to not have this too coupled to the DB stuff and the messages table.

Successor to #2746 and #2743

[adamkrellenstein]

Some standard textual representation of events:

function getEventDescription(event) {
    switch (event.event) {
        case "ENHANCED_SEND":
        case "MPMA_SEND":
        case "SEND":
            return `Send ${event.params.quantity} ${event.params.asset} to ${event.params.dest}`;
        case "SWEEP":
            return `Sweep ${event.params.source} to ${event.params.dest}`;

        
        // DEX Events
        case "OPEN_ORDER":
            return `Open order ${event.params.give_price} ${event.params.get_asset} / ${event.params.give_asset}`;
        case "ORDER_MATCH":
            return `Order match ${event.params.order_hash_1} with ${event.params.order_hash_2}`;
        case "ORDER_UPDATE":
            return `Order ${event.params.order_hash} status ${event.params.status}`;
        case "ORDER_MATCH_UPDATE":
            return `Order match update ${event.params.order_match_id}`;
        case "BTC_PAY":
            return `BTC Pay ${event.params.order_match_id}`;
        case "ORDER_FILLED":
            return `Order filled ${event.params.order_hash}`;
        case "CANCEL_ORDER":
            return `Cancel order ${event.params.offer_hash}`;
        case "ORDER_EXPIRATION":
            return `Expire order ${event.params.order_hash}`;
        case "ORDER_MATCH_EXPIRATION":
            return `Expire order match ${event.params.order_match_id}`;
        
        // Dispenser Events
        case "OPEN_DISPENSER":
            return `Open dispenser ${event.params.dispenser_price} ${event.params.asset}`;
        case "DISPENSER_UPDATE":
            return `Dispenser update ${event.params.source}`;
        case "REFILL_DISPENSER":
            return `Refill dispenser ${event.params.source}`;
        case "DISPENSE":
            return `Dispense ${event.params.dispense_quantity}`;
        
        // Broadcast Events
        case "BROADCAST":
            return `Broadcast ${event.params.text}`;
        
        // Fair Minting Events
        case "NEW_FAIRMINTER":
            return `Create ${event.params.asset} fair minter`;
        case "FAIRMINTER_UPDATE":
            return `Fair minter ${event.params.asset} status ${event.params.status}`;
        case "NEW_FAIRMINT":
            return `Fair mint ${event.params.earn_quantity} ${event.params.asset}`;
        
        // UTXO Support
        case "DETACH_FROM_UTXO":
            const outputDetachment = event.params.destination.split(":")[1];
            return `Detach ${event.params.asset} from ${outputDetachment}`;
        case "ATTACH_TO_UTXO":
            return `Attach ${event.params.asset} to ${event.params.output}`;
        case "UTXO_MOVE":
            const [txHash, index] = event.params.tx_hash.split(":");
            return `Move ${event.params.asset} from ${event.params.source} to ${event.params.dest}`;
        
        // Burns
        case "BURN":
            return `Burn ${event.params.burned} BTC`;
        
        // Blocks
        case "NEW_BLOCK":
            return `New block ${event.params.block_index} with hash ${event.params.block_hash}`;
        case "BLOCK_PARSED":
            return `Block ${event.params.block_index} parsed with ledger hash ${event.params.ledger_hash}`;

        // Transactions
        case "NEW_TRANSACTION":
            return `New transaction ${event.params.tx_hash} in block ${event.params.block_index}`;
        case "NEW_TRANSACTION_OUTPUT":
            return `New transaction output ${event.params.tx_hash} at index ${event.params.out_index}`;
        case "TRANSACTION_PARSED":
            return `Transaction ${event.params.tx_hash} parsed, supported: ${event.params.supported}`;


        // Asset Events?
        case "ASSET_TRANSFER":
            return `Transfer ${event.params.asset} to ${event.params.dest}`;
        case "ASSET_DIVIDEND":
            return `Dividend ${event.params.dividend_asset} to ${event.params.asset}`;
        case "RESET_ISSUANCE":
            return `Reset ${event.params.asset}`;
        case "ASSET_CREATION":
        case "ASSET_ISSUANCE":
            return `Issue ${event.params.asset}`;
        case "ASSET_DESTRUCTION":
            return `Destroy ${event.params.asset}`;
        
        // More Asset Events??
        default:
            switch (event.params.assetEvents) {
                case "reissuance":
                    return `Reissue ${displayAssetName(event.params.asset, event.params.assetLongname)}`;
                case "lock_quantity reissuance":
                    return `Lock Quantity for ${displayAssetName(event.params.asset, event.params.assetLongname)}`;
                case "change_description":
                    return `Change Description for ${displayAssetName(event.params.asset, event.params.assetLongname)}`;
                case "lock_description":
                    return `Lock Description for ${displayAssetName(event.params.asset, event.params.assetLongname)}`;
                case "transfer":
                    return `Transfer ${displayAssetName(event.params.asset, event.params.assetLongname)}`;
                default:
                    return "Unknown asset event";
            }
    }
}

[adamkrellenstein]

Something like this would be great. (And we don't just want to describe the status quo—we want the whole thing to make sense.)