Wallets and Secrets

Most Compose apps need some form of credential — an EOA private key, an auth token for an external service, etc. Compose handles both built-in smart wallets and arbitrary user-managed secrets.

Wallets

Many compose apps will need to make blockchain transactions and will need gas and payment funds to do so. By default, Compose will make you a smart wallet which allows you to pay gas fees in fiat as part of your normal monthly Goldsky bill. This allows simple USD based accounting for companies and users who are not “blockchain-native”. You can easily fund these smart wallets with any tokens you may require for your particular business logic (by default Goldsky will pay gas fees if you haven’t funded the wallet yourself). Goldsky hosted wallets are created dynamically and idempotently in your app code, allowing any type of logic in wallet creation — for specifics see Context. However there may be times when specific EOA wallets are needed for specific transactions, such as owner-only contract methods. In those cases you can store your private key securely in a secret — see below for details.

To fund your built-in smart wallet (beyond Goldsky’s default gas-sponsorship behavior), you can retrieve its public key from the compose Dashboard at app.goldsky.com. See monitoring for details.

Examples

import { TaskContext } from "compose";

export async function main({ env, evm }: TaskContext) {

  // a default smart wallet
  // this will make a smart wallet and will sponsor gas by default
  const mySmartWallet = await evm.wallet({ name: "my-wallet" });

  // you can disable gas sponsoring on a smart wallet
  // allowing you to obtain the public key from your compose dashboard and fund it yourself
  const mySelfFundedSmartWallet = await evm.wallet({ 
    name: "my-wallet", 
    sponsorGas: false 
  });

  // make an EOA based wallet using a private key secret 
  // by default privateKey wallets don't use gas sponsoring
  // see below for info about storing the secret
  const myPrivateKeyWallet = await evm.wallet({ 
    privateKey: env.MY_PRIVATE_KEY 
  });
}

Secrets

Compose secrets are scoped to a specific Compose app within your Goldsky project. You can set or update secrets at any time using the CLI, but a running app will only pick up new secret values after a redeploy. This protects running apps from accidental changes and lets you roll forward (or back) safely by pairing a deploy with the secrets it expects. The way secrets are managed in the cloud vs locally is slightly different.

Secret names must be in SCREAMING_SNAKE_CASE — all uppercase letters, digits, and underscores, starting with a letter (e.g. MY_SECRET, API_KEY_V2).

Manage Secrets for Local Dev

In local dev, you’ll put your secrets in your .env file. Every compose app created with goldsky compose init comes with a gitignored .env file by default.

.env

# Compose Local Secrets
PRIVATE_KEY=132981234adsufyadsf78134asdf

Manage Secrets for Cloud

To add or update a secret in the cloud:

goldsky compose secret set MY_PRIVATE_KEY --value xyz123

To update a secret and immediately redeploy so the app picks it up:

goldsky compose secret set MY_PRIVATE_KEY --value xyz123 --redeploy

To remove a cloud secret:

goldsky compose secret delete MY_PRIVATE_KEY

To list all secrets for the app:

goldsky compose secret list

You can also write secrets into your local .env with the same command by adding --env local:

goldsky compose secret set MY_PRIVATE_KEY --value xyz123 --env local

How secrets are stored

Cloud secrets are end-to-end encrypted. When you run goldsky compose secret set, the CLI encrypts the value on your machine with your project’s public key before uploading it, so the value is never sent or stored in plaintext. There is no way to read a secret value back: not from the CLI, not from the dashboard, and not by Goldsky. goldsky compose secret list shows secret names only. A secret is decrypted only inside your running app, where it appears on ctx.env. To rotate a secret, set a new value. The previous value is never displayed, and the dashboard secrets page shows names, not values.

If a secret value would appear in a task run’s trace output, it is redacted in the dashboard. That is intended behavior, not data loss.

Syncing .env to the cloud at deploy

If you’ve been developing locally with secrets in your .env file, compose deploy --sync-env uploads every entry from your .env as a cloud secret before deploying. This is a convenient way to push a whole app’s secrets in one step.

goldsky compose deploy --sync-env

A running app only picks up new secret values after a redeploy. Use --redeploy on secret set, or run goldsky compose deploy yourself.

Using Secrets

For secrets to be injected into your app at runtime, they have to be listed in the secrets: section of the manifest. Only secrets named in the manifest of the currently-deployed version are made available to your tasks — so older deploys keep working even as you add, rename, or remove secrets for newer ones.

compose.yaml

name: "my_app"
secrets:
  - MY_PRIVATE_KEY
  - MY_API_KEY
  - CONTRACT_ADDRESS
tasks:
  - name: "price_fetcher"
    path: "./tasks/fetch_price.ts"
  - name: "data_processor"
    path: "./tasks/process_data.ts"

Inside a task, each secret is exposed on ctx.env under its exact name:

import { TaskContext } from "compose";

export async function main({ env, evm, fetch }: TaskContext) {
  const myPrivateKeyWallet = await evm.wallet({ privateKey: env.MY_PRIVATE_KEY });

  const address = "0x1234567890abcdef1234567890abcdef12345678" as `0x${string}`;
  const questionId = "0xabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcd";

  const { hash } = await myPrivateKeyWallet.writeContract(
    evm.chains.polygon,
    env.CONTRACT_ADDRESS as `0x${string}`,
    "prepareCondition(address,bytes32,uint256)",
    [address, questionId, 2]
  );

  const response = await fetch(`https://api-service/api/v1/path?auth_token=${env.MY_API_KEY}`);
}

Compose

Guides

Reference

Wallets

Examples

Secrets

Manage Secrets for Local Dev

Manage Secrets for Cloud

How secrets are stored

Syncing .env to the cloud at deploy

Using Secrets

Next Steps

App configuration

Deploying and monitoring

​Wallets

​Examples

​Secrets

​Manage Secrets for Local Dev

​Manage Secrets for Cloud

​How secrets are stored

​Syncing .env to the cloud at deploy

​Using Secrets

​Next Steps

App configuration

Deploying and monitoring

Wallets

Examples

Secrets

Manage Secrets for Local Dev

Manage Secrets for Cloud

How secrets are stored

Syncing .env to the cloud at deploy

Using Secrets

Next Steps