# dyRPC overlays

## TL;DR
Overlays allow you to add your custom logic to already deployed contracts to simulate new events and new read-only functions on top of them. With overlays you can create new view functions, modify existing ones, change field visibility, emit new events and query the historical data of any contract with your modified source code. :sparkles:

## Usecases

### 1. New events for existing contracts
Here's a typical dev flow to add new events to existing contracts:

1) pick a contract on mainnet and change it locally, add new events to it where necessary
2) compile it to get the new bytecode
3) if the contract constructor takes any args, you can get the original values from the contract's deployment tx by calling this API:

curl "https://cache.dyrpc.network/etherscan/constructor_args/<CONTRACT_ADDRESS>"

5) create a new overlay, this returns a new `<OVERLAY_HASH>` that can be used in the next step. For simulating multiple contracts, you can provide multiple modified bytecode entries when creating the overlay. You can also create multiple versions of a contract on two different overlays and use all of them for A/B testing.
6) get contract logs via `eth_getLogs`; existing and new events will be returned:

curl "https://node.dyrpc.network/eth/<API_KEY>/<OVERLAY_HASH>" \
  -H 'Content-Type: application/json'                          \
  -d '                                                         \
    { "jsonrpc": "2.0",                                        \
      "method": "eth_getLogs",                                 \
      "id": 1,                                                 \
      "params": [                                              \
        {                                                      \
          "address": "<CONTRACT_ADDRESS>",                     \
          "fromBlock": "<FROM_BLOCK>",                         \
          "toBlock": "<TO_BLOCK>",                             \
          "topics": [<TOPICS>]                                 \
        }                                                      \
    ]                                                          \
  }'

### 2. New read-only functions for existing contracts
If you'd like to extend your existing contract by adding another function you can use this flow:
1) pick one contract on mainnet and change it locally, add new function
2) compile it to get the new bytecode
3) get the constructor args in ABI-encoded bytecode (e.g. from etherscan code tab)
4) create a new overlay, this returns a new `<OVERLAY_HASH>` that can be used in the next step. For simulating multiple contracts, you can provide multiple modified bytecode entries when creating the overlay. You can also create multiple versions of a contract on two different overlays and use all of them for A/B testing.
5) encode the function signature for `getNewFunc()`:

:::info
web3.js:

> web3.eth.abi.encodeFunctionSignature('getNewFunc()')
'0x1e14ec3f'

:::

:::info
web3.py

>>> web3.sha3(text=f"getNewFunc()")[0:4]
HexBytes('0x1e14ec3f')

:::
6) call the new function:

curl "https://node.dyrpc.network/eth/<API_KEY>/<OVERLAY_HASH>" \
  -H 'Content-Type: application/json'                          \
  -d '                                                         \
    '{                                                         \
      "id": 1,                                                 \
      "jsonrpc": "2.0",                                        \
      "method": "eth_call",                                    \
      "params": [                                              \
        {                                                      \
          "to": "<CONTRACT_ADDRESS>",                          \
          "data": "0x1e14ec3f"                                 \
        },                                                     \
        "latest"                                               \
      ]                                                        \
    }'

## Overlay API
This describes the overlay API endpoints used to create, list and delete overlays. Overlays are scoped to the `<API_KEY>` so other users won't see them.

### Creating
In order to use overlays, you can send your new bytecode along with the constructor args (if constructor takes params) to our API.

:::info
:information_source: Make sure to send the bytecode that contains the call to the constructor (vyper: default, solc: `--bin` flag, ape: `deployment_bytecode`) as `creationCode`
:::

curl -X PUT "https://node.dyrpc.network/eth/<API_KEY>/overlay/put" \
  -H 'Content-Type: application/json'                              \
  -d '{                                                            \
    "overlays": {                                                  \
      "<ADDRESS>": {                                               \
        "creationCode": "<NEW_BYTECODE>",                          \
        "constructorArgs": "<CONSTRUCTOR_ARGS_BYTECODE>"           \
      }                                                            \
    }                                                              \
  }' | jq

If all validations are successful, you'll receive a response with the new overlay RPC URL and the `overlayHash`

{
  "message": "Successfully created new overlay",
  "overlayHash": "<OVERLAY_HASH>",
  "addresses": [
    "<CONTRACT_ADDRESS>"
  ],
  "overlayRpcUrl": "https://node.dyrpc.network/eth/<API_KEY>/<OVERLAY_HASH>"
}

You can use `overlayRpcUrl` now in your client app so that your modified code will be used instead of the on-chain code.

:::info
:information_source: You can use overlays for easy A/B testing just by switching the RPC URL used in your client app:

`https://node.dyrpc.network/eth/<API_KEY>`
=> use on-chain code

`https://node.dyrpc.network/eth/<API_KEY>/<OVERLAY_HASH_0>`
=> use modified code from first overlay

`https://node.dyrpc.network/eth/<API_KEY>/<OVERLAY_HASH_1>`
=> use modified code from second overlay
:::

### Listing

curl -X POST "https://node.dyrpc.network/eth/<API_KEY>/overlay/get" \
  -H 'Content-Type: application/json'                               \
  -d '{ "overlayHash": "<OVERLAY_HASH>" }' | jq

### Deleting

curl -X DELETE "https://node.dyrpc.network/eth/<API_KEY>/overlay/delete" \
  -H 'Content-Type: application/json'                                    \
  -d '{"overlayHash": "<OVERLAY_HASH>"}' | jq