Introducing token-based access to Ethereum node APIs on Amazon Managed Blockchain

On October 22, 2022, Amazon Managed Blockchain for Ethereum launched an alternative way for interoperable access to Ethereum nodes JSON-RPC APIs for HTTPs and secure WebSockets using token-based access. In this post we demonstrate how to deploy an Ethereum node and access its JSON-RPC APIs using an accessor token.

Managed Blockchain is a fully managed service that allows you to set up and run production-grade blockchain infrastructure. The service allows you to quickly create full node(s) to connect to the public Ethereum networks (Mainnet, Goerli, Ropsten, and Rinkeby). Managed Blockchain for Ethereum does the heavy lifting of spinning up fully-synced Go-ethereum (geth) nodes, enabling you to read data from the blockchain, broadcast transactions and subscribe to on-chain events. The service takes care of instance configuration, software patching, and making sure you have healthy nodes at all times.

The typical way to access Ethereum RPC APIs from Managed Blockchain is using Signature Version 4 (SigV4), a Hash-based Message Authentication Code (HMAC) mechanism used to authenticate AWS SDK calls. It provides several security features, including being able to set a request expiration at signing time and explicit payload signature per request.

Although SigV4 has been the main way to authorize requests, it poses interoperability challenges with established community tools (such as Ethers.js, HardHat MetaMask, The Graph, Chainlink, POKT Network, and Ethereum ETL) that rely on a direct connection to an Ethereum RPC endpoint and are not designed to create and append an AWS SigV4 signature to requests. Customers have relied on middleware or custom proxies that are capable of signing mid-flight requests from applications using Ethereum developer tools to nodes hosted on Managed Blockchain. Token-based access, a new access method for Ethereum nodes on Managed Blockchain, presents a solution to this interoperability problem by allowing customers to optionally use a token to access their node rather than a SigV4 signature. These tokens, or Accessors, can now be provided as part of the request object for the newly introduced endpoints.

When should you use SigV4 or Accessors?

With the option of using AWS SigV4 or Accessors, it is important to understand when to use each method for accessing your Ethereum node(s) on Managed Blockchain. SigV4 prioritizes security and auditability over convenience, while Accessors lean towards convenience and ease of access. Accessors are ideal for local development environments that require convenient, direct access to your Managed Blockchain Ethereum node over the internet, particularly when using developer tools such as Hardhat or Ethers.js. However, for production applications, particularly where a backend application is used to interact with your Ethereum nodes, Sigv4 is the recommended method for access. It requires minimal effort to append the appropriate SigV4 signature to requests to Ethereum node(s) from a backend application within your AWS stack.

For additional considerations about using Accessors via token-based access, refer to the Managed Blockchain Ethereum Developer Guide.

Prerequisites

The AWS Command-Line Interface (CLI) is required for this guide. Refer to Installing or updating the latest version of the AWS CLI.

To access data from Managed Blockchain for Ethereum, you need to have at least one Ethereum node available. The following command shows how to create an Ethereum node on the public Goerli testnet in the us-east-1a Availability Zone of the us-east-1 Region (N. Virginia). If you wish to learn more about creating an Ethereum node on Managed Blockchain, refer to Working with Ethereum nodes using Managed Blockchain. Alternatively, go to the Managed Blockchain Console to create a node.

$ aws managedblockchain create-node \
--network-id=n-ethereum-goerli \
--region=us-east-1 \
--node-configuration='{"InstanceType":"bc.t3.large","AvailabilityZone":"us-east-1a"}'

Note: creating a Goerli and Mainnet node takes approximately 30 and 60 minutes, respectively.

For the complete list of Regions where Managed Blockchain is available, refer to the Service Endpoints Page or the AWS Regional Services List.

Create your first Accessor

To access RPC data for your Ethereum server, you first need to have at least one active Accessor for your account and Region of choice. At a later point, we use one of the Accessor’s attributes, BillingToken, to append to a specific endpoint URL, corresponding to the Ethereum node available on your account. Create your Accessor with the following command:

$ aws managedblockchain create-accessor --accessor-type=BILLING_TOKEN
{
    "AccessorId": "ac-XXXXXXXXXXXXXXXXXXXXXXXXXX",
    "BillingToken": "Abc-D01efGhiJKLmn234MNOPqrS_TuvWxyzA56bcd7"
}

Note: If you get the error message aws: error: argument operation: Invalid choice, make sure you are using the latest AWS CLI version.

The billing token is only returned on the create-accessor and get-accessor SDK calls. Alternatively, the following code shows two ways to see information about existing accessors:

$ aws managedblockchain list-accessors
{
    "Accessors": [
        {
            "Id": "ac-XXXXXXXXXXXXXXXXXXXXXXXXXX",
            "Type": "BILLING_TOKEN",
            "Status": "AVAILABLE",
            "CreationDate": "2022-10-11T14:47:56.827000+00:00",
            "Arn": "arn:aws:managedblockchain:us-east-1:1234567890:accessors/ac-XXXXXXXXXXXXXXXXXXXXXXXXXX"
        }
    ]
}

