compose

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Goldsky Compose

Goldsky Compose is the offchain-to-onchain framework for high-stakes systems. Write TypeScript tasks that run in verifiable sandboxes — triggered by cron, HTTP, or onchain events — with smart wallets, gas sponsorship, and durable collections. Typical use cases: custom price oracles, keepers, circuit breakers, prediction-market resolvers, cross-chain automation, identity/attestation flows, and notifications.

Goldsky Compose是面向高风险系统的链下转链上框架。编写TypeScript 任务，这些任务可在可验证沙箱中运行——由cron、HTTP或链上事件触发——并支持智能钱包、gas赞助和持久化集合。典型用例包括：自定义价格预言机、keeper、断路器、预测市场解析器、跨链自动化、身份/认证流程以及通知服务。

Boundaries

使用边界

Build new Compose apps or explain what Compose is. For debugging a broken app, use
```
/compose-doctor
```
.
Do not serve as a manifest / CLI / API reference. For field syntax, flag lookups, or TaskContext shapes, use
```
/compose-reference
```
.
For
```
goldsky login
```
, use
```
/auth-setup
```
. For generic secret management, use
```
/secrets
```
.

用于构建新的Compose应用或解释Compose是什么。如需调试故障应用，请使用
```
/compose-doctor
```
。
不充当清单/CLI/API参考工具。如需查询字段语法、标志或TaskContext结构，请使用
```
/compose-reference
```
。
如需执行
```
goldsky login
```
，请使用
```
/auth-setup
```
。如需通用密钥管理，请使用
```
/secrets
```
。

Mode Detection

模式检测

Before running commands, check if the

Bash

tool is available:

If Bash is available (CLI mode): use the Walk Me Through It section below to execute commands directly and parse output.
If Bash is NOT available (reference mode): the Quickstart below is enough for most chatbot Q&A. For step-by-step help, output one command at a time and ask the user to paste output back.

在执行命令前，请检查是否可用

Bash

工具：

如果Bash可用（CLI模式）：使用下方的“逐步引导”部分直接执行命令并解析输出。
如果Bash不可用（参考模式）：下方的快速入门指南足以应对大多数聊天机器人问答场景。如需分步帮助，请每次输出一条命令，并要求用户粘贴返回的输出内容。

What Compose Does

Compose的功能

Serverless TypeScript runtime for EVM-aware tasks.
Three trigger types: cron, HTTP, onchain_event.
Smart wallets (managed by Goldsky, gas-sponsored by default) or BYO EOA wallets (user-supplied private key).
Built-in secrets, collections (durable storage), typed contract bindings via codegen.
```
compose dev
```
for hot-reload local dev;
```
compose deploy
```
to ship;
```
compose logs -f
```
to tail.

支持EVM感知任务的无服务器TypeScript运行时。
三种触发类型：cron、HTTP、onchain_event。
智能钱包（由Goldsky托管，默认启用gas赞助）或自备EOA钱包（用户提供私钥）。
内置密钥管理、集合（持久化存储）、通过代码生成实现类型化合约绑定。
使用
```
compose dev
```
进行热重载本地开发；
```
compose deploy
```
部署应用；
```
compose logs -f
```
查看实时日志。

Out of Scope (for this skill)

本技能的范围外内容

Deploying the target onchain contract. Compose writes to contracts that already exist. If the user needs one deployed, direct them to Foundry / Hardhat first and resume here once they have the address + ABI.
Sourcing a contract ABI. The user provides the ABI JSON file; this skill does not fetch from Etherscan / Sourcify.
Funding a BYO EOA. If sponsorship is off, the user must fund the address out-of-band.

部署目标链上合约：Compose仅与已存在的合约交互。如果用户需要部署合约，请先引导他们使用Foundry / Hardhat，待获取合约地址和ABI后再继续使用本技能。
获取合约ABI：用户需提供ABI JSON文件；本技能不会从Etherscan / Sourcify获取ABI。
为自备EOA充值：如果关闭gas赞助，用户必须通过其他方式为地址充值。

