diff --git a/src/config/sidebar.ts b/src/config/sidebar.ts index 3cc950c98ed..d2fb9304b86 100644 --- a/src/config/sidebar.ts +++ b/src/config/sidebar.ts @@ -140,7 +140,11 @@ export const SIDEBAR: Partial> = { "cre/getting-started/part-4-writing-onchain-go", ], }, - { title: "Conclusion & Next Steps", url: "cre/getting-started/conclusion" }, + { + title: "Before You Build", + url: "cre/getting-started/before-you-build", + highlightAsCurrent: ["cre/getting-started/before-you-build-ts", "cre/getting-started/before-you-build-go"], + }, ], }, { diff --git a/src/content/cre/getting-started/before-you-build-go.mdx b/src/content/cre/getting-started/before-you-build-go.mdx new file mode 100644 index 00000000000..d9547b74bc8 --- /dev/null +++ b/src/content/cre/getting-started/before-you-build-go.mdx @@ -0,0 +1,92 @@ +--- +section: cre +title: "Before You Build" +date: Last Modified +pageId: "getting-started-before-you-build" +sdkLang: "go" +metadata: + description: "Essential tips before building your own CRE workflows: working with time, randomness, and next steps for production deployment." + datePublished: "2026-02-04" + lastModified: "2026-02-04" +--- + +import { Aside } from "@components" + +You've completed the Getting Started guide and built a workflow that fetches offchain data, reads from a smart contract, performs calculations, and writes results onchain. You're ready to build your own workflows. + +Before you do, take two minutes to understand how CRE differs from typical development. These tips will save you debugging time. + +## Working with time + +If your workflow uses timestamps (e.g., for API authentication or time-based queries), use `runtime.Now()` instead of `time.Now()`. This ensures all nodes in the DON use the same timestamp and can reach consensus. + +{/* prettier-ignore */} + + +## Working with randomness + +If your workflow needs random values (e.g., selecting a winner or generating nonces), use `runtime.Rand()` instead of Go's `rand` package. This ensures all nodes generate the same random sequence and can reach consensus. + +{/* prettier-ignore */} + + +{/* prettier-ignore */} + + +## What's next? + +Here are resources to help you go from simulation to production. + +### Learn from examples + +- **[Run the Custom Data Feed Demo](/cre/templates/running-demo-workflow)** — A starter template you can run locally and customize +- **[Browse all Templates](/cre/templates)** — Building blocks for specific patterns (secrets, HTTP auth, streams) and starter templates +- **[AI-Powered Prediction Market](/cre/demos/prediction-market)** — Full end-to-end demo integrating CRE with Gemini AI and Firebase + +### Deploy to production + +{/* prettier-ignore */} + + +1. **[Link a Wallet Key](/cre/organization/linking-keys)** — Connect your wallet to your organization +1. **[Deploy Your Workflow](/cre/guides/operations/deploying-workflows)** — Push your workflow live +1. **[Monitor Your Workflow](/cre/guides/operations/monitoring-workflows)** — Watch it execute and debug issues + +### Explore different triggers + +You used a Cron trigger. Most production workflows react to events: + +- **[HTTP Trigger](/cre/guides/workflow/using-triggers/http-trigger/overview)** — Trigger via API calls +- **[EVM Log Trigger](/cre/guides/workflow/using-triggers/evm-log-trigger)** — React to onchain events + +### Add secrets + +Real workflows need API keys and sensitive data: + +- **[Using Secrets in Simulation](/cre/guides/workflow/secrets/using-secrets-simulation)** — Local development +- **[Using Secrets with Deployed Workflows](/cre/guides/workflow/secrets/using-secrets-deployed)** — Store secrets in the Vault DON for production +- **[Managing Secrets with 1Password](/cre/guides/workflow/secrets/managing-secrets-1password)** — Best practice: inject secrets at runtime + +### Build your own consumer contract + +- **[Building Consumer Contracts](/cre/guides/workflow/using-evm-client/onchain-write/building-consumer-contracts)** — Create contracts that receive CRE data + +## Reference + +Dive deeper into concepts from this guide: + +| Topic | Resources | +| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| **Workflow structure** | [Core SDK](/cre/reference/sdk/core), [Triggers Overview](/cre/guides/workflow/using-triggers/overview) | +| **HTTP & offchain data** | [API Interactions](/cre/guides/workflow/using-http-client), [Consensus & Aggregation](/cre/reference/sdk/consensus) | +| **EVM interactions** | [EVM Client Overview](/cre/guides/workflow/using-evm-client/overview), [Onchain Read](/cre/guides/workflow/using-evm-client/onchain-read), [Onchain Write](/cre/guides/workflow/using-evm-client/onchain-write/overview) | +| **Configuration** | [Project Configuration](/cre/reference/project-configuration), [Secrets Guide](/cre/guides/workflow/secrets) | +| **All capabilities** | [Capabilities Overview](/cre/capabilities) | diff --git a/src/content/cre/getting-started/before-you-build-ts.mdx b/src/content/cre/getting-started/before-you-build-ts.mdx new file mode 100644 index 00000000000..031aa7a0f56 --- /dev/null +++ b/src/content/cre/getting-started/before-you-build-ts.mdx @@ -0,0 +1,115 @@ +--- +section: cre +title: "Before You Build" +date: Last Modified +pageId: "getting-started-before-you-build" +sdkLang: "ts" +metadata: + description: "Essential tips before building your own CRE workflows: library compatibility, Solidity integers, working with time, and next steps for production deployment." + datePublished: "2026-02-04" + lastModified: "2026-02-04" +--- + +import { Aside } from "@components" + +You've completed the Getting Started guide and built a workflow that fetches offchain data, reads from a smart contract, performs calculations, and writes results onchain. You're ready to build your own workflows. + +Before you do, take two minutes to understand how CRE differs from typical development. These tips will save you debugging time. + +## Library compatibility + +Your TypeScript code compiles to WebAssembly and runs in a QuickJS environment, **not Node.js**. Some NPM packages won't work if they rely on Node.js-specific APIs like `node:crypto` or `node:fs`. + +**Before using a third-party package:** + +1. Check if it relies on Node.js built-in modules +1. Test with `cre workflow simulate` — simulation uses the same WASM environment as production, so compatibility issues surface immediately + +{/* prettier-ignore */} + + +## Working with Solidity integers + +When sending values to smart contracts, always use `bigint` (with the `n` suffix) in your workflow code. JavaScript `number` loses precision for large values, causing **silent precision loss**. + +```typescript +// WRONG - silent precision loss +const amount = 10000000000000001 // 10 quadrillion + 1 +// Silently becomes 10000000000000000 (the +1 vanishes) + +// CORRECT - use bigint +const amount = 10000000000000001n // Stays exactly 10000000000000001 +``` + +{/* prettier-ignore */} + + +## Working with time + +If your workflow uses timestamps (e.g., for API authentication or time-based queries), use `runtime.now()` instead of `Date.now()`. This ensures all nodes in the DON use the same timestamp and can reach consensus. + +{/* prettier-ignore */} + + +{/* prettier-ignore */} + + +## What's next? + +Here are resources to help you go from simulation to production. + +### Learn from examples + +- **[Run the Custom Data Feed Demo](/cre/templates/running-demo-workflow)** — A starter template you can run locally and customize +- **[Browse all Templates](/cre/templates)** — Building blocks for specific patterns (secrets, HTTP auth, streams) and starter templates +- **[AI-Powered Prediction Market](/cre/demos/prediction-market)** — Full end-to-end demo integrating CRE with Gemini AI and Firebase + +### Deploy to production + +{/* prettier-ignore */} + + +1. **[Link a Wallet Key](/cre/organization/linking-keys)** — Connect your wallet to your organization +1. **[Deploy Your Workflow](/cre/guides/operations/deploying-workflows)** — Push your workflow live +1. **[Monitor Your Workflow](/cre/guides/operations/monitoring-workflows)** — Watch it execute and debug issues + +### Explore different triggers + +You used a Cron trigger. Most production workflows react to events: + +- **[HTTP Trigger](/cre/guides/workflow/using-triggers/http-trigger/overview)** — Trigger via API calls +- **[EVM Log Trigger](/cre/guides/workflow/using-triggers/evm-log-trigger)** — React to onchain events + +### Add secrets + +Real workflows need API keys and sensitive data: + +- **[Using Secrets in Simulation](/cre/guides/workflow/secrets/using-secrets-simulation)** — Local development +- **[Using Secrets with Deployed Workflows](/cre/guides/workflow/secrets/using-secrets-deployed)** — Store secrets in the Vault DON for production +- **[Managing Secrets with 1Password](/cre/guides/workflow/secrets/managing-secrets-1password)** — Best practice: inject secrets at runtime + +### Build your own consumer contract + +- **[Building Consumer Contracts](/cre/guides/workflow/using-evm-client/onchain-write/building-consumer-contracts)** — Create contracts that receive CRE data + +## Reference + +Dive deeper into concepts from this guide: + +| Topic | Resources | +| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| **Workflow structure** | [Core SDK](/cre/reference/sdk/core), [Triggers Overview](/cre/guides/workflow/using-triggers/overview) | +| **HTTP & offchain data** | [API Interactions](/cre/guides/workflow/using-http-client), [Consensus & Aggregation](/cre/reference/sdk/consensus) | +| **EVM interactions** | [EVM Client Overview](/cre/guides/workflow/using-evm-client/overview), [Onchain Read](/cre/guides/workflow/using-evm-client/onchain-read), [Onchain Write](/cre/guides/workflow/using-evm-client/onchain-write/overview) | +| **Configuration** | [Project Configuration](/cre/reference/project-configuration), [Secrets Guide](/cre/guides/workflow/secrets) | +| **All capabilities** | [Capabilities Overview](/cre/capabilities) | diff --git a/src/content/cre/getting-started/conclusion.mdx b/src/content/cre/getting-started/conclusion.mdx deleted file mode 100644 index 7d62e3c1910..00000000000 --- a/src/content/cre/getting-started/conclusion.mdx +++ /dev/null @@ -1,115 +0,0 @@ ---- -section: cre -title: "Conclusion & Next Steps" -date: Last Modified -metadata: - description: "Getting started conclusion: next steps after completing the tutorial - deploy to production, explore triggers, and build custom contracts." - datePublished: "2025-11-04" - lastModified: "2025-11-04" ---- - -import { Aside } from "@components" - -You've built a complete, end-to-end CRE workflow from scratch. - -You started with an empty project and progressively built a workflow that: - -- Fetches data from an offchain API with consensus -- Reads values from a smart contract -- Performs calculations combining onchain and offchain data -- Writes results back to the blockchain - -**This is no small achievement.** You've mastered the core pattern that powers most CRE workflows: the trigger-and-callback model with capabilities for HTTP, EVM, and consensus. - -## What's next? - -Now that you have a working workflow, here's your natural progression from simulation to production and beyond. - -### 1. See a complete example - -Ready to see all these concepts in a more complex, real-world scenario? - -- **[Run the Custom Data Feed Demo](/cre/templates/running-demo-workflow)** - Explore an advanced template that combines multiple capabilities - -**Why this matters:** Templates show production-ready patterns. - -### 2. Deploy your Calculator workflow to Production - -You've simulated your workflow locally. **The logical next step is to deploy it to the CRE production environment** so it runs across a Decentralized Oracle Network (DON). - -{/* prettier-ignore */} - - -**Follow this deployment sequence:** - -1. **[Link a Wallet Key](/cre/organization/linking-keys)** - Connect your wallet address to your organization (required before deployment) -1. **[Deploy Your Workflow](/cre/guides/operations/deploying-workflows)** - Push your calculator workflow live -1. **[Monitor Your Workflow](/cre/guides/operations/monitoring-workflows)** - Watch it execute in production and debug any issues - -**Why this matters:** Deploying moves your workflow from local simulation to production execution across a DON. - -### 3. Explore different triggers - -You used a **Cron trigger** (time-based). **Most production workflows react to real-world events.** - -**Try these next:** - -- **[HTTP Trigger](/cre/guides/workflow/using-triggers/http-trigger/overview)** - Let external systems trigger your workflow via API calls -- **[EVM Log Trigger](/cre/guides/workflow/using-triggers/evm-log-trigger)** - React to onchain events (e.g., token transfers, contract events) - -**Why this matters:** Event-driven workflows are more powerful than scheduled ones. They respond instantly to real-world changes. - -### 4. Add secrets - -Your calculator used a public API. **Real workflows often need API keys and other sensitive data.** - -**Learn how to secure your secrets:** - -- **[Using Secrets in Simulation](/cre/guides/workflow/secrets/using-secrets-simulation)** - Store secrets in your local environment for development -- **[Using Secrets with Deployed Workflows](/cre/guides/workflow/secrets/using-secrets-deployed)** - Store secrets in the Vault DON for production -- **[Managing Secrets with 1Password](/cre/guides/workflow/secrets/managing-secrets-1password)** - Best practice: inject secrets at runtime - -**Why this matters:** Hardcoded credentials are a security risk. CRE's secrets management lets you safely use authenticated APIs and private keys. - -### 5. Build your own consumer contract - -You used a **pre-deployed consumer contract**. **For production workflows, you'll create custom contracts tailored to your use case.** - -**Learn the secure pattern:** - -- **[Building Consumer Contracts](/cre/guides/workflow/using-evm-client/onchain-write/building-consumer-contracts)** - Create contracts that safely receive CRE data - -**Why this matters:** Consumer contracts enforce business logic and validation onchain, enabling trustless and verifiable execution. - -## Reference: Deepen Your Understanding - -Want to dive deeper into specific concepts from the Getting Started guide? Use this section as a quick reference. - -**Workflow Structure & Triggers** - -- **[Core SDK Reference](/cre/reference/sdk/core/)** - Fundamental building blocks (`InitWorkflow`, `Handler`, `Runtime`) -- **[Triggers Overview](/cre/guides/workflow/using-triggers/overview)** - Compare all available event sources - -**HTTP & Offchain Data** - -- **[API Interactions Guide](/cre/guides/workflow/using-http-client/)** - Complete patterns for HTTP requests -- **[Consensus & Aggregation](/cre/reference/sdk/consensus)** - All aggregation methods (median, mode, custom) -- **[Consensus Computing Concept](/cre/concepts/consensus-computing)** - How CRE's consensus-based execution works - -**EVM & Onchain Interactions** - -- **[EVM Client Overview](/cre/guides/workflow/using-evm-client/overview)** - Introduction to smart contract interactions -- **[Onchain Read Guide](/cre/guides/workflow/using-evm-client/onchain-read)** - Reading from a smart contract -- **[Onchain Write Guide](/cre/guides/workflow/using-evm-client/onchain-write/overview)** - Complete write patterns and report generation - -**Configuration & Secrets** - -- **[Project Configuration](/cre/reference/project-configuration/)** - Complete guide to `project.yaml`, `workflow.yaml`, and targets -- **[Secrets Guide](/cre/guides/workflow/secrets)** - All secrets management patterns - -**All Capabilities** - -- **[Capabilities Overview](/cre/capabilities/)** - See the full list of CRE capabilities and how they work together diff --git a/src/content/cre/getting-started/part-4-writing-onchain-go.mdx b/src/content/cre/getting-started/part-4-writing-onchain-go.mdx index 2dc7b2d5ba5..145ef82f504 100644 --- a/src/content/cre/getting-started/part-4-writing-onchain-go.mdx +++ b/src/content/cre/getting-started/part-4-writing-onchain-go.mdx @@ -204,4 +204,4 @@ To learn more about implementing consumer contracts and the secure write process You've now mastered the complete CRE development workflow! -- **[Conclusion & Next Steps](/cre/getting-started/conclusion)**: Review what you've learned and find resources for advanced topics. +- **[Before You Build](/cre/getting-started/before-you-build-go)**: Don't skip this — critical tips before building your own workflows. diff --git a/src/content/cre/getting-started/part-4-writing-onchain-ts.mdx b/src/content/cre/getting-started/part-4-writing-onchain-ts.mdx index 226b8719fef..8f890d953cf 100644 --- a/src/content/cre/getting-started/part-4-writing-onchain-ts.mdx +++ b/src/content/cre/getting-started/part-4-writing-onchain-ts.mdx @@ -205,4 +205,4 @@ To learn more about implementing consumer contracts and the secure write process You've now mastered the complete CRE development workflow! -- **[Conclusion & Next Steps](/cre/getting-started/conclusion)**: Review what you've learned and find resources for advanced topics. +- **[Before You Build](/cre/getting-started/before-you-build-ts)**: Don't skip this — critical tips before building your own workflows. diff --git a/src/content/cre/guides/workflow/using-evm-client/onchain-write/writing-data-onchain.mdx b/src/content/cre/guides/workflow/using-evm-client/onchain-write/writing-data-onchain.mdx index ee480ef131e..ac97779cba8 100644 --- a/src/content/cre/guides/workflow/using-evm-client/onchain-write/writing-data-onchain.mdx +++ b/src/content/cre/guides/workflow/using-evm-client/onchain-write/writing-data-onchain.mdx @@ -88,9 +88,21 @@ const reportData = encodeAbiParameters(parseAbiParameters("address"), ["0x123456 const reportData = encodeAbiParameters(parseAbiParameters("bool"), [true]) ``` -