neo-go/docs/notifications.md

# Notification subsystem

Original motivation, requirements and general solution strategy are described
in the [issue #895](https://github.com/nspcc-dev/neo-go/issues/895).

This extension allows a websocket client to subscribe to various events and
receive them as JSON-RPC notifications from the server.

## Events
Currently supported events:
 * new block added

   Contents: block. Filters: primary ID, since/till block indexes.
 * new transaction in the block

   Contents: transaction. Filters: sender and signer.
 * notification generated during execution

   Contents: container hash, contract hash, notification name, stack item.
   Filters: contract hash, notification name, notification parameters.
 * transaction/persisting script executed

   Contents: application execution result. Filters: VM state, script container hash.
 * new/removed P2P notary request (if `P2PSigExtensions` are enabled)

   Contents: P2P notary request. Filters: request sender and main tx signer.

Filters use conjunctional logic.

## Ordering and persistence guarantees
 * new block and header of this block are only announced after block's processing
   is complete and the chain is updated to the new height
 * no disk-level persistence guarantees are given
 * header of newly added block is announced after block processing, but before
   announcing the block itself
 * new in-block transaction is announced after block processing, but before
   announcing the block header and the block itself
 * transaction notifications are only announced for successful transactions
 * all announcements are being done in the same order they happen on the chain.
   First, OnPersist script execution is announced followed by notifications generated
   during the script execution. After that transaction execution is announced. It is
   then followed by notifications generated during this execution. Next, follows the
   transaction announcement. Transaction announcements are ordered the same way
   they're in the block. After all in-block transactions announcements PostPersist
   script execution is announced followed by notifications generated during the
   script execution. Finally, block header is announced followed by the block 
   announcement itself.
 * notary request events announcements are not bound to the chain processing.
   Trigger for notary request notifications is notary request mempool content
   change, thus, notary request event is announced every time notary request
   enters or leaves notary pool.
 * unsubscription may not cancel pending, but not yet sent events

## Subscription management

To receive events, clients need to subscribe to them first via `subscribe`
method. Upon successful subscription, clients receive subscription ID for
subsequent management of this subscription. Subscription is only valid for
connection lifetime, no long-term client identification is being made.

Errors are not described down below, but they can be returned as standard
JSON-RPC errors (most often caused by invalid parameters).

### `subscribe` method

Parameters: event stream name, stream-specific filter rules hash (can be
omitted if empty).

Recognized stream names:
 * `block_added`
   Filter: `primary` as an integer with a valid range of 0-255 with 
   primary (speaker) node index from ConsensusData and/or `since` field as 
   an integer value with block index starting from which new block 
   notifications will be received and/or `till` field as an integer values
   containing block index till which new block notifications will be received.
 * `header_of_added_block`
   Filter: `primary` as an integer with primary (speaker) node index from
   ConsensusData and/or `since` field as an integer value with header
   index starting from which new header notifications will be received and/or
   `till` field as an integer values containing header index till which new
   header notifications will be received.
 * `transaction_added`
   Filter: `sender` field containing a string with hex-encoded Uint160 (LE
   representation) for transaction's `Sender` and/or `signer` in the same
   format for one of transaction's `Signers`.
 * `notification_from_execution`
   Filter: `contract` field containing a string with hex-encoded Uint160 (LE
   representation), `name` field containing a string with execution 
   notification name which should be a valid UTF-8 string not longer than 
   32 bytes and/or `parameters` field containing an ordered array of structs
   with `type` and `value` fields. Not more than 16 parameters are accepted. 
   Parameter's `type` must be not-a-complex type from the list: `Any`,
   `Boolean`, `Integer`, `ByteArray`, `String`, `Hash160`, `Hash256`, `PublicKey`
   or `Signature`. Filter that allows any parameter must be omitted or must
   be `Any` typed with zero value. It is prohibited to have `parameters` be
   filled with `Any` types only.
 * `transaction_executed`
   Filter: `state` field containing `HALT` or `FAULT` string for successful
   and failed executions respectively and/or `container` field containing
   script container (block/transaction) hash.
 * `notary_request_event`
   Filter: `sender` field containing a string with hex-encoded Uint160 (LE
   representation) for notary request's `Sender` and/or `signer` in the same
   format for one of main transaction's `Signers`. `type` field containing a
   string with event type, which could be one of "added" or "removed".

Response: returns subscription ID (string) as a result. This ID can be used to
cancel this subscription and has no meaning other than that.

Example request (subscribe to notifications from contract
0x6293a440ed80a427038e175a507d3def1e04fb67 generated when executing
transactions):

```
{
  "jsonrpc": "2.0",
  "method": "subscribe",
  "params": ["notification_from_execution", {"contract": "6293a440ed80a427038e175a507d3def1e04fb67"}],
  "id": 1
}

```

Example response:

```
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "55aaff00"
}
```

### `unsubscribe` method

Parameters: subscription ID as a string.

Response: boolean true.

Example request (unsubscribe from "55aaff00"):

```
{
  "jsonrpc": "2.0",
  "method": "unsubscribe",
  "params": ["55aaff00"],
  "id": 1
}
```

Example response:

```
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": true
}
```

## Events

Events are sent as JSON-RPC notifications from the server with `method` field
being used for notification names. Notification names are identical to stream
names described for `subscribe` method with one important addition for
`event_missed`, which can be sent for any subscription to signify that some
events have not been delivered (usually when a client is unable to keep up with
the event flow).

Verbose responses for various structures like blocks and transactions are used
to simplify working with notifications on the client side. Returned structures
mostly follow the one used by standard Neo RPC calls but may have some minor
differences.

If a server-side event matches several subscriptions from one client, it's
only sent once.

### `block_added` notification

The first parameter (`params` section) contains a block converted to a JSON
structure, which is similar to a verbose `getblock` response but with the
following differences:
 * it doesn't have `size` field (you can calculate it client-side)
 * it doesn't have `nextblockhash` field (it's supposed to be the latest one
    anyway)
 * it doesn't have `confirmations` field (see previous)