Quickstart

快速入门

Install

安装

bash

curl https://goldsky.com | sh
goldsky login

bash

curl https://goldsky.com | sh
goldsky login

Scaffold + deploy

初始化并部署

bash

goldsky compose init <app-name>          # scaffolds a Bitcoin-oracle example
cd <app-name>
goldsky compose dev                      # hot-reload local server on :4000
goldsky compose deploy                   # bundle + upload to cloud
goldsky compose status                   # expect RUNNING
goldsky compose logs -f                  # stream logs

bash

goldsky compose init <app-name>          # 初始化一个比特币预言机示例
cd <app-name>
goldsky compose dev                      # 在:4000端口启动热重载本地服务器
goldsky compose deploy                   # 打包并上传至云端
goldsky compose status                   # 预期状态为RUNNING
goldsky compose logs -f                  # 流式查看日志

Minimal

compose.yaml

+ task

最简

compose.yaml

及任务

yaml

undefined

yaml

undefined

compose.yaml

name: my-oracle api_version: stable secrets:

ORACLE_ADDRESS tasks:
name: hourly_update path: src/tasks/hourly-update.ts triggers:
- type: cron expression: "0 * * * *"


```ts
// src/tasks/hourly-update.ts
import type { TaskContext } from "compose";

export async function main({ evm, env, logEvent }: TaskContext) {
  const wallet = await evm.wallet({ name: "updater" });
  const tx = await wallet.writeContract(
    evm.chains.polygonAmoy,
    env.ORACLE_ADDRESS,
    "update(uint256)",
    [BigInt(Date.now())],
    { confirmations: 3, onReorg: { action: { type: "replay" }, depth: 200 } },
  );
  await logEvent({ code: "updated", message: "ok", data: { hash: tx.hash } });
}

name: my-oracle api_version: stable secrets:

ORACLE_ADDRESS tasks:
name: hourly_update path: src/tasks/hourly-update.ts triggers:
- type: cron expression: "0 * * * *"


```ts
// src/tasks/hourly-update.ts
import type { TaskContext } from "compose";

export async function main({ evm, env, logEvent }: TaskContext) {
  const wallet = await evm.wallet({ name: "updater" });
  const tx = await wallet.writeContract(
    evm.chains.polygonAmoy,
    env.ORACLE_ADDRESS,
    "update(uint256)",
    [BigInt(Date.now())],
    { confirmations: 3, onReorg: { action: { type: "replay" }, depth: 200 } },
  );
  await logEvent({ code: "updated", message: "ok", data: { hash: tx.hash } });
}

Core Concepts

核心概念

Tasks

任务

A task is a TypeScript file exporting

async function main(context, params?)

. Each task declares one or more triggers in

compose.yaml

任务是一个导出

async function main(context, params?)

的TypeScript文件。每个任务会在

compose.yaml

中声明一个或多个触发器。

Triggers

触发器

Type	Fires on	Key config
`cron`	schedule	`expression` (5-field cron)
`http`	HTTP POST to `/tasks/<name>`	`authentication: auth_token \| none` , optional `ip_whitelist`
`onchain_event`	decoded log	`network` (snake_case), `contract` , `events` (viem signature strings)

类型	触发条件	关键配置
`cron`	定时调度	`expression` （5字段cron表达式）
`http`	向 `/tasks/<name>` 发送HTTP POST请求	`authentication: auth_token \| none` ，可选配置 `ip_whitelist`
`onchain_event`	解码后的日志	`network` （蛇形命名）、 `contract` 、 `events` （viem签名字符串）

TaskContext

Every task receives

{ env, fetch, callTask, logEvent, evm, collection }

. Secrets flatten into

context.env

— there is no separate

secrets

namespace. See

/compose-reference

for the full API.

每个任务都会接收

{ env, fetch, callTask, logEvent, evm, collection }

