Sidekick Quickstart

Quickstart guide for getting started with Sidekick

There is a public docker image available on GitHub Container Registry.

docker run -p 7500:7500 -e SEQUENCE_PROJECT_ACCESS_KEY=... ghcr.io/0xsequence/sidekick:latest

This will get you started with a local Sidekick backend running on port 7500 with the minimal features.

We recommend setting SEQUENCE_PROJECT_ACCESS_KEY as well but for testing purposes we provide a default one, you can get yours from Sequence Builder.

Backend wallet

Sidekick creates a Sequence Smart Contract Wallet based on the BACKEND_WALLET_PV_KEY or AWS / GCP KMS signer you provide, this allows gas-sponsorship, batching and other optimizations.

To configure the backend wallet, you can:

• Declare your BACKEND_WALLET_PV_KEY in the .env file for a local setup (not recommended for production) or don’t provide it and get a random one generated for you, you can find it in the auto generated dev.key file.
• Use the recommended method: setting up AWS or GCP KMS and adding the necessary credentials in the .env file.

To find out what are the required credentials for local, AWS, or GCP wallet configurations, please refer to the env.example file.

Make sure you choose the correct key types in AWS KMS and GCP KMS.

• AWS KMS: ECC_NIST_P256_KEY_ALIAS
• GCP KMS: GCP_KEY_RING_NAME

Sidekick is built to integrate seamlessly with AWS and GCP KMS, allowing you to use your KMS signer. We’ve developed adapters that make AWS/GCP KMS compatible with the ethers signer type, ensuring compatibility with the latest version.

Sequence Sidekick empowers developers with a scalable, plug-and-play backend solution for blockchain-based applications, allowing you to focus on building without backend complexities.

When using the Sequence Sidekick:

• msg.sender will be the Sequence Wallet address of your EOA, not your EOA address
• tx.origin will be one of the Sequence Relayer addresses
• Ensure proper permissions are granted for contract function calls to the Sequence Wallet address
• View active relayer addresses in the mainnet status page

Start Sidekick in dev mode

1. Clone the Sidekick repository

   git clone https://github.com/0xsequence/sidekick
   
2. Setup the required environment variables

   Required Environment Variables

   Variable	Description
   PROJECT_ACCESS_KEY	Access key from Sequence Builder API Keys

   Optional Environment Variables

   Variable	Description
   BACKEND_WALLET_PV_KEY	Private key for the EOA used to sign transactions
   PORT	Port for the Sidekick server (default: 7500)
   HOST	Host address for the server (default: 0.0.0.0)
   REDIS_HOST	Redis server host (default: localhost)
   REDIS_PORT	Redis server port (default: 6379)
   REDIS_PASSWORD	Password for Redis server (optional)
   DATABASE_URL	PostgreSQL connection string for Sidekick database
   SIDEKICK_API_SECRET_KEY	Secret key required for write access to the Sidekick API
   ETHERSCAN_API_KEY	API key for Etherscan to enable contract verification
   VERIFY_CONTRACT_ON_DEPLOY	Enable automatic contract verification on deployment (set to true to enable)
   DEBUG	Enable debug logging (set to true for verbose output)
   SIGNER_TYPE	Type of signer to use (local, aws_kms, google_kms)
   AWS_REGION	AWS account region
   AWS_ACCESS_KEY_ID	AWS access key ID
   AWS_SECRET_ACCESS_KEY	AWS secret access key
   AWS_KMS_KEY_ID	ID of the KMS key to use
   PROJECT	GCP project name
   LOCATION	GCP project location
   KEY_RING	Key ring name
   CRYPTO_KEY	Crypto key name
   CRYPTO_KEY_VERSION	Crypto key version

   Wallet Configuration Variables

   Choose one of the following configurations:

   For local wallet:

   Variable	Description
   SIGNER_TYPE	local
   BACKEND_WALLET_PV_KEY	0x…	(optional)

   For AWS KMS:

   Variable	Description
   SIGNER_TYPE	aws_kms
   AWS_REGION	AWS account region
   AWS_ACCESS_KEY_ID	AWS access key ID
   AWS_SECRET_ACCESS_KEY	AWS secret access key
   AWS_KMS_KEY_ID	ID of the KMS key to use

   For GCP KMS:

   Variable	Description
   SIGNER_TYPE	google_kms
   PROJECT	GCP project name
   LOCATION	GCP project location
   KEY_RING	Key ring name
   CRYPTO_KEY	Crypto key name
   CRYPTO_KEY_VERSION	Crypto key version

3. Make sure you have Docker installed

   Get it from here

4. Start Sidekick in a Docker container

   pnpm docker:start
   
5. Check your backend wallet address

   curl -X GET 'http://localhost:3000/sidekick/smart-account-address'
   

Dev mode without Docker

If you want to make changes to the codebase and test them without Docker

pnpm install
pnpm dev:withRedis

This will run Sidekick and also start a Redis server.

Gas Sponsorship

On testnet, we sponsor all the transactions. However, on mainnet - you will want to ensure that you sponsor the transactions in order to ensure that they process correctly by sponsoring the contract itself. You can take a deeper look at our Gas Sponsorship solution to learn how to do this.