No other parameters are sent.

Example:
```
{
   "params" : [
      {
         "index" : 207,
         "time" : 1590006200,
         "nextconsensus" : "AXSvJVzydxXuL9da4GVwK25zdesCrVKkHL",
         "consensusdata" : {
            "primary" : 0,
            "nonce" : "0000000000000457"
         },
         "previousblockhash" : "0x04f7580b111ec75f0ce68d3a9fd70a0544b4521b4a98541694d8575c548b759e",
         "witnesses" : [
            {
               "invocation" : "0c4063429fca5ff75c964d9e38179c75978e33f8174d91a780c2e825265cf2447281594afdd5f3e216dcaf5ff0693aec83f415996cf224454495495f6bd0a4c5d08f0c4099680903a954278580d8533121c2cd3e53a089817b6a784901ec06178a60b5f1da6e70422bdcadc89029767e08d66ce4180b99334cb2d42f42e4216394af15920c4067d5e362189e48839a24e187c59d46f5d9db862c8a029777f1548b19632bfdc73ad373827ed02369f925e89c2303b64e6b9838dca229949b9b9d3bd4c0c3ed8f0c4021d4c00d4522805883f1db929554441bcbbee127c48f6b7feeeb69a72a78c7f0a75011663e239c0820ef903f36168f42936de10f0ef20681cb735a4b53d0390f",
               "verification" : "130c2102103a7f7dd016558597f7960d27c516a4394fd968b9e65155eb4b013e4040406e0c2102a7bc55fe8684e0119768d104ba30795bdcc86619e864add26156723ed185cd620c2102b3622bf4017bdfe317c58aed5f4c753f206b7db896046fa7d774bbc4bf7f8dc20c2103d90c07df63e690ce77912e10ab51acc944b66860237b608c4f8f8309e71ee699140b413073b3bb"
            }
         ],
         "version" : 0,
         "hash" : "0x239fea00c54c2f6812612874183b72bef4473fcdf68bf8da08d74fd5b6cab030",
         "tx" : [
            {
               "txid" : "0xf736cd91ab84062a21a09b424346b241987f6245ffe8c2b2db39d595c3c222f7",
               "witnesses" : [
                  {
                     "verification" : "0c2102b3622bf4017bdfe317c58aed5f4c753f206b7db896046fa7d774bbc4bf7f8dc20b410a906ad4",
                     "invocation" : "0c4016e7a112742409cdfaad89dcdbcb52c94c5c1a69dfe5d8b999649eaaa787e31ca496d1734d6ea606c749ad36e9a88892240ae59e0efa7f544e0692124898d512"
                  }
               ],
               "vout" : [],
               "cosigners" : [],
               "validuntilblock" : 1200,
               "nonce" : 8,
               "netfee" : "0.0030421",
               "sender" : "ALHF9wsXZVEuCGgmDA6ZNsCLtrb4A1g4yG",
               "sysfee" : "0",
               "type" : "InvocationTransaction",
               "attributes" : [],
               "version" : 1,
               "vin" : [],
               "size" : 204,
               "script" : "10c00c04696e69740c14769162241eedf97c2481652adf1ba0f5bf57431b41627d5b52"
            },
            {
               "script" : "01e8030c14316e851039019d39dfc2c37d6c3fee19fd5809870c14769162241eedf97c2481652adf1ba0f5bf57431b13c00c087472616e736665720c14769162241eedf97c2481652adf1ba0f5bf57431b41627d5b5238",
               "size" : 277,
               "attributes" : [],
               "version" : 1,
               "vin" : [],
               "netfee" : "0.0037721",
               "sender" : "ALHF9wsXZVEuCGgmDA6ZNsCLtrb4A1g4yG",
               "sysfee" : "0",
               "type" : "InvocationTransaction",
               "nonce" : 9,
               "signers" : [
                  {
                     "scopes" : 1,
                     "account" : "0x870958fd19ee3f6c7dc3c2df399d013910856e31"
                  }
               ],
               "validuntilblock" : 1200,
               "witnesses" : [
                  {
                     "invocation" : "0c4027727296b84853c5d9e07fb8a40e885246ae25641383b16eefbe92027ecb1635b794aacf6bbfc3e828c73829b14791c483d19eb758b57638e3191393dbf2d288",
                     "verification" : "0c2102b3622bf4017bdfe317c58aed5f4c753f206b7db896046fa7d774bbc4bf7f8dc20b410a906ad4"
                  }
               ],
               "vout" : [],
               "txid" : "0xe1cd5e57e721d2a2e05fb1f08721b12057b25ab1dd7fd0f33ee1639932fdfad7"
            }
         ],
         "merkleroot" : "0xb2c7230ebee4cb83bc03afadbba413e6bca8fcdeaf9c077bea060918da0e52a1"
      }
   ],
   "jsonrpc" : "2.0",
   "method" : "block_added"
}
```