$ aws managedblockchain get-accessor --accessor-id="ac-XXXXXXXXXXXXXXXXXXXXXXXXXX"
{
   "BillingToken": "Abc-D01efGhiJKLmn234MNOPqrS_TuvWxyzA56bcd7"
   "Id": "ac-XXXXXXXXXXXXXXXXXXXXXXXXXX",
   "Type": "BILLING_TOKEN",
   "Status": "AVAILABLE",
   "CreationDate": "2022-10-11T14:47:56.827000+00:00",
   "Arn": "arn:aws:managedblockchain:us-east-1:1234567890:accessors/ac-XXXXXXXXXXXXXXXXXXXXXXXXXX"
}

For a complete run-down of the Accessor operations, refer to the document Using token based access to make Ethereum API calls to Ethereum nodes in Amazon Managed Blockchain.

Assemble the HTTPs and secure WebSocket URLs for the endpoints accessible by token

To assemble the HTTPs and secure WebSocket URLs, use the following code:

# Getting node information for Ethereum Goerli test network
$ aws managedblockchain list-nodes --network-id=n-ethereum-goerli 

{
    "Nodes": [
        {
            "Id": "nd-YYYYYYYYYYYYYYYYYYYYYYYYYY",
            "Status": "AVAILABLE",
            "CreationDate": "2022-01-01T00:00:00.000000+00:00",
            "AvailabilityZone": "us-east-1a",
            "InstanceType": "bc.t3.xlarge",
            "Arn": "arn:aws:managedblockchain:us-east-1:199335414706:nodes/nd-YYYYYYYYYYYYYYYYYYYYYYYYYY"
        }
    ]
}

The endpoint URLs have a specific format, different from the traditional ones, used with SigV4. The following Python code does the needed text interpolation to get to the final endpoint URLs:

aws_region = "us-east-1"
node_id = "nd-YYYYYYYYYYYYYYYYYYYYYYYYYY"
accessor_token = "Abc-D01efGhiJKLmn234MNOPqrS_TuvWxyzA56bcd7"

endpoint_https = "https://{node_id}.t.ethereum.managedblockchain.{aws_region}.amazonaws.com/?billingtoken={accessor_token}".format(node_id=node_id, aws_region=aws_region, accessor_token=accessor_token)
# https://nd-YYYYYYYYYYYYYYYYYYYYYYYYYY.t.ethereum.managedblockchain.us-east-1.amazonaws.com/?billingtoken=Abc-D01efGhiJKLmn234MNOPqrS_TuvWxyzA56bcd7

endpoint_wss = "wss://{node_id}.wss.t.ethereum.managedblockchain.{aws_region}.amazonaws.com/?billingtoken={accessor_token}".format(node_id=node_id, aws_region=aws_region, accessor_token=accessor_token)
# wss://nd-YYYYYYYYYYYYYYYYYYYYYYYYYY.wss.t.ethereum.managedblockchain.us-east-1.amazonaws.com/?billingtoken=Abc-D01efGhiJKLmn234MNOPqrS_TuvWxyzA56bcd7

Test the token-based endpoints

In this section, we present two methods to test the token-based endpoints.

Test using the HTTPs endpoint

The following code demonstrates how to install the Web3.py library to handle RPC requests, enter the Python REPL, and run commands over a HTTPs connection. Note that the endpoints are different from the traditional (SigV4) ones, it includes a .t. subdomain.

$ pip install web3

$ python

>>> from web3 import Web3

>>> endpoint_https = "https://nd-YYYYYYYYYYYYYYYYYYYYYYYYYY.t.ethereum.managedblockchain.us-east-1.amazonaws.com/?billingtoken=Abc-D01efGhiJKLmn234MNOPqrS_TuvWxyzA56bcd7"

# Create a HTTPProvider with the proper endpoint
>>> w3 = Web3(Web3.HTTPProvider(endpoint_https))

# Check the latest block number
>>> w3.eth.blockNumber
7925328

# Check how many gas units were consumed in the latest block
>>> w3.eth.getBlock("latest", False).gasUsed
4607505

Test using secure WebSockets endpoint with wscat

wscat is a community Node.js tool that provides an easy interface to WebSocket endpoints. After you run the command with the URL to connect to, anything entered on the prompt is transferred to the remote endpoint. Any responses are immediately displayed at the current session. See the following code:

$ wscat -c "wss://nd-YYYYYYYYYYYYYYYYYYYYYYYYYY.wss.t.ethereum.managedblockchain.us-east-1.amazonaws.com/?billingtoken=Abc-D01efGhiJKLmn234MNOPqrS_TuvWxyzA56bcd7"

Connected (press CTRL+C to quit)

> {"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id": 1}

< {"jsonrpc":"2.0","id":1,"result":"0x78d07b"}

Conclusion

Accessors unlock new ways to interact with Ethereum nodes provided by Managed Blockchain, and reduce the reliance on middleware or proxies required to develop and test Ethereum applications using common tools such as Ethers.js, HardHat, MetaMask, and more. While you can, and should, use SigV4 authentication when security and auditability are of utmost importance, token-based access presents a convenient method for accessing your Ethereum nodes.

You can use the comments section, Ethereum Stack Exchange, or AWS re:post to engage with the AWS Blockchain community, should any questions arise.

About the author

Everton Fraga works as Sr. Blockchain/Web3 Specialist SA at AWS. He helps companies worldwide to build Web3 infrastructure and applications. Former Software Engineer at Ethereum Foundation.