对象。密钥会扁平化到

context.env

中——没有单独的

secrets

命名空间。如需完整API，请查看

/compose-reference

。

Wallets

钱包

Two kinds:

Smart wallet (managed) —
```
evm.wallet({ name: "updater" })
```
. Hosted by Goldsky, gas-sponsored by default. Cannot be used in plain local dev — use
```
compose dev --fork-chains
```
or switch to a BYO EOA.
BYO EOA (private key) —
```
evm.wallet({ privateKey: env.MY_KEY, sponsorGas: true })
```
. Gas sponsorship is OFF by default for BYO EOA wallets; opt in explicitly.

两种类型：

托管智能钱包 —
```
evm.wallet({ name: "updater" })
```
。由Goldsky托管，默认启用gas赞助。无法在纯本地开发中使用——需使用
```
compose dev --fork-chains
```
或切换至自备EOA钱包。
自备EOA（私钥） —
```
evm.wallet({ privateKey: env.MY_KEY, sponsorGas: true })
```
。自备EOA钱包默认关闭gas赞助；需显式开启。

Secrets & env

密钥与环境变量

List names in the manifest's

secrets:

array, set values with

goldsky compose secret set --name X --value Y

(or

compose secret sync

to upload

.env

). Values flatten into

context.env

at runtime. Names must be SCREAMING_SNAKE_CASE.

在清单的

secrets:

数组中列出密钥名称，使用

goldsky compose secret set --name X --value Y

设置值（或使用

compose secret sync

上传

.env

文件）。运行时值会扁平化到

context.env

中。名称必须为大写下划线命名（SCREAMING_SNAKE_CASE）。

Gas sponsorship

Gas赞助

Bundler fallback: Alchemy → Pimlico → Gelato. Broad EVM coverage (mainnet + testnet); see

/compose-reference

for the chain list and caveats.

Bundler备选方案：Alchemy → Pimlico → Gelato。支持广泛的EVM链（主网+测试网）；如需链列表和注意事项，请查看

/compose-reference

。

Dashboard

控制台

Every deployed app has a dashboard at

https://app.goldsky.com/<project_id>/dashboard/compose/<app-name>

每个已部署的应用都有对应的控制台，地址为

https://app.goldsky.com/<project_id>/dashboard/compose/<app-name>

。

Capability Tour

功能演示

Inline worked examples. Start with Cron → writeContract if you don't know which applies.

内嵌实战示例。如果不确定适用场景，请从Cron → writeContract开始。

Cron → writeContract (the scaffold default)

Cron → writeContract（初始化默认模板）

Exactly the minimal task above — a cron task that writes to a contract every hour, with

onReorg: replay

for safety.

正是上述最简任务——一个每小时向合约写入数据的cron任务，配置

onReorg: replay

以确保安全性。

HTTP task with auth_token

带auth_token的HTTP任务

yaml

undefined

yaml

undefined

compose.yaml (task entry)

compose.yaml（任务条目）

name: manual_fire path: src/tasks/manual-fire.ts triggers:
- type: http authentication: auth_token


```ts
// src/tasks/manual-fire.ts
import type { TaskContext } from "compose";

export async function main({ logEvent }: TaskContext, params: { amount: number }) {
  await logEvent({ code: "fired", message: "manual", data: params });
  return { ok: true, received: params.amount };
}

Invoke:

curl -X POST -H "Authorization: Bearer $TOKEN" -d '{"amount": 42}' https://<app-url>/tasks/manual_fire

name: manual_fire path: src/tasks/manual-fire.ts triggers:
- type: http authentication: auth_token


```ts
// src/tasks/manual-fire.ts
import type { TaskContext } from "compose";

export async function main({ logEvent }: TaskContext, params: { amount: number }) {
  await logEvent({ code: "fired", message: "manual", data: params });
  return { ok: true, received: params.amount };
}

调用方式：

curl -X POST -H "Authorization: Bearer $TOKEN" -d '{"amount": 42}' https://<app-url>/tasks/manual_fire

。

Onchain event listener

链上事件监听器

yaml

- name: on_transfer
  path: src/tasks/on-transfer.ts
  triggers:
    - type: onchain_event
      network: polygon_amoy
      contract: "0xYourContract"
      events:
        - "Transfer(address,address,uint256)"

import type { TaskContext } from "compose";

export async function main(
  { evm, logEvent }: TaskContext,
  params: { log: { topics: string[]; data: string; address: string } },
) {
  const decoded = await evm.decodeEventLog(
    [{ type: "event", name: "Transfer", inputs: [/* ABI inputs */] }],
    params.log,
  );
  await logEvent({ code: "transfer", message: "seen", data: decoded });
}

yaml

- name: on_transfer
  path: src/tasks/on-transfer.ts
  triggers:
    - type: onchain_event
      network: polygon_amoy
      contract: "0xYourContract"
      events:
        - "Transfer(address,address,uint256)"

import type { TaskContext } from "compose";

export async function main(
  { evm, logEvent }: TaskContext,
  params: { log: { topics: string[]; data: string; address: string } },
) {
  const decoded = await evm.decodeEventLog(
    [{ type: "event", name: "Transfer", inputs: [/* ABI输入 */] }],
    params.log,
  );
  await logEvent({ code: "transfer", message: "seen", data: decoded });
}

Smart wallet + sponsored writeContract

智能钱包 + 赞助式writeContract

const wallet = await evm.wallet({ name: "my-oracle" }); // sponsorGas defaults TRUE
const tx = await wallet.writeContract(
  evm.chains.base,
  env.FEED_ADDRESS,
  "setPrice(uint256)",
  [1234n],
);

const wallet = await evm.wallet({ name: "my-oracle" }); // sponsorGas默认开启
const tx = await wallet.writeContract(
  evm.chains.base,
  env.FEED_ADDRESS,
  "setPrice(uint256)",
  [1234n],
);

BYO EOA with sponsored gas (opt-in)

带gas赞助的自备EOA（需显式开启）

const wallet = await evm.wallet({
  privateKey: env.MY_KEY,
  sponsorGas: true, // MUST opt in; defaults FALSE
});

const wallet = await evm.wallet({
  privateKey: env.MY_KEY,
  sponsorGas: true, // 必须显式开启；默认关闭
});

Durable storage (collection)

持久化存储（集合）

const runs = await collection<{ id: string; ts: number }>("runs");
await runs.setById("latest", { id: "latest", ts: Date.now() });
const recent = await runs.findOne({ ts: { $gt: Date.now() - 86_400_000 } });

const runs = await collection<{ id: string; ts: number }>("runs");
await runs.setById("latest", { id: "latest", ts: Date.now() });
const recent = await runs.findOne({ ts: { $gt: Date.now() - 86_400_000 } });

Typed contracts via codegen

通过代码生成实现类型化合约

Drop an ABI into

src/contracts/Oracle.json

. After

goldsky compose codegen

(or any

init

dev

deploy

), the contract is available as

evm.contracts.Oracle

. Full workflow in

/compose-reference

将ABI放入

src/contracts/Oracle.json

。执行

goldsky compose codegen

（或任何

init

dev

deploy

命令）后，合约可通过

evm.contracts.Oracle

访问。完整流程请查看

/compose-reference

。

Walk Me Through It

逐步引导

Only activate when Bash is available.

仅当Bash可用时启用。

Step 1 — Verify auth

步骤1 — 验证认证状态

goldsky project list 2>&1

. If not logged in, use

/auth-setup

执行

goldsky project list 2>&1

。如果未登录，请使用

/auth-setup

。

Step 2 — Derive first, ask only the ambiguous

步骤2 — 先推导，仅询问模糊信息

From the user's natural-language prompt, derive as many of these as possible before asking:

Trigger type — "every 5 minutes" → cron; "on each Transfer" → onchain_event; "when I call it" → http.
Chain — named (
```
polygonAmoy
```
,
```
base
```
) → use it; "testnet" with no name → ask.
Read vs write — "track", "index", "notify" → read; "update", "set", "submit" → write.
Wallet — write + sponsored gas → smart wallet (default); user supplied a PK → BYO EOA with
```
sponsorGas: true
```
.
Secrets — any external API key or contract address → needs a secret entry.
api_version
— default to
```
stable
```
unless user asks otherwise.

Only ask the user for fields you couldn't derive.

从用户的自然语言请求中，推导尽可能多的信息，仅询问无法推导的内容：

触发器类型 — “每5分钟一次” → cron；“每次Transfer事件” → onchain_event；“我调用时触发” → http。
链 — 指定名称（
```
polygonAmoy
```
、
```
base
```
）→ 使用该名称；仅说明“测试网”但未指定名称 → 询问用户。
读取 vs 写入 — “跟踪”、“索引”、“通知” → 读取；“更新”、“设置”、“提交” → 写入。
钱包 — 写入操作 + gas赞助 → 智能钱包（默认）；用户提供私钥 → 带
```
sponsorGas: true
```
的自备EOA。
密钥 — 任何外部API密钥或合约地址 → 需要添加密钥条目。
api_version
— 除非用户特别要求，否则默认使用
```
stable
```
。

仅向用户询问无法推导的字段。

Step 3 — Scaffold

步骤3 — 初始化项目

goldsky compose init <name>

. Inspect the scaffold to see the canonical file layout.

执行

goldsky compose init <name>

。检查初始化后的项目结构，了解标准文件布局。

Step 4 — Edit the manifest

步骤4 — 编辑清单

Replace the scaffold's task block with the derived trigger + secret list. Use the YAML snippets from the Capability Tour above.

将初始化模板中的任务块替换为推导得到的触发器和密钥列表。使用上述功能演示中的YAML片段。

Step 5 — Write the task

步骤5 — 编写任务代码

Replace the scaffold's task file with logic derived from the prompt. Use the capability-tour snippet for the chosen trigger as the starting point.

将初始化模板中的任务文件替换为根据请求推导的逻辑。以所选触发器对应的功能演示片段为起点。

Step 6 — Wire secrets and wallets

步骤6 — 配置密钥和钱包

Every name in

compose.yaml

secrets:

→

goldsky compose secret set --name X --value Y

(or add to

.env

compose secret sync

Smart wallet →
```
goldsky compose wallet create --name <name>
```
. Then
```
wallet list
```
to get the address and share with the user (they may need to grant it onchain permissions on the target contract).
BYO EOA → add the private key to
```
.env
```
(SCREAMING_SNAKE_CASE name), reference via
```
env.X
```
in the task.

compose.yaml

的

secrets:

中的每个名称 → 执行

goldsky compose secret set --name X --value Y

（或添加到

.env

文件并执行

compose secret sync

）。

智能钱包 → 执行
```
goldsky compose wallet create --name <name>
```
。然后执行
```
wallet list
```
获取地址并分享给用户（他们可能需要在链上为该地址授予目标合约的权限）。
自备EOA → 将私钥添加到
```
.env
```
文件（使用大写下划线命名），在任务中通过
```
env.X
```
引用。

Step 7 — Local dev

步骤7 — 本地开发

goldsky compose dev

. Smart wallets require

--fork-chains

locally; use a BYO EOA if the user wants to test against a live testnet. For HTTP tasks:

goldsky compose callTask <name> '<json>'

in another terminal.

执行

goldsky compose dev

。智能钱包在本地开发中需要

--fork-chains

；如果用户希望针对真实测试网测试，请使用自备EOA。对于HTTP任务：在另一个终端执行

goldsky compose callTask <name> '<json>'

。

Step 8 — Deploy

步骤8 — 部署应用

goldsky compose deploy

. Expect progress: "Building Dedicated app database…" → "Deploying app…" → "Provisioning infra…" (can take a minute or two on first deploy).

执行

goldsky compose deploy

。预期流程：“Building Dedicated app database…” → “Deploying app…” → “Provisioning infra…”（首次部署可能需要一两分钟）。

Step 9 — Verify

步骤9 — 验证部署

bash

goldsky compose status --json     # expect .status == "RUNNING"
goldsky compose logs -f           # expect app-specific log lines

Share the dashboard URL:

https://app.goldsky.com/<project_id>/dashboard/compose/<app-name>

bash

goldsky compose status --json     # 预期.status == "RUNNING"
goldsky compose logs -f           # 预期看到应用特定的日志行

分享控制台URL：

https://app.goldsky.com/<project_id>/dashboard/compose/<app-name>

。

Important Rules

重要规则

Smart wallets don't work in plain
compose dev
— use
```
--fork-chains
```
or switch to a BYO EOA for local iteration.
BYO EOA gas sponsorship defaults to FALSE — opt in explicitly with
```
sponsorGas: true
```
.
Cloud secrets are not synced from
.env
automatically. Run
```
compose secret sync
```
or
```
compose deploy --sync-env
```
.
Secret names must be SCREAMING_SNAKE_CASE.
api_version
is required for deploy. Default to
```
stable
```
.

智能钱包无法在纯
compose dev
中使用 — 本地迭代需使用
```
--fork-chains
```
或切换至自备EOA钱包。
自备EOA的gas赞助默认关闭 — 需显式添加
```
sponsorGas: true
```
开启。
云端密钥不会自动从
.env
同步。需执行
```
compose secret sync
```
或
```
compose deploy --sync-env
```
。
密钥名称必须为大写下划线命名（SCREAMING_SNAKE_CASE）。
部署必须指定
api_version
。默认使用
```
stable
```
。

compose

Original

Translation

Goldsky Compose

Goldsky Compose

Boundaries

使用边界

Mode Detection

模式检测

What Compose Does

Compose的功能

Out of Scope (for this skill)

本技能的范围外内容

Quickstart

快速入门

Install

安装

Scaffold + deploy

初始化并部署

Minimal compose.yaml + task

最简compose.yaml及任务

compose.yaml

compose.yaml

Core Concepts

核心概念

Tasks

任务

Triggers

触发器

TaskContext

TaskContext

Wallets

钱包

Secrets & env

密钥与环境变量

Gas sponsorship

Gas赞助

Dashboard

控制台

Capability Tour

功能演示

Cron → writeContract (the scaffold default)

Cron → writeContract（初始化默认模板）

HTTP task with auth_token

带auth_token的HTTP任务

compose.yaml (task entry)

compose.yaml（任务条目）

Onchain event listener

链上事件监听器

Smart wallet + sponsored writeContract

智能钱包 + 赞助式writeContract

BYO EOA with sponsored gas (opt-in)

带gas赞助的自备EOA（需显式开启）

Durable storage (collection)

持久化存储（集合）

Typed contracts via codegen

通过代码生成实现类型化合约

Walk Me Through It

逐步引导

Step 1 — Verify auth

步骤1 — 验证认证状态

Step 2 — Derive first, ask only the ambiguous

步骤2 — 先推导，仅询问模糊信息

Step 3 — Scaffold

步骤3 — 初始化项目

Step 4 — Edit the manifest

步骤4 — 编辑清单

Step 5 — Write the task

步骤5 — 编写任务代码

Step 6 — Wire secrets and wallets

步骤6 — 配置密钥和钱包

Step 7 — Local dev

步骤7 — 本地开发

Step 8 — Deploy

步骤8 — 部署应用

Step 9 — Verify

步骤9 — 验证部署

Important Rules

重要规则

Related

Minimal
`compose.yaml`
+ task

最简
`compose.yaml`
及任务