### `header_of_added_block` notification

The first parameter (`params` section) contains a header of added block 
converted to a JSON structure, which is similar to a verbose
`getblockheader` response but with the following differences:
 * it doesn't have `size` field (you can calculate it client-side)
 * it doesn't have `nextblockhash` field (it's supposed to be the latest
   one anyway)
 * it doesn't have `confirmations` field (see previous)

No other parameters are sent.

Example:
```
{
   "jsonrpc": "2.0",
   "method": "header_of_added_block",
   "params": [
      {
         "index" : 207,
         "time" : 1590006200,
         "nextconsensus" : "AXSvJVzydxXuL9da4GVwK25zdesCrVKkHL",
         "consensusdata" : {
            "primary" : 0,
            "nonce" : "0000000000000457"
         },
         "previousblockhash" : "0x04f7580b111ec75f0ce68d3a9fd70a0544b4521b4a98541694d8575c548b759e",
         "witnesses" : [
            {
               "invocation" : "0c4063429fca5ff75c964d9e38179c75978e33f8174d91a780c2e825265cf2447281594afdd5f3e216dcaf5ff0693aec83f415996cf224454495495f6bd0a4c5d08f0c4099680903a954278580d8533121c2cd3e53a089817b6a784901ec06178a60b5f1da6e70422bdcadc89029767e08d66ce4180b99334cb2d42f42e4216394af15920c4067d5e362189e48839a24e187c59d46f5d9db862c8a029777f1548b19632bfdc73ad373827ed02369f925e89c2303b64e6b9838dca229949b9b9d3bd4c0c3ed8f0c4021d4c00d4522805883f1db929554441bcbbee127c48f6b7feeeb69a72a78c7f0a75011663e239c0820ef903f36168f42936de10f0ef20681cb735a4b53d0390f",
               "verification" : "130c2102103a7f7dd016558597f7960d27c516a4394fd968b9e65155eb4b013e4040406e0c2102a7bc55fe8684e0119768d104ba30795bdcc86619e864add26156723ed185cd620c2102b3622bf4017bdfe317c58aed5f4c753f206b7db896046fa7d774bbc4bf7f8dc20c2103d90c07df63e690ce77912e10ab51acc944b66860237b608c4f8f8309e71ee699140b413073b3bb"
            }
         ],
         "version" : 0,
         "hash" : "0x239fea00c54c2f6812612874183b72bef4473fcdf68bf8da08d74fd5b6cab030",
         "merkleroot" : "0xb2c7230ebee4cb83bc03afadbba413e6bca8fcdeaf9c077bea060918da0e52a1"
      }
   ]
}
```

### `transaction_added` notification

The first parameter (`params` section) contains a transaction converted to
JSON, which is similar to a verbose `getrawtransaction` response, but with the
following differences:
 * block's metadata is missing (`blockhash`, `confirmations`, `blocktime`)

No other parameters are sent.

Example:
```
{
   "method" : "transaction_added",
   "params" : [
      {
         "validuntilblock" : 1200,
         "version" : 1,
         "txid" : "0xe1cd5e57e721d2a2e05fb1f08721b12057b25ab1dd7fd0f33ee1639932fdfad7",
         "witnesses" : [
            {
               "invocation" : "0c4027727296b84853c5d9e07fb8a40e885246ae25641383b16eefbe92027ecb1635b794aacf6bbfc3e828c73829b14791c483d19eb758b57638e3191393dbf2d288",
               "verification" : "0c2102b3622bf4017bdfe317c58aed5f4c753f206b7db896046fa7d774bbc4bf7f8dc20b410a906ad4"
            }
         ],
         "sysfee" : "0",
         "sender" : "ALHF9wsXZVEuCGgmDA6ZNsCLtrb4A1g4yG",
         "vout" : [],
         "netfee" : "0.0037721",
         "size" : 277,
         "attributes" : [],
         "script" : "01e8030c14316e851039019d39dfc2c37d6c3fee19fd5809870c14769162241eedf97c2481652adf1ba0f5bf57431b13c00c087472616e736665720c14769162241eedf97c2481652adf1ba0f5bf57431b41627d5b5238",
         "nonce" : 9,
         "vin" : [],
         "type" : "InvocationTransaction",
         "signers" : [
            {
               "account" : "0x870958fd19ee3f6c7dc3c2df399d013910856e31",
               "scopes" : 1
            }
         ]
      }
   ],
   "jsonrpc" : "2.0"
}
```

### `notification_from_execution` notification

Contains four parameters: container hash (block's or transaction's hex-encoded LE
Uint256 hash in a string), contract hash (hex-encoded LE Uint160 in a string),
notification name and stack item (encoded the same way as `state` field contents
for notifications from `getapplicationlog` response).

Example:

```
{
   "jsonrpc" : "2.0",
   "method" : "notification_from_execution",
   "params" : [
      {
         "state" : {
            "value" : [
               {
                  "value" : "636f6e74726163742063616c6c",
                  "type" : "ByteString"
               },
               {
                  "value" : "7472616e73666572",
                  "type" : "ByteString"
               },
               {
                  "value" : [
                     {
                        "value" : "769162241eedf97c2481652adf1ba0f5bf57431b",
                        "type" : "ByteString"
                     },
                     {
                        "value" : "316e851039019d39dfc2c37d6c3fee19fd580987",
                        "type" : "ByteString"
                     },
                     {
                        "value" : "1000",
                        "type" : "Integer"
                     }
                  ],
                  "type" : "Array"
               }
            ],
            "type" : "Array"
         },
         "contract" : "0x1b4357bff5a01bdf2a6581247cf9ed1e24629176",
         "name" : "transfer",
         "container" : "0xe1cd5e57e721d2a2e05fb1f08721b12057b25ab1dd7fd0f33ee1639932fdfad7",
      }
   ]
}
```

### `transaction_executed` notification

It contains the same result as from `getapplicationlog` method in the first
parameter and no other parameters. The difference from `getapplicationlog` is
that it has block's or transaction's hex-encoded LE Uint256 hash in the `container`
field instead of two separate `txid` and `blockhash` fields and a single execution
instead of an executions array.

