From e55c8fe11554b4e1d0bb44f8826e11740daff4dd Mon Sep 17 00:00:00 2001
From: perama-v <83961755+perama-v@users.noreply.github.com>
Date: Fri, 28 Jul 2023 19:10:32 +1000
Subject: [PATCH 01/12] doc: add README for address API

---
 src/address/README.md | 49 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 49 insertions(+)
 create mode 100644 src/address/README.md

diff --git a/src/address/README.md b/src/address/README.md
new file mode 100644
index 000000000..519db87a6
--- /dev/null
+++ b/src/address/README.md
@@ -0,0 +1,49 @@
+# Address JSON-RPC API
+
+The Address JSON-RPC API is a collection of methods that Ethereum archival execution clients MAY implement.
+
+This interface allows the use of an archive node from the perspective of an end user.
+It provides information about which transactions are important for a given address. The address
+may be an externally owned account, a smart wallet, an account abstraction wallet or an application contract.
+
+The API is desinged around an index mapping addresses to transaction ids. This index is created
+in advance so that queries are responded to quickly and do not require EVM re-execution.
+
+The API allows introspection into otherwise opaque history. An example is an EOA that received
+ether via a CALL opcode. The API can return this transaction id, which can then be used with
+other methods (debug_traceTransaction) to identify the transfer.
+
+# Address API -- Common Definitions
+
+This document specifies common definitions and requirements affecting Address API specification in general.
+
+## Table of contents
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+
+- [Address JSON-RPC API](#address-json-rpc-api)
+- [Address API -- Common Definitions](#address-api----common-definitions)
+  - [Table of contents](#table-of-contents)
+  - [Errors](#errors)
+
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+## Errors
+
+The list of error codes introduced by this specification can be found below.
+
+| Code | Message | Meaning |
+| - | - | - |
+| -32700 | Parse error | Invalid JSON was received by the server. |
+| -32600 | Invalid Request | The JSON sent is not a valid Request object. |
+| -32601 | Method not found | The method does not exist / is not available. |
+| -32602 | Invalid params | Invalid method parameter(s). |
+| -32603 | Internal error | Internal JSON-RPC error. |
+| -32000 | Server error | Generic client error while processing request. |
+| -38004 | Too large request | Number of requested entities is too large. |
+
+
+Each error returns a `null` `data` value, except `-32000` which returns the `data` object with a `err` member that explains the error encountered.
+

From 767d8ebe13ae8f830d4d5cc7239b3e951418f9dd Mon Sep 17 00:00:00 2001
From: perama-v <83961755+perama-v@users.noreply.github.com>
Date: Fri, 28 Jul 2023 19:11:25 +1000
Subject: [PATCH 02/12] feat(address): Add API method and schemas

---
 src/address/methods/appearances.yaml | 20 ++++++++++++++++++++
 src/address/schemas/appearances.yaml | 22 ++++++++++++++++++++++
 2 files changed, 42 insertions(+)
 create mode 100644 src/address/methods/appearances.yaml
 create mode 100644 src/address/schemas/appearances.yaml

diff --git a/src/address/methods/appearances.yaml b/src/address/methods/appearances.yaml
new file mode 100644
index 000000000..eecacb243
--- /dev/null
+++ b/src/address/methods/appearances.yaml
@@ -0,0 +1,20 @@
+- name: eth_getAddressAppearances
+  summary: Returns transaction identifiers relevant to an address.
+  params:
+    - name: Address
+      required: true
+      schema:
+        $ref: '#/components/schemas/address'
+    - name: Block range
+      required: false
+      schema:
+        title: Inclusive block number range with two values [low, high]
+        type: array
+        items:
+          $ref: '#/components/schemas/uint'
+  result:
+    name: Address appearances
+    schema:
+      oneOf:
+        - $ref: '#/components/schemas/notFound'
+        - $ref: '#/components/schemas/AddressAppearances'
diff --git a/src/address/schemas/appearances.yaml b/src/address/schemas/appearances.yaml
new file mode 100644
index 000000000..546a9637e
--- /dev/null
+++ b/src/address/schemas/appearances.yaml
@@ -0,0 +1,22 @@
+AddressAppearances:
+  title: Transaction identifiers relevant to an address
+  type: array
+  additionalProperties: false
+  $ref: '#/components/schemas/RelevantTransaction'
+RelevantTransaction:
+  title: Relevant Transaction
+  type: object
+  description: Identifier of a transaction relevant to an address
+  required:
+    - blockNumber
+    - transactionIndex
+  additionalProperties: false
+  properties:
+    blockNumber:
+      title: Block number
+      description: Block containing the relevant transactions
+      $ref: '#/components/schemas/uint'
+    transactionIndex:
+      title: Transaction index
+      description: Index of a transaction that an address appears in
+      $ref: '#/components/schemas/uint'

From bae4a081fdb0618be2ead9ca4b1785f52cc64035 Mon Sep 17 00:00:00 2001
From: perama-v <83961755+perama-v@users.noreply.github.com>
Date: Fri, 28 Jul 2023 19:11:50 +1000
Subject: [PATCH 03/12] feat(address): Add test cases for address appearances

---
 tests/address_getAppearances/get-appearances-all-blocks-none.io | 2 ++
 tests/address_getAppearances/get-appearances-all-blocks-some.io | 2 ++
 .../get-appearances-block-range-single.io                       | 2 ++
 tests/address_getAppearances/get-appearances-block-range.io     | 2 ++
 .../get-appearances-error-backward-range.io                     | 2 ++
 .../address_getAppearances/get-appearances-error-half-range.io  | 2 ++
 .../get-appearances-error-short-address.io                      | 2 ++
 .../get-appearances-one-block-multiple-transactions.io          | 2 ++
 8 files changed, 16 insertions(+)
 create mode 100644 tests/address_getAppearances/get-appearances-all-blocks-none.io
 create mode 100644 tests/address_getAppearances/get-appearances-all-blocks-some.io
 create mode 100644 tests/address_getAppearances/get-appearances-block-range-single.io
 create mode 100644 tests/address_getAppearances/get-appearances-block-range.io
 create mode 100644 tests/address_getAppearances/get-appearances-error-backward-range.io
 create mode 100644 tests/address_getAppearances/get-appearances-error-half-range.io
 create mode 100644 tests/address_getAppearances/get-appearances-error-short-address.io
 create mode 100644 tests/address_getAppearances/get-appearances-one-block-multiple-transactions.io

diff --git a/tests/address_getAppearances/get-appearances-all-blocks-none.io b/tests/address_getAppearances/get-appearances-all-blocks-none.io
new file mode 100644
index 000000000..a4ad78694
--- /dev/null
+++ b/tests/address_getAppearances/get-appearances-all-blocks-none.io
@@ -0,0 +1,2 @@
+>> {"jsonrpc":"2.0","id":1,"method":"address_getAppearances","params":["0x0000639850b3ddeaaca4f06280aa751682f11382"]}
+<< {"jsonrpc":"2.0","id":1,"result":[]}
diff --git a/tests/address_getAppearances/get-appearances-all-blocks-some.io b/tests/address_getAppearances/get-appearances-all-blocks-some.io
new file mode 100644
index 000000000..37e347902
--- /dev/null
+++ b/tests/address_getAppearances/get-appearances-all-blocks-some.io
@@ -0,0 +1,2 @@
+>> {"jsonrpc":"2.0","id":1,"method":"address_getAppearances","params":["0x30a4639850b3ddeaaca4f06280aa751682f11382"]}
+<< {"id":1,"jsonrpc":"2.0","result":[{"blockNumber":14040913,"transactionIndex":230},{"blockNumber":14040922,"transactionIndex":283},{"blockNumber":14057812,"transactionIndex":6},{"blockNumber":14064971,"transactionIndex":61},{"blockNumber":14065074,"transactionIndex":75},{"blockNumber":14081630,"transactionIndex":37},{"blockNumber":14081755,"transactionIndex":115},{"blockNumber":14085374,"transactionIndex":102},{"blockNumber":14683020,"transactionIndex":107},{"blockNumber":14683030,"transactionIndex":120},{"blockNumber":14683030,"transactionIndex":121},{"blockNumber":14724641,"transactionIndex":294},{"blockNumber":14870967,"transactionIndex":129},{"blockNumber":14870973,"transactionIndex":316},{"blockNumber":15488280,"transactionIndex":175},{"blockNumber":15488361,"transactionIndex":275},{"blockNumber":15488361,"transactionIndex":284},{"blockNumber":15488363,"transactionIndex":165},{"blockNumber":15488374,"transactionIndex":293},{"blockNumber":15488379,"transactionIndex":265},{"blockNumber":15488388,"transactionIndex":114},{"blockNumber":15488530,"transactionIndex":26},{"blockNumber":15919652,"transactionIndex":34},{"blockNumber":15919705,"transactionIndex":149},{"blockNumber":17189746,"transactionIndex":84},{"blockNumber":17189754,"transactionIndex":158},{"blockNumber":17190681,"transactionIndex":103},{"blockNumber":17190690,"transactionIndex":136},{"blockNumber":17190873,"transactionIndex":95},{"blockNumber":17190889,"transactionIndex":89},{"blockNumber":17194361,"transactionIndex":125},{"blockNumber":17194403,"transactionIndex":163},{"blockNumber":17219903,"transactionIndex":116},{"blockNumber":17572135,"transactionIndex":43}]}
diff --git a/tests/address_getAppearances/get-appearances-block-range-single.io b/tests/address_getAppearances/get-appearances-block-range-single.io
new file mode 100644
index 000000000..8194297b5
--- /dev/null
+++ b/tests/address_getAppearances/get-appearances-block-range-single.io
@@ -0,0 +1,2 @@
+>> {"jsonrpc":"2.0","id":1,"method":"eth_getBlockByNumber","params":["0x30a4639850b3ddeaaca4f06280aa751682f11382",[17190873, 17190873]]}
+<< {"id":1,"jsonrpc":"2.0","result":[{"blockNumber":17190873,"transactionIndex":95}]}
diff --git a/tests/address_getAppearances/get-appearances-block-range.io b/tests/address_getAppearances/get-appearances-block-range.io
new file mode 100644
index 000000000..df9a53b73
--- /dev/null
+++ b/tests/address_getAppearances/get-appearances-block-range.io
@@ -0,0 +1,2 @@
+>> {"jsonrpc":"2.0","id":1,"method":"eth_getBlockByNumber","params":["0x30a4639850b3ddeaaca4f06280aa751682f11382",[17190873, 17190889]]}
+<< {"id":1,"jsonrpc":"2.0","result":[{"blockNumber":17190873,"transactionIndex":95},{"blockNumber":17190889,"transactionIndex":89}]}
diff --git a/tests/address_getAppearances/get-appearances-error-backward-range.io b/tests/address_getAppearances/get-appearances-error-backward-range.io
new file mode 100644
index 000000000..353992437
--- /dev/null
+++ b/tests/address_getAppearances/get-appearances-error-backward-range.io
@@ -0,0 +1,2 @@
+>> {"jsonrpc":"2.0","id":1,"method":"address_getAppearances","params":["0x30a4639850b3ddeaaca4f06280aa751682f11382",[17190874, 17190873]]}
+<< {"jsonrpc":"2.0","id":1,"result":{"code":-32602,"message":"Invalid params"}}
diff --git a/tests/address_getAppearances/get-appearances-error-half-range.io b/tests/address_getAppearances/get-appearances-error-half-range.io
new file mode 100644
index 000000000..e6e98ec1a
--- /dev/null
+++ b/tests/address_getAppearances/get-appearances-error-half-range.io
@@ -0,0 +1,2 @@
+>> {"jsonrpc":"2.0","id":1,"method":"address_getAppearances","params":["0x30a4639850b3ddeaaca4f06280aa751682f11382",[17190873]]}
+<< {"jsonrpc":"2.0","id":1,"result":{"code":-32602,"message":"Invalid params"}}
diff --git a/tests/address_getAppearances/get-appearances-error-short-address.io b/tests/address_getAppearances/get-appearances-error-short-address.io
new file mode 100644
index 000000000..a73fea112
--- /dev/null
+++ b/tests/address_getAppearances/get-appearances-error-short-address.io
@@ -0,0 +1,2 @@
+>> {"jsonrpc":"2.0","id":1,"method":"address_getAppearances","params":["0xeaaca4f06280aa751682f11382"]}
+<< {"jsonrpc":"2.0","id":1,"result":{"code":-32602,"message":"Invalid params"}}
diff --git a/tests/address_getAppearances/get-appearances-one-block-multiple-transactions.io b/tests/address_getAppearances/get-appearances-one-block-multiple-transactions.io
new file mode 100644
index 000000000..fd6accf2e
--- /dev/null
+++ b/tests/address_getAppearances/get-appearances-one-block-multiple-transactions.io
@@ -0,0 +1,2 @@
+>> {"jsonrpc":"2.0","id":1,"method":"eth_getBlockByNumber","params":["0x2d7C6B69175c2939173F2fd470538835336Df92b",[17190873, 17190873]]}
+<< {"id":1,"jsonrpc":"2.0","result":[{"blockNumber":17190873,"transactionIndex":103},{"blockNumber":17190873,"transactionIndex":163},{"blockNumber":17190873,"transactionIndex":169},{"blockNumber":17190873,"transactionIndex":179},{"blockNumber":17190873,"transactionIndex":182}]}
\ No newline at end of file

From 4c47623c6a5b4006bbf0af7cd77b3a1e80972061 Mon Sep 17 00:00:00 2001
From: perama-v <83961755+perama-v@users.noreply.github.com>
Date: Sat, 29 Jul 2023 18:00:43 +1000
Subject: [PATCH 04/12] doc: Update readme for address_ namespace

---
 src/address/README.md | 93 +++++++++++++++++++++++++++++--------------
 1 file changed, 64 insertions(+), 29 deletions(-)

diff --git a/src/address/README.md b/src/address/README.md
index 519db87a6..0d3d69cd5 100644
--- a/src/address/README.md
+++ b/src/address/README.md
@@ -1,49 +1,84 @@
 # Address JSON-RPC API
 
+## Table of Contents
+
+- [Address JSON-RPC API](#address-json-rpc-api)
+  - [Table of Contents](#table-of-contents)
+  - [Overview](#overview)
+  - [Separate `address_` namespace](#separate-address_-namespace)
+  - [Database requirement](#database-requirement)
+  - [Rationale for the index existing inside the node](#rationale-for-the-index-existing-inside-the-node)
+  - ["Address appearances" concept](#address-appearances-concept)
+  - [Security considerations](#security-considerations)
+    - [Increased resource use](#increased-resource-use)
+
+## Overview
+
 The Address JSON-RPC API is a collection of methods that Ethereum archival execution clients MAY implement.
 
 This interface allows the use of an archive node from the perspective of an end user.
-It provides information about which transactions are important for a given address. The address
-may be an externally owned account, a smart wallet, an account abstraction wallet or an application contract.
+It provides information about which transactions are important for a given address.
+This includes any address, including an externally owned account, a smart wallet, an account abstraction wallet or an application contract.
 
-The API is desinged around an index mapping addresses to transaction ids. This index is created
-in advance so that queries are responded to quickly and do not require EVM re-execution.
+The API is desinged around an index mapping addresses to transaction identifiers. This index is created in advance so that queries are responded to quickly and do not require block re-execution.
 
-The API allows introspection into otherwise opaque history. An example is an EOA that received
-ether via a CALL opcode. The API can return this transaction id, which can then be used with
-other methods (debug_traceTransaction) to identify the transfer.
+The API allows introspection into otherwise opaque history. An example is an externally
+owned account that received ether via a `CALL` opcode.
+The API can return this transaction id, which can then be used with other methods (e.g., `debug_traceTransaction`) to identify the meaning of the transaction,
+in this case an ether transfer.
 
-# Address API -- Common Definitions
+## Separate `address_` namespace
 
-This document specifies common definitions and requirements affecting Address API specification in general.
+A separace `address_` namespace exists because the method(s) within the namespace
+require additional considerations that the `eth_` namespace does not require.
+Clients that support the `address_` therefore have a clear way to toggle on this feature
+to explicitly opt in to these requirements.
 
-## Table of contents
+The requirements are:
+- Archival node (store history for all blocks)
+- Additional database requirement (see below)
 
-<!-- START doctoc generated TOC please keep comment here to allow auto update -->
-<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+## Database requirement
 
-- [Address JSON-RPC API](#address-json-rpc-api)
-- [Address API -- Common Definitions](#address-api----common-definitions)
-  - [Table of contents](#table-of-contents)
-  - [Errors](#errors)
+A node that supports the `address_` must store an index consisting of a mapping of address
+to transaction identifiers. Each block must be parsed and addresses detected. Then for each
+address the block number and transaction index must be stored.
+
+The space required for a basic implementation is estimated at 80GB. Client implementations
+may be able to reduce this amount significantly.
+
+## Rationale for the index existing inside the node
+
+The rationale for storing the index alongside other chain data is to standardise a new pattern
+of data access. Archive nodes that support the `address_` namespace will be able to provide
+users with the ability to introspect on particular addresses out of the box. This
+means that a frontend can connect to a node and have historical data access for an
+arbitrary combination of addresses.
+
+This provides application developers with a new tool for decentralised front ends that
+include historical information.
+
+As the `address_` namespace methods apply to all addresses, this is a generalised solution
+that makes inclusion inside the node an immediate utility for every user and protocol.
 
+## "Address appearances" concept
 
-<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+`address_getAppearances` is the basic method to discover which transactions are relevant to a given address.
 
-## Errors
+For a given address, this method returns an array of transaction identifiers in which the
+address "appears". An "address appearance" is defined in [../../specs/appearances](../../specs/appearances.md)
 
-The list of error codes introduced by this specification can be found below.
+## Security considerations
 
-| Code | Message | Meaning |
-| - | - | - |
-| -32700 | Parse error | Invalid JSON was received by the server. |
-| -32600 | Invalid Request | The JSON sent is not a valid Request object. |
-| -32601 | Method not found | The method does not exist / is not available. |
-| -32602 | Invalid params | Invalid method parameter(s). |
-| -32603 | Internal error | Internal JSON-RPC error. |
-| -32000 | Server error | Generic client error while processing request. |
-| -38004 | Too large request | Number of requested entities is too large. |
+See [../../specs/appearances](../../specs/appearances.md) for additional security
+considerations.
 
+### Increased resource use
 
-Each error returns a `null` `data` value, except `-32000` which returns the `data` object with a `err` member that explains the error encountered.
+The provision of the `address_` namespace will result in the index being created by
+the client. This can cause a temporary high resource use (CPU/disk), and then an
+additional amount of work as the chain grows.
 
+The amount of new work for a new block may impact a resource constrained node. The
+task involves the equivalent of calling `debug_traceTransaction` with a `callTracer`,
+parsing for addresses, and then adding these to a local database.

From 6a6e3a36f7b80942a9a8f0bfd6d7cbf50e075c69 Mon Sep 17 00:00:00 2001
From: perama-v <83961755+perama-v@users.noreply.github.com>
Date: Sat, 29 Jul 2023 18:01:20 +1000
Subject: [PATCH 05/12] fix: eth_getAppearances -> address_getAppearances

---
 src/address/methods/appearances.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/address/methods/appearances.yaml b/src/address/methods/appearances.yaml
index eecacb243..f052840ea 100644
--- a/src/address/methods/appearances.yaml
+++ b/src/address/methods/appearances.yaml
@@ -1,4 +1,4 @@
-- name: eth_getAddressAppearances
+- name: address_getAppearances
   summary: Returns transaction identifiers relevant to an address.
   params:
     - name: Address

From 8869fbf5aa47e3885063e6a01e9d867a37e23606 Mon Sep 17 00:00:00 2001
From: perama-v <83961755+perama-v@users.noreply.github.com>
Date: Thu, 3 Aug 2023 11:16:05 +1000
Subject: [PATCH 06/12] build(address): add address namespace to build.js

---
 scripts/build.js | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)

diff --git a/scripts/build.js b/scripts/build.js
index 639081f7e..d081a93d3 100644
--- a/scripts/build.js
+++ b/scripts/build.js
@@ -30,6 +30,18 @@ methodFiles.forEach(file => {
   ];
 });
 
+methodsBase = "src/address/methods/";
+methodFiles = fs.readdirSync(methodsBase);
+methodFiles.forEach(file => {
+  console.log(file);
+  let raw = fs.readFileSync(methodsBase + file);
+  let parsed = yaml.load(raw);
+  methods = [
+    ...methods,
+    ...parsed,
+  ];
+});
+
 methodsBase = "src/debug/";
 methodFiles = fs.readdirSync(methodsBase);
 methodFiles.forEach(file => {
@@ -55,6 +67,7 @@ methodFiles.forEach(file => {
 });
 
 let schemas = {};
+
 let schemasBase = "src/schemas/"
 let schemaFiles = fs.readdirSync(schemasBase);
 schemaFiles.forEach(file => {
@@ -67,6 +80,18 @@ schemaFiles.forEach(file => {
   };
 });
 
+schemasBase = "src/address/schemas/"
+schemaFiles = fs.readdirSync(schemasBase);
+schemaFiles.forEach(file => {
+  console.log(file);
+  let raw = fs.readFileSync(schemasBase + file);
+  let parsed = yaml.load(raw);
+  schemas = {
+    ...schemas,
+    ...parsed,
+  };
+});
+
 schemasBase = "src/engine/openrpc/schemas/"
 schemaFiles = fs.readdirSync(schemasBase);
 schemaFiles.forEach(file => {

From 0c2a51d6c9e7faffda7b528afe9f95408d19338d Mon Sep 17 00:00:00 2001
From: perama-v <83961755+perama-v@users.noreply.github.com>
Date: Thu, 3 Aug 2023 11:17:34 +1000
Subject: [PATCH 07/12] fix(address): make test case inputs valid

---
 .../get-appearances-block-range-single.io                       | 2 +-
 tests/address_getAppearances/get-appearances-block-range.io     | 2 +-
 .../get-appearances-error-backward-range.io                     | 2 +-
 .../address_getAppearances/get-appearances-error-half-range.io  | 2 +-
 .../get-appearances-one-block-multiple-transactions.io          | 2 +-
 5 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/tests/address_getAppearances/get-appearances-block-range-single.io b/tests/address_getAppearances/get-appearances-block-range-single.io
index 8194297b5..26b963a31 100644
--- a/tests/address_getAppearances/get-appearances-block-range-single.io
+++ b/tests/address_getAppearances/get-appearances-block-range-single.io
@@ -1,2 +1,2 @@
->> {"jsonrpc":"2.0","id":1,"method":"eth_getBlockByNumber","params":["0x30a4639850b3ddeaaca4f06280aa751682f11382",[17190873, 17190873]]}
+>> {"jsonrpc":"2.0","id":1,"method":"address_getAppearances","params":["0x30a4639850b3ddeaaca4f06280aa751682f11382",["0x1064fd9", "0x1064fd9"]]}
 << {"id":1,"jsonrpc":"2.0","result":[{"blockNumber":17190873,"transactionIndex":95}]}
diff --git a/tests/address_getAppearances/get-appearances-block-range.io b/tests/address_getAppearances/get-appearances-block-range.io
index df9a53b73..6d9724995 100644
--- a/tests/address_getAppearances/get-appearances-block-range.io
+++ b/tests/address_getAppearances/get-appearances-block-range.io
@@ -1,2 +1,2 @@
->> {"jsonrpc":"2.0","id":1,"method":"eth_getBlockByNumber","params":["0x30a4639850b3ddeaaca4f06280aa751682f11382",[17190873, 17190889]]}
+>> {"jsonrpc":"2.0","id":1,"method":"address_getAppearances","params":["0x30a4639850b3ddeaaca4f06280aa751682f11382",["0x1064fd9", "0x1064fe9"]]}
 << {"id":1,"jsonrpc":"2.0","result":[{"blockNumber":17190873,"transactionIndex":95},{"blockNumber":17190889,"transactionIndex":89}]}
diff --git a/tests/address_getAppearances/get-appearances-error-backward-range.io b/tests/address_getAppearances/get-appearances-error-backward-range.io
index 353992437..7f18e4bf4 100644
--- a/tests/address_getAppearances/get-appearances-error-backward-range.io
+++ b/tests/address_getAppearances/get-appearances-error-backward-range.io
@@ -1,2 +1,2 @@
->> {"jsonrpc":"2.0","id":1,"method":"address_getAppearances","params":["0x30a4639850b3ddeaaca4f06280aa751682f11382",[17190874, 17190873]]}
+>> {"jsonrpc":"2.0","id":1,"method":"address_getAppearances","params":["0x30a4639850b3ddeaaca4f06280aa751682f11382",["0x1064fda","0x1064fd9"]]}
 << {"jsonrpc":"2.0","id":1,"result":{"code":-32602,"message":"Invalid params"}}
diff --git a/tests/address_getAppearances/get-appearances-error-half-range.io b/tests/address_getAppearances/get-appearances-error-half-range.io
index e6e98ec1a..e43d42036 100644
--- a/tests/address_getAppearances/get-appearances-error-half-range.io
+++ b/tests/address_getAppearances/get-appearances-error-half-range.io
@@ -1,2 +1,2 @@
->> {"jsonrpc":"2.0","id":1,"method":"address_getAppearances","params":["0x30a4639850b3ddeaaca4f06280aa751682f11382",[17190873]]}
+>> {"jsonrpc":"2.0","id":1,"method":"address_getAppearances","params":["0x30a4639850b3ddeaaca4f06280aa751682f11382",["0x1064fd9"]]}
 << {"jsonrpc":"2.0","id":1,"result":{"code":-32602,"message":"Invalid params"}}
diff --git a/tests/address_getAppearances/get-appearances-one-block-multiple-transactions.io b/tests/address_getAppearances/get-appearances-one-block-multiple-transactions.io
index fd6accf2e..2ded200f8 100644
--- a/tests/address_getAppearances/get-appearances-one-block-multiple-transactions.io
+++ b/tests/address_getAppearances/get-appearances-one-block-multiple-transactions.io
@@ -1,2 +1,2 @@
->> {"jsonrpc":"2.0","id":1,"method":"eth_getBlockByNumber","params":["0x2d7C6B69175c2939173F2fd470538835336Df92b",[17190873, 17190873]]}
+>> {"jsonrpc":"2.0","id":1,"method":"address_getAppearances","params":["0x2d7C6B69175c2939173F2fd470538835336Df92b",["0x1064fd9", "0x1064fd9"]]}
 << {"id":1,"jsonrpc":"2.0","result":[{"blockNumber":17190873,"transactionIndex":103},{"blockNumber":17190873,"transactionIndex":163},{"blockNumber":17190873,"transactionIndex":169},{"blockNumber":17190873,"transactionIndex":179},{"blockNumber":17190873,"transactionIndex":182}]}
\ No newline at end of file

From a494d263c99f2cf36dcfef01c5087be8d93ad1ce Mon Sep 17 00:00:00 2001
From: perama-v <83961755+perama-v@users.noreply.github.com>
Date: Thu, 3 Aug 2023 11:19:59 +1000
Subject: [PATCH 08/12] fix(address): remove tests for expected errors

---
 .../get-appearances-error-backward-range.io                     | 2 --
 .../address_getAppearances/get-appearances-error-half-range.io  | 2 --
 .../get-appearances-error-short-address.io                      | 2 --
 3 files changed, 6 deletions(-)
 delete mode 100644 tests/address_getAppearances/get-appearances-error-backward-range.io
 delete mode 100644 tests/address_getAppearances/get-appearances-error-half-range.io
 delete mode 100644 tests/address_getAppearances/get-appearances-error-short-address.io

diff --git a/tests/address_getAppearances/get-appearances-error-backward-range.io b/tests/address_getAppearances/get-appearances-error-backward-range.io
deleted file mode 100644
index 7f18e4bf4..000000000
--- a/tests/address_getAppearances/get-appearances-error-backward-range.io
+++ /dev/null
@@ -1,2 +0,0 @@
->> {"jsonrpc":"2.0","id":1,"method":"address_getAppearances","params":["0x30a4639850b3ddeaaca4f06280aa751682f11382",["0x1064fda","0x1064fd9"]]}
-<< {"jsonrpc":"2.0","id":1,"result":{"code":-32602,"message":"Invalid params"}}
diff --git a/tests/address_getAppearances/get-appearances-error-half-range.io b/tests/address_getAppearances/get-appearances-error-half-range.io
deleted file mode 100644
index e43d42036..000000000
--- a/tests/address_getAppearances/get-appearances-error-half-range.io
+++ /dev/null
@@ -1,2 +0,0 @@
->> {"jsonrpc":"2.0","id":1,"method":"address_getAppearances","params":["0x30a4639850b3ddeaaca4f06280aa751682f11382",["0x1064fd9"]]}
-<< {"jsonrpc":"2.0","id":1,"result":{"code":-32602,"message":"Invalid params"}}
diff --git a/tests/address_getAppearances/get-appearances-error-short-address.io b/tests/address_getAppearances/get-appearances-error-short-address.io
deleted file mode 100644
index a73fea112..000000000
--- a/tests/address_getAppearances/get-appearances-error-short-address.io
+++ /dev/null
@@ -1,2 +0,0 @@
->> {"jsonrpc":"2.0","id":1,"method":"address_getAppearances","params":["0xeaaca4f06280aa751682f11382"]}
-<< {"jsonrpc":"2.0","id":1,"result":{"code":-32602,"message":"Invalid params"}}

From 4ec2a8e111b71312ee4517e830e94adb61096d34 Mon Sep 17 00:00:00 2001
From: perama-v <83961755+perama-v@users.noreply.github.com>
Date: Thu, 3 Aug 2023 14:38:52 +1000
Subject: [PATCH 09/12] fix(address): Use hex strings for uint in test cases

---
 tests/address_getAppearances/get-appearances-all-blocks-some.io | 2 +-
 .../get-appearances-block-range-single.io                       | 2 +-
 tests/address_getAppearances/get-appearances-block-range.io     | 2 +-
 .../get-appearances-one-block-multiple-transactions.io          | 2 +-
 4 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/tests/address_getAppearances/get-appearances-all-blocks-some.io b/tests/address_getAppearances/get-appearances-all-blocks-some.io
index 37e347902..37437d838 100644
--- a/tests/address_getAppearances/get-appearances-all-blocks-some.io
+++ b/tests/address_getAppearances/get-appearances-all-blocks-some.io
@@ -1,2 +1,2 @@
 >> {"jsonrpc":"2.0","id":1,"method":"address_getAppearances","params":["0x30a4639850b3ddeaaca4f06280aa751682f11382"]}
-<< {"id":1,"jsonrpc":"2.0","result":[{"blockNumber":14040913,"transactionIndex":230},{"blockNumber":14040922,"transactionIndex":283},{"blockNumber":14057812,"transactionIndex":6},{"blockNumber":14064971,"transactionIndex":61},{"blockNumber":14065074,"transactionIndex":75},{"blockNumber":14081630,"transactionIndex":37},{"blockNumber":14081755,"transactionIndex":115},{"blockNumber":14085374,"transactionIndex":102},{"blockNumber":14683020,"transactionIndex":107},{"blockNumber":14683030,"transactionIndex":120},{"blockNumber":14683030,"transactionIndex":121},{"blockNumber":14724641,"transactionIndex":294},{"blockNumber":14870967,"transactionIndex":129},{"blockNumber":14870973,"transactionIndex":316},{"blockNumber":15488280,"transactionIndex":175},{"blockNumber":15488361,"transactionIndex":275},{"blockNumber":15488361,"transactionIndex":284},{"blockNumber":15488363,"transactionIndex":165},{"blockNumber":15488374,"transactionIndex":293},{"blockNumber":15488379,"transactionIndex":265},{"blockNumber":15488388,"transactionIndex":114},{"blockNumber":15488530,"transactionIndex":26},{"blockNumber":15919652,"transactionIndex":34},{"blockNumber":15919705,"transactionIndex":149},{"blockNumber":17189746,"transactionIndex":84},{"blockNumber":17189754,"transactionIndex":158},{"blockNumber":17190681,"transactionIndex":103},{"blockNumber":17190690,"transactionIndex":136},{"blockNumber":17190873,"transactionIndex":95},{"blockNumber":17190889,"transactionIndex":89},{"blockNumber":17194361,"transactionIndex":125},{"blockNumber":17194403,"transactionIndex":163},{"blockNumber":17219903,"transactionIndex":116},{"blockNumber":17572135,"transactionIndex":43}]}
+<< {"id":1,"jsonrpc":"2.0","result":[{"blockNumber":"0xd63f51","transactionIndex":"0xe6"},{"blockNumber":"0xd63f5a","transactionIndex":"0x11b"},{"blockNumber":"0xd68154","transactionIndex":"0x6"},{"blockNumber":"0xd69d4b","transactionIndex":"0x3d"},{"blockNumber":"0xd69db2","transactionIndex":"0x4b"},{"blockNumber":"0xd6de5e","transactionIndex":"0x25"},{"blockNumber":"0xd6dedb","transactionIndex":"0x73"},{"blockNumber":"0xd6ecfe","transactionIndex":"0x66"},{"blockNumber":"0xe00b8c","transactionIndex":"0x6b"},{"blockNumber":"0xe00b96","transactionIndex":"0x78"},{"blockNumber":"0xe00b96","transactionIndex":"0x79"},{"blockNumber":"0xe0ae21","transactionIndex":"0x126"},{"blockNumber":"0xe2e9b7","transactionIndex":"0x81"},{"blockNumber":"0xe2e9bd","transactionIndex":"0x13c"},{"blockNumber":"0xec5518","transactionIndex":"0xaf"},{"blockNumber":"0xec5569","transactionIndex":"0x113"},{"blockNumber":"0xec5569","transactionIndex":"0x11c"},{"blockNumber":"0xec556b","transactionIndex":"0xa5"},{"blockNumber":"0xec5576","transactionIndex":"0x125"},{"blockNumber":"0xec557b","transactionIndex":"0x109"},{"blockNumber":"0xec5584","transactionIndex":"0x72"},{"blockNumber":"0xec5612","transactionIndex":"0x1a"},{"blockNumber":"0xf2ea24","transactionIndex":"0x22"},{"blockNumber":"0xf2ea59","transactionIndex":"0x95"},{"blockNumber":"0x1064b72","transactionIndex":"0x54"},{"blockNumber":"0x1064b7a","transactionIndex":"0x9e"},{"blockNumber":"0x1064f19","transactionIndex":"0x67"},{"blockNumber":"0x1064f22","transactionIndex":"0x88"},{"blockNumber":"0x1064fd9","transactionIndex":"0x5f"},{"blockNumber":"0x1064fe9","transactionIndex":"0x59"},{"blockNumber":"0x1065d79","transactionIndex":"0x7d"},{"blockNumber":"0x1065da3","transactionIndex":"0xa3"},{"blockNumber":"0x106c13f","transactionIndex":"0x74"},{"blockNumber":"0x10c2127","transactionIndex":"0x2b"}]}
diff --git a/tests/address_getAppearances/get-appearances-block-range-single.io b/tests/address_getAppearances/get-appearances-block-range-single.io
index 26b963a31..26ce74d40 100644
--- a/tests/address_getAppearances/get-appearances-block-range-single.io
+++ b/tests/address_getAppearances/get-appearances-block-range-single.io
@@ -1,2 +1,2 @@
 >> {"jsonrpc":"2.0","id":1,"method":"address_getAppearances","params":["0x30a4639850b3ddeaaca4f06280aa751682f11382",["0x1064fd9", "0x1064fd9"]]}
-<< {"id":1,"jsonrpc":"2.0","result":[{"blockNumber":17190873,"transactionIndex":95}]}
+<< {"id":1,"jsonrpc":"2.0","result":[{"blockNumber":"0x1064fd9","transactionIndex":"0x5f"}]}
diff --git a/tests/address_getAppearances/get-appearances-block-range.io b/tests/address_getAppearances/get-appearances-block-range.io
index 6d9724995..099b8a91e 100644
--- a/tests/address_getAppearances/get-appearances-block-range.io
+++ b/tests/address_getAppearances/get-appearances-block-range.io
@@ -1,2 +1,2 @@
 >> {"jsonrpc":"2.0","id":1,"method":"address_getAppearances","params":["0x30a4639850b3ddeaaca4f06280aa751682f11382",["0x1064fd9", "0x1064fe9"]]}
-<< {"id":1,"jsonrpc":"2.0","result":[{"blockNumber":17190873,"transactionIndex":95},{"blockNumber":17190889,"transactionIndex":89}]}
+<< {"id":1,"jsonrpc":"2.0","result":[{"blockNumber":"0x1064fd9","transactionIndex":"0x5f"},{"blockNumber":"0x1064fe9","transactionIndex":"0x59"}]}
diff --git a/tests/address_getAppearances/get-appearances-one-block-multiple-transactions.io b/tests/address_getAppearances/get-appearances-one-block-multiple-transactions.io
index 2ded200f8..45ea4cd12 100644
--- a/tests/address_getAppearances/get-appearances-one-block-multiple-transactions.io
+++ b/tests/address_getAppearances/get-appearances-one-block-multiple-transactions.io
@@ -1,2 +1,2 @@
 >> {"jsonrpc":"2.0","id":1,"method":"address_getAppearances","params":["0x2d7C6B69175c2939173F2fd470538835336Df92b",["0x1064fd9", "0x1064fd9"]]}
-<< {"id":1,"jsonrpc":"2.0","result":[{"blockNumber":17190873,"transactionIndex":103},{"blockNumber":17190873,"transactionIndex":163},{"blockNumber":17190873,"transactionIndex":169},{"blockNumber":17190873,"transactionIndex":179},{"blockNumber":17190873,"transactionIndex":182}]}
\ No newline at end of file
+<< {"id":1,"jsonrpc":"2.0","result":[{"blockNumber":"0x1064fd9","transactionIndex":"0x67"},{"blockNumber":"0x1064fd9","transactionIndex":"0xa3"},{"blockNumber":"0x1064fd9","transactionIndex":"0xa9"},{"blockNumber":"0x1064fd9","transactionIndex":"0xb3"},{"blockNumber":"0x1064fd9","transactionIndex":"0xb6"}]}

From ba047a4b43879313e80c10401e840cbf2f458e12 Mon Sep 17 00:00:00 2001
From: perama-v <83961755+perama-v@users.noreply.github.com>
Date: Fri, 11 Aug 2023 11:07:31 +1000
Subject: [PATCH 10/12] fix(address): use object for block range params

---
 src/address/README.md                           |  4 ++--
 src/address/methods/appearances.yaml            |  5 +----
 src/address/schemas/appearances.yaml            | 17 +++++++++++++++++
 .../get-appearances-block-range-single.io       |  2 +-
 .../get-appearances-block-range.io              |  2 +-
 ...pearances-one-block-multiple-transactions.io |  2 +-
 6 files changed, 23 insertions(+), 9 deletions(-)

diff --git a/src/address/README.md b/src/address/README.md
index 0d3d69cd5..395b6b835 100644
--- a/src/address/README.md
+++ b/src/address/README.md
@@ -66,11 +66,11 @@ that makes inclusion inside the node an immediate utility for every user and pro
 `address_getAppearances` is the basic method to discover which transactions are relevant to a given address.
 
 For a given address, this method returns an array of transaction identifiers in which the
-address "appears". An "address appearance" is defined in [../../specs/appearances](../../specs/appearances.md)
+address "appears". An "address appearance" is defined in [../../specs/appearance](../../specs/appearance.md)
 
 ## Security considerations
 
-See [../../specs/appearances](../../specs/appearances.md) for additional security
+See [../../specs/appearance](../../specs/appearance.md) for additional security
 considerations.
 
 ### Increased resource use
diff --git a/src/address/methods/appearances.yaml b/src/address/methods/appearances.yaml
index f052840ea..508f2f9d6 100644
--- a/src/address/methods/appearances.yaml
+++ b/src/address/methods/appearances.yaml
@@ -8,10 +8,7 @@
     - name: Block range
       required: false
       schema:
-        title: Inclusive block number range with two values [low, high]
-        type: array
-        items:
-          $ref: '#/components/schemas/uint'
+        $ref: '#/components/schemas/BlockRange'
   result:
     name: Address appearances
     schema:
diff --git a/src/address/schemas/appearances.yaml b/src/address/schemas/appearances.yaml
index 546a9637e..28a3fce02 100644
--- a/src/address/schemas/appearances.yaml
+++ b/src/address/schemas/appearances.yaml
@@ -20,3 +20,20 @@ RelevantTransaction:
       title: Transaction index
       description: Index of a transaction that an address appears in
       $ref: '#/components/schemas/uint'
+BlockRange:
+  title: Block range
+  type: object
+  description: Inclusive range of blocks
+  required:
+    - firstBlock
+    - lastBlock
+  additionalProperties: false
+  properties:
+    firstBlock:
+      title: First block
+      description: Lowest block in the range
+      $ref: '#/components/schemas/BlockNumberOrTag'
+    lastBlock:
+      title: Last block
+      description: Highest block in the range
+      $ref: '#/components/schemas/BlockNumberOrTag'
diff --git a/tests/address_getAppearances/get-appearances-block-range-single.io b/tests/address_getAppearances/get-appearances-block-range-single.io
index 26ce74d40..b7b802636 100644
--- a/tests/address_getAppearances/get-appearances-block-range-single.io
+++ b/tests/address_getAppearances/get-appearances-block-range-single.io
@@ -1,2 +1,2 @@
->> {"jsonrpc":"2.0","id":1,"method":"address_getAppearances","params":["0x30a4639850b3ddeaaca4f06280aa751682f11382",["0x1064fd9", "0x1064fd9"]]}
+>> {"jsonrpc":"2.0","id":1,"method":"address_getAppearances","params":["0x30a4639850b3ddeaaca4f06280aa751682f11382",{"firstBlock":"0x1064fd9","lastBlock":"0x1064fd9"}]}
 << {"id":1,"jsonrpc":"2.0","result":[{"blockNumber":"0x1064fd9","transactionIndex":"0x5f"}]}
diff --git a/tests/address_getAppearances/get-appearances-block-range.io b/tests/address_getAppearances/get-appearances-block-range.io
index 099b8a91e..3a6d1f06c 100644
--- a/tests/address_getAppearances/get-appearances-block-range.io
+++ b/tests/address_getAppearances/get-appearances-block-range.io
@@ -1,2 +1,2 @@
->> {"jsonrpc":"2.0","id":1,"method":"address_getAppearances","params":["0x30a4639850b3ddeaaca4f06280aa751682f11382",["0x1064fd9", "0x1064fe9"]]}
+>> {"jsonrpc":"2.0","id":1,"method":"address_getAppearances","params":["0x30a4639850b3ddeaaca4f06280aa751682f11382",{"firstBlock":"0x1064fd9","lastBlock":"0x1064fe9"}]}
 << {"id":1,"jsonrpc":"2.0","result":[{"blockNumber":"0x1064fd9","transactionIndex":"0x5f"},{"blockNumber":"0x1064fe9","transactionIndex":"0x59"}]}
diff --git a/tests/address_getAppearances/get-appearances-one-block-multiple-transactions.io b/tests/address_getAppearances/get-appearances-one-block-multiple-transactions.io
index 45ea4cd12..d8c224789 100644
--- a/tests/address_getAppearances/get-appearances-one-block-multiple-transactions.io
+++ b/tests/address_getAppearances/get-appearances-one-block-multiple-transactions.io
@@ -1,2 +1,2 @@
->> {"jsonrpc":"2.0","id":1,"method":"address_getAppearances","params":["0x2d7C6B69175c2939173F2fd470538835336Df92b",["0x1064fd9", "0x1064fd9"]]}
+>> {"jsonrpc":"2.0","id":1,"method":"address_getAppearances","params":["0x2d7C6B69175c2939173F2fd470538835336Df92b",{"firstBlock":"0x1064fd9","lastBlock":"0x1064fd9"}]}
 << {"id":1,"jsonrpc":"2.0","result":[{"blockNumber":"0x1064fd9","transactionIndex":"0x67"},{"blockNumber":"0x1064fd9","transactionIndex":"0xa3"},{"blockNumber":"0x1064fd9","transactionIndex":"0xa9"},{"blockNumber":"0x1064fd9","transactionIndex":"0xb3"},{"blockNumber":"0x1064fd9","transactionIndex":"0xb6"}]}

From bf20999b07d01ea7763a0ea64b12cf134ba3cec3 Mon Sep 17 00:00:00 2001
From: perama-v <83961755+perama-v@users.noreply.github.com>
Date: Mon, 14 Aug 2023 11:42:13 +1000
Subject: [PATCH 11/12] fix(address): update to latest appearances spec

---
 src/address/schemas/appearances.yaml |  9 ++++-----
 src/schemas/address.yaml             | 17 +++++++++++++++++
 wordlist.txt                         |  1 +
 3 files changed, 22 insertions(+), 5 deletions(-)
 create mode 100644 src/schemas/address.yaml

diff --git a/src/address/schemas/appearances.yaml b/src/address/schemas/appearances.yaml
index 28a3fce02..c1130fc75 100644
--- a/src/address/schemas/appearances.yaml
+++ b/src/address/schemas/appearances.yaml
@@ -9,17 +9,16 @@ RelevantTransaction:
   description: Identifier of a transaction relevant to an address
   required:
     - blockNumber
-    - transactionIndex
+    - location
   additionalProperties: false
   properties:
     blockNumber:
       title: Block number
       description: Block containing the relevant transactions
       $ref: '#/components/schemas/uint'
-    transactionIndex:
-      title: Transaction index
-      description: Index of a transaction that an address appears in
-      $ref: '#/components/schemas/uint'
+    location:
+      title: Location in block
+      $ref: '#/components/schemas/Location'
 BlockRange:
   title: Block range
   type: object
diff --git a/src/schemas/address.yaml b/src/schemas/address.yaml
new file mode 100644
index 000000000..e9259fd6e
--- /dev/null
+++ b/src/schemas/address.yaml
@@ -0,0 +1,17 @@
+Location:
+  title: Location in a block
+  description: A place an address appears within a block
+  oneOf:
+    - title: Transaction index
+      $ref: '#/components/schemas/uint64'
+    - title: Block field
+      $ref: '#/components/schemas/BlockField'
+BlockField:
+  title: Block field
+  description: A block field. Alloc is a genesis block field.
+  type: string
+  enum:
+    - alloc
+    - miner
+    - uncles
+    - withdrawals
\ No newline at end of file
diff --git a/wordlist.txt b/wordlist.txt
index fef7a4af8..ece805892 100644
--- a/wordlist.txt
+++ b/wordlist.txt
@@ -1,3 +1,4 @@
+alloc
 apis
 attributesv
 bodyv

From f0572ce0ccfb6c659d225339c5650b62976c4da0 Mon Sep 17 00:00:00 2001
From: perama-v <83961755+perama-v@users.noreply.github.com>
Date: Mon, 14 Aug 2023 11:42:41 +1000
Subject: [PATCH 12/12] fix(address): update test cases for appearances

---
 tests/address_getAppearances/get-appearances-all-blocks-some.io | 2 +-
 .../address_getAppearances/get-appearances-block-range-miner.io | 2 ++
 .../get-appearances-block-range-single.io                       | 2 +-
 tests/address_getAppearances/get-appearances-block-range.io     | 2 +-
 .../get-appearances-one-block-multiple-transactions.io          | 2 +-
 5 files changed, 6 insertions(+), 4 deletions(-)
 create mode 100644 tests/address_getAppearances/get-appearances-block-range-miner.io

diff --git a/tests/address_getAppearances/get-appearances-all-blocks-some.io b/tests/address_getAppearances/get-appearances-all-blocks-some.io
index 37437d838..cea0a7d95 100644
--- a/tests/address_getAppearances/get-appearances-all-blocks-some.io
+++ b/tests/address_getAppearances/get-appearances-all-blocks-some.io
@@ -1,2 +1,2 @@
 >> {"jsonrpc":"2.0","id":1,"method":"address_getAppearances","params":["0x30a4639850b3ddeaaca4f06280aa751682f11382"]}
-<< {"id":1,"jsonrpc":"2.0","result":[{"blockNumber":"0xd63f51","transactionIndex":"0xe6"},{"blockNumber":"0xd63f5a","transactionIndex":"0x11b"},{"blockNumber":"0xd68154","transactionIndex":"0x6"},{"blockNumber":"0xd69d4b","transactionIndex":"0x3d"},{"blockNumber":"0xd69db2","transactionIndex":"0x4b"},{"blockNumber":"0xd6de5e","transactionIndex":"0x25"},{"blockNumber":"0xd6dedb","transactionIndex":"0x73"},{"blockNumber":"0xd6ecfe","transactionIndex":"0x66"},{"blockNumber":"0xe00b8c","transactionIndex":"0x6b"},{"blockNumber":"0xe00b96","transactionIndex":"0x78"},{"blockNumber":"0xe00b96","transactionIndex":"0x79"},{"blockNumber":"0xe0ae21","transactionIndex":"0x126"},{"blockNumber":"0xe2e9b7","transactionIndex":"0x81"},{"blockNumber":"0xe2e9bd","transactionIndex":"0x13c"},{"blockNumber":"0xec5518","transactionIndex":"0xaf"},{"blockNumber":"0xec5569","transactionIndex":"0x113"},{"blockNumber":"0xec5569","transactionIndex":"0x11c"},{"blockNumber":"0xec556b","transactionIndex":"0xa5"},{"blockNumber":"0xec5576","transactionIndex":"0x125"},{"blockNumber":"0xec557b","transactionIndex":"0x109"},{"blockNumber":"0xec5584","transactionIndex":"0x72"},{"blockNumber":"0xec5612","transactionIndex":"0x1a"},{"blockNumber":"0xf2ea24","transactionIndex":"0x22"},{"blockNumber":"0xf2ea59","transactionIndex":"0x95"},{"blockNumber":"0x1064b72","transactionIndex":"0x54"},{"blockNumber":"0x1064b7a","transactionIndex":"0x9e"},{"blockNumber":"0x1064f19","transactionIndex":"0x67"},{"blockNumber":"0x1064f22","transactionIndex":"0x88"},{"blockNumber":"0x1064fd9","transactionIndex":"0x5f"},{"blockNumber":"0x1064fe9","transactionIndex":"0x59"},{"blockNumber":"0x1065d79","transactionIndex":"0x7d"},{"blockNumber":"0x1065da3","transactionIndex":"0xa3"},{"blockNumber":"0x106c13f","transactionIndex":"0x74"},{"blockNumber":"0x10c2127","transactionIndex":"0x2b"}]}
+<< {"id":1,"jsonrpc":"2.0","result":[{"blockNumber":"0xd63f51","location":"0xe6"},{"blockNumber":"0xd63f5a","location":"0x11b"},{"blockNumber":"0xd68154","location":"0x6"},{"blockNumber":"0xd69d4b","location":"0x3d"},{"blockNumber":"0xd69db2","location":"0x4b"},{"blockNumber":"0xd6de5e","location":"0x25"},{"blockNumber":"0xd6dedb","location":"0x73"},{"blockNumber":"0xd6ecfe","location":"0x66"},{"blockNumber":"0xe00b8c","location":"0x6b"},{"blockNumber":"0xe00b96","location":"0x78"},{"blockNumber":"0xe00b96","location":"0x79"},{"blockNumber":"0xe0ae21","location":"0x126"},{"blockNumber":"0xe2e9b7","location":"0x81"},{"blockNumber":"0xe2e9bd","location":"0x13c"},{"blockNumber":"0xec5518","location":"0xaf"},{"blockNumber":"0xec5569","location":"0x113"},{"blockNumber":"0xec5569","location":"0x11c"},{"blockNumber":"0xec556b","location":"0xa5"},{"blockNumber":"0xec5576","location":"0x125"},{"blockNumber":"0xec557b","location":"0x109"},{"blockNumber":"0xec5584","location":"0x72"},{"blockNumber":"0xec5612","location":"0x1a"},{"blockNumber":"0xf2ea24","location":"0x22"},{"blockNumber":"0xf2ea59","location":"0x95"},{"blockNumber":"0x1064b72","location":"0x54"},{"blockNumber":"0x1064b7a","location":"0x9e"},{"blockNumber":"0x1064f19","location":"0x67"},{"blockNumber":"0x1064f22","location":"0x88"},{"blockNumber":"0x1064fd9","location":"0x5f"},{"blockNumber":"0x1064fe9","location":"0x59"},{"blockNumber":"0x1065d79","location":"0x7d"},{"blockNumber":"0x1065da3","location":"0xa3"},{"blockNumber":"0x106c13f","location":"0x74"},{"blockNumber":"0x10c2127","location":"0x2b"}]}
diff --git a/tests/address_getAppearances/get-appearances-block-range-miner.io b/tests/address_getAppearances/get-appearances-block-range-miner.io
new file mode 100644
index 000000000..1adc693dc
--- /dev/null
+++ b/tests/address_getAppearances/get-appearances-block-range-miner.io
@@ -0,0 +1,2 @@
+>> {"jsonrpc":"2.0","id":1,"method":"address_getAppearances","params":["0xd2090025857b9c7b24387741f120538e928a3a59",{"firstBlock":"0x1064fd9","lastBlock":"0x1064fe9"}]}
+<< {"id":1,"jsonrpc":"2.0","result":[{"blockNumber":"0x1064fd9","location":"0x8"},{"blockNumber":"0x1064fd9","location":"0xcd"},{"blockNumber":"0x1064fd9","location":"miner"}]}
diff --git a/tests/address_getAppearances/get-appearances-block-range-single.io b/tests/address_getAppearances/get-appearances-block-range-single.io
index b7b802636..809e41fa6 100644
--- a/tests/address_getAppearances/get-appearances-block-range-single.io
+++ b/tests/address_getAppearances/get-appearances-block-range-single.io
@@ -1,2 +1,2 @@
 >> {"jsonrpc":"2.0","id":1,"method":"address_getAppearances","params":["0x30a4639850b3ddeaaca4f06280aa751682f11382",{"firstBlock":"0x1064fd9","lastBlock":"0x1064fd9"}]}
-<< {"id":1,"jsonrpc":"2.0","result":[{"blockNumber":"0x1064fd9","transactionIndex":"0x5f"}]}
+<< {"id":1,"jsonrpc":"2.0","result":[{"blockNumber":"0x1064fd9","location":"0x5f"}]}
diff --git a/tests/address_getAppearances/get-appearances-block-range.io b/tests/address_getAppearances/get-appearances-block-range.io
index 3a6d1f06c..dc8b82ea3 100644
--- a/tests/address_getAppearances/get-appearances-block-range.io
+++ b/tests/address_getAppearances/get-appearances-block-range.io
@@ -1,2 +1,2 @@
 >> {"jsonrpc":"2.0","id":1,"method":"address_getAppearances","params":["0x30a4639850b3ddeaaca4f06280aa751682f11382",{"firstBlock":"0x1064fd9","lastBlock":"0x1064fe9"}]}
-<< {"id":1,"jsonrpc":"2.0","result":[{"blockNumber":"0x1064fd9","transactionIndex":"0x5f"},{"blockNumber":"0x1064fe9","transactionIndex":"0x59"}]}
+<< {"id":1,"jsonrpc":"2.0","result":[{"blockNumber":"0x1064fd9","location":"0x5f"},{"blockNumber":"0x1064fe9","location":"0x59"}]}
diff --git a/tests/address_getAppearances/get-appearances-one-block-multiple-transactions.io b/tests/address_getAppearances/get-appearances-one-block-multiple-transactions.io
index d8c224789..cc6912069 100644
--- a/tests/address_getAppearances/get-appearances-one-block-multiple-transactions.io
+++ b/tests/address_getAppearances/get-appearances-one-block-multiple-transactions.io
@@ -1,2 +1,2 @@
 >> {"jsonrpc":"2.0","id":1,"method":"address_getAppearances","params":["0x2d7C6B69175c2939173F2fd470538835336Df92b",{"firstBlock":"0x1064fd9","lastBlock":"0x1064fd9"}]}
-<< {"id":1,"jsonrpc":"2.0","result":[{"blockNumber":"0x1064fd9","transactionIndex":"0x67"},{"blockNumber":"0x1064fd9","transactionIndex":"0xa3"},{"blockNumber":"0x1064fd9","transactionIndex":"0xa9"},{"blockNumber":"0x1064fd9","transactionIndex":"0xb3"},{"blockNumber":"0x1064fd9","transactionIndex":"0xb6"}]}
+<< {"id":1,"jsonrpc":"2.0","result":[{"blockNumber":"0x1064fd9","location":"0x67"},{"blockNumber":"0x1064fd9","location":"0xa3"},{"blockNumber":"0x1064fd9","location":"0xa9"},{"blockNumber":"0x1064fd9","location":"0xb3"},{"blockNumber":"0x1064fd9","location":"0xb6"}]}