Skip to content
nXCC

Getting Started with nXCC

Welcome to nXCC! This guide will get you up and running with your first cross-chain worker in just a few steps.

Quick Start

Section titled “Quick Start”

Pick the runtime that matches your setup.

  1. Run the container with host-only port mappings so the HTTP API and libp2p are reachable:

    docker run --rm \
      --add-host=host.docker.internal:host-gateway \
      -p 127.0.0.1:6922:6922 \
      -p 127.0.0.1:9000:9000 \
      ghcr.io/nxcc-bridge/node:latest

  2. Access the node at http://localhost:6922 (HTTP API) while keeping port 9000 available for libp2p peers. Remove the leading 127.0.0.1: to expose the node to the network.

  3. To reach services running on your host (for example an Anvil instance on 127.0.0.1:8545), connect to http://host.docker.internal:8545

Your First Worker

Section titled “Your First Worker”

Create a simple worker that runs in a secure environment:

# Install the CLI
npm install -g @nxcc/cli


# Create a new project
nxcc init my-nxcc-app
cd my-nxcc-app
npm install

The CLI creates a complete project structure. Let’s look at the generated worker:

workers/my-worker.ts
import { worker, type WorkerContext } from "@nxcc/sdk";
import { Hex, decodeEventLog, formatUnits, parseAbiItem } from "viem";


const transferEvent = parseAbiItem(
  "event Transfer(address indexed from, address indexed to, uint256 value)",
);


export default worker({
  async launch(eventPayload: Record<string, unknown>, { userdata }: WorkerContext) {
    console.log("Worker launched!", eventPayload, userdata);
  },


  async fetch(request: Request, { userdata }: WorkerContext) {
    return {
      message: "Hello from nXCC worker!",
      path: new URL(request.url).pathname,
    };
  },


  async handleTransfer(eventPayload: Record<string, unknown>, { userdata }: WorkerContext) {
    try {
      const {
        args: { from, to, value },
      } = decodeEventLog({
        abi: [transferEvent],
        topics: eventPayload.topics as [signature: Hex, ...args: Hex[]],
        data: eventPayload.data as Hex,
      });


      const transactionHash = eventPayload.transaction_hash as Hex;
      const blockNumber = eventPayload.block_number as number;


      console.log(`➡️ Transfer detected in block ${blockNumber}:`);
      console.log(`  From: ${from}`);
      console.log(`  To: ${to}`);
      console.log(`  Amount: ${formatUnits(value, 6)} USDC`);
      console.log(`  Tx: ${transactionHash}`);
    } catch (error) {
      console.error("Failed to decode transfer event", error, eventPayload);
    }
  },


  async tick(eventPayload: Record<string, unknown>, { userdata }: WorkerContext) {
    const timestamp = new Date().toISOString();
    console.log(`Scheduled tick executed at ${timestamp}`);


    // Example: Perform periodic tasks like data aggregation, monitoring, etc.
    const status = {
      timestamp,
      message: "Scheduled event fired successfully",
      eventPayload,
      userdata,
    };


    console.log("Tick event processed:", status);
    return status;
  },
});

This scaffold includes handlers for common trigger types:

  • launch runs once when the worker is deployed and is perfect for bootstrap logic.
  • fetch handles HTTP requests and generic invocations routed through the runtime.
  • handleTransfer shows how to respond to token transfer events with decoded payloads.
  • tick demonstrates scheduled jobs for periodic background work.

Build and deploy it:

# Build the TypeScript worker
npm run build


# Deploy to your local node
nxcc worker deploy --bundle workers/manifest.template.json --rpc-url http://localhost:6922

Your worker is now running!

Core Concepts

Section titled “Core Concepts”

Workers: JavaScript/TypeScript code that runs in secure environments and can:

  • React to blockchain events across 400+ chains
  • Handle HTTP requests
  • Access secrets and make API calls
  • Send transactions

Secure by Default: All code runs in Trusted Execution Environments (TEEs) with memory encryption and remote attestation.

Multi-Chain Native: Built-in support for Ethereum, Polygon, Arbitrum, and 400+ other EVM chains.

Next Steps

Section titled “Next Steps”

Follow our progressive tutorial series:

  1. Blockchain Events - Build workers that react to on-chain events across multiple blockchains

  2. Identities & Policies - Add secure credential management and access controls

Reference Docs

Section titled “Reference Docs”

Need Help?

Section titled “Need Help?”

Ready to build the future of cross-chain applications? Let’s go! 🚀