Example:
```
{
   "method" : "transaction_executed",
   "params" : [
      {
         "container" : "0xe1cd5e57e721d2a2e05fb1f08721b12057b25ab1dd7fd0f33ee1639932fdfad7",
         "trigger" : "Application",
         "gasconsumed" : "2.291",
         "stack" : [],
         "notifications" : [
            {
               "state" : {
                  "type" : "Array",
                  "value" : [
                     {
                        "value" : "636f6e74726163742063616c6c",
                        "type" : "ByteString"
                     },
                     {
                        "type" : "ByteString",
                        "value" : "7472616e73666572"
                     },
                     {
                        "value" : [
                           {
                              "value" : "769162241eedf97c2481652adf1ba0f5bf57431b",
                              "type" : "ByteString"
                           },
                           {
                              "type" : "ByteString",
                              "value" : "316e851039019d39dfc2c37d6c3fee19fd580987"
                           },
                           {
                              "value" : "1000",
                              "type" : "Integer"
                           }
                        ],
                        "type" : "Array"
                     }
                  ]
               },
               "contract" : "0x1b4357bff5a01bdf2a6581247cf9ed1e24629176"
            },
            {
               "contract" : "0x1b4357bff5a01bdf2a6581247cf9ed1e24629176",
               "state" : {
                  "value" : [
                     {
                        "value" : "7472616e73666572",
                        "type" : "ByteString"
                     },
                     {
                        "value" : "769162241eedf97c2481652adf1ba0f5bf57431b",
                        "type" : "ByteString"
                     },
                     {
                        "value" : "316e851039019d39dfc2c37d6c3fee19fd580987",
                        "type" : "ByteString"
                     },
                     {
                        "value" : "1000",
                        "type" : "Integer"
                     }
                  ],
                  "type" : "Array"
               }
            }
         ],
         "vmstate" : "HALT"
      }
   ],
   "jsonrpc" : "2.0"
}
```

### `notary_request_event` notification

It contains two parameters: event type, which could be one of "added" or "removed", and
added (or removed) notary request.

Example:

```
{
   "jsonrpc" : "2.0",
   "method" : "notary_request_event",
   "params" : [
      {
         "notaryrequest" : {
            "Witness" : {
               "verification" : "DCECs2Ir9AF73+MXxYrtX0x1PyBrfbiWBG+n13S7xL9/jcJBVuezJw==",
               "invocation" : "DECWLkFhNqBMCewLxjAWiXXA1YE/GmX6EWmIRM17F9lwwpXyWtzp+hkxvJNWHpDlslDvpXizGiB/YBd05kadXlSv"
            },
            "fallbacktx" : {
               "validuntilblock" : 115,
               "attributes" : [
                  {
                     "type" : "NotValidBefore",
                     "height" : 65
                  },
                  {
                     "type" : "Conflicts",
                     "hash" : "0x03c564ed28ba3d50beb1a52dcb751b929e1d747281566bd510363470be186bc0"
                  },
                  {
                     "type" : "NotaryAssisted",
                     "nkeys" : 0
                  }
               ],
               "sender" : "NRNp25VPHahL3umVxBcMLuEENGZR9cHxtc",
               "size" : 291,
               "netfee" : "200000000",
               "witnesses" : [
                  {
                     "invocation" : "DEAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
                     "verification" : ""
                  },
                  {
                     "invocation" : "DEBnVePpwnsM54K72RmxZR8cWTGxQveJ1cAdd3/zQUh6KVDnj+G5F8AI6gYlbnEK5qJwP40WfGWlmy3A8mYHGVLm",
                     "verification" : "DCECs2Ir9AF73+MXxYrtX0x1PyBrfbiWBG+n13S7xL9/jcJBVuezJw=="
                  }
               ],
               "nonce" : 0,
               "sysfee" : "0",
               "signers" : [
                  {
                     "scopes" : "None",
                     "account" : "0xc1e14f19c3e60d0b9244d06dd7ba9b113135ec3b"
                  },
                  {
                     "account" : "0xb248508f4ef7088e10c48f14d04be3272ca29eee",
                     "scopes" : "None"
                  }
               ],
               "version" : 0,
               "hash" : "0x5eb5f89d04648d43ba7563130e8bfd1710392ab97cba8e35857aed4206db3643",
               "script" : "QA=="
            },
            "maintx" : {
               "sender" : "Nhfg3TbpwogLvDGVvAvqyThbsHgoSUKwtn",
               "attributes" : [
                  {
                     "nkeys" : 1,
                     "type" : "NotaryAssisted"
                  }
               ],
               "validuntilblock" : 115,
               "witnesses" : [
                  {
                     "invocation" : "AQQH",
                     "verification" : "AwYJ"
                  }
               ],
               "netfee" : "0",
               "size" : 62,
               "version" : 0,
               "signers" : [
                  {
                     "scopes" : "None",
                     "account" : "0xb248508f4ef7088e10c48f14d04be3272ca29eee"
                  }
               ],
               "sysfee" : "0",
               "nonce" : 1,
               "script" : "QA==",
               "hash" : "0x03c564ed28ba3d50beb1a52dcb751b929e1d747281566bd510363470be186bc0"
            }
         },
         "type" : "added"
      }
   ]
}
```

### `event_missed` notification

Never has any parameters. Example:

```
{
  "jsonrpc": "2.0",
  "method": "event_missed",
  "params": []
}
```