Golem Network manual for Degen Hack hackathon participants.

Golem Network is a P2P network that consists of many nodes. Each node is a system with a Yagna service running on it. The nodes that offer their resources to others are called providers. The nodes that rent resources are called requestors.

Yagna is a service that enables the user to interact with the network. In practice, the user creates a requestor script utilizing one of the available Golem SDKs. The script is used to define what resources are needed and what should be run on the provider's node, and to orchestrate all activities.

For the resources consumed on the Golem Network, you pay in GLM. GLM is an ERC-20 utility token. When you run Yagna for the first time on your computer, it will create a wallet for you. It will have an address on supported blockchains and you can export the wallet address to an external application.

When developing your code on the Golem Network you do not necessarily need to acquire GLM tokens. You can use the testnet network, which while consisting of providers of some limited performance allows you to pay in tGLM available for free. Once your code is ready for production, you switch to mainnet, where you need true GLM.

curl -sSf https://join.golem.network/as-requestor | YA_INSTALLER_CORE=v0.13.2 bash -

To start the yagna service, open a terminal and type:

yagna service run

Requesting tasks on the Golem Network requires GLM tokens. When you use testnet you use test GLM. Open another terminal and run the following command:

yagna payment fund

It will top up your account with test GLM tokens. These tokens can only be used on the testnet.

The steps below are not part of the installation process, however they will be useful at later stages:

The app-key purpose is to allow your requestor script to securely access and interact with the Yagna API Open a terminal (command line window) and create the app-key named requestor:

yagna app-key create requestor

After running this command, make sure to copy its output. This output is your app-key, which you will need to use for setting up the YAGNA_APPKEY environment variable.

export YAGNA_APPKEY=<32-char>

Note: If you need to find your key value again at any time, you can retrieve it using the following command:

yagna app-key list

and locate the desired value in the 'key' column for copying.

To find out where to transfer funds for your Yagna wallet, you can easily obtain the address of your wallet with this command:

yagna payment accounts

This command is not only used to find your wallet address, but it also serves as the unique identifier of your node within the network.

yagna payment status --network=holesky --driver=erc20

To create a backup of your Golem wallet, export the keystore with:

yagna id export --file-path=./key.json

This will generate a file named key.json in the directory where the command was run. This file contains the private key of your Golem wallet.

Create a new Node.js project and install the Golem SDK by entering the following commands in your terminal:

npm init @golem-sdk/golem-app@latest my-golem-app

Make sure you have created an app-key and exported its value as YAGNA_APPKEY.

In src folder you will find a reaquestor script. This script sets up a task to execute node -v on the Golem Network and displays the result in your terminal.

import "dotenv/config";
import { GolemNetwork, MarketOrderSpec } from "@golem-sdk/golem-js";

(async () => {
  // Initialize a new GolemNetwork instance,
  // you can also pass additional options here like logger or api key
  const glm = new GolemNetwork();

  try {
    // Connect to the Golem network using the Yagna node
    await glm.connect();

    // Define the specifications for a market order
    const order: MarketOrderSpec = {
      demand: {
        // Specify workload options such as image tag from golem registry
        // or other criteria for rented machines
        workload: { imageTag: "golem/alpine:latest" },
      },
      market: {
        // Specify the rental time (15 minutes)
        rentHours: 15 / 60,
        pricing: {
          // Pricing model set to linear
          model: "linear",
          // Set the maximum starting price
          maxStartPrice: 0.5,
          // Set the maximum price per CPU per hour
          maxCpuPerHourPrice: 1.0,
          // Set the maximum price per environment per hour
          maxEnvPerHourPrice: 0.5,
        },
      },
    };

    // Create a pool that can handle up to 3 rentals simultaneously
    const pool = await glm.manyOf({
      poolSize: 3,
      order,
    });

    console.log("Starting work on Golem!");

    console.log("Running three different commands on a pool of three rented machines");

    // Execute three tasks concurrently, each on a different rented machine in the pool
    await Promise.allSettled([
      pool.withRental(async (rental) =>
        rental
          .getExeUnit()
          .then((exe) => exe.run(`echo Hello Golem from provider ${exe.provider.name} 😻`))
          .then((res) => console.log(res.stdout))
          .catch((err) => console.error(`Something went wrong:`, err)),
      ),
      pool.withRental(async (rental) =>
        rental
          .getExeUnit()
          .then((exe) => exe.run(`echo Hello Golem from provider ${exe.provider.name} 🤠`))
          .then((res) => console.log(res.stdout))
          .catch((err) => console.error(`Something went wrong:`, err)),
      ),
      pool.withRental(async (rental) =>
        rental
          .getExeUnit()
          .then((exe) => exe.run(`echo Hello Golem from provider ${exe.provider.name} 👻`))
          .then((res) => console.log(res.stdout))
          .catch((err) => console.error(`Something went wrong:`, err)),
      ),
    ]);

    console.log("Running a command on a single rented machine");

    // Acquire a single rental, execute a command, and log the output or an error
    const singleRental = await glm.oneOf({ order });
    await singleRental
      .getExeUnit()
      .then((exe) => exe.run(`echo Hello Golem from provider ${exe.provider.name} 👽`))
      .then((res) => console.log(res.stdout))
      .catch((err) => console.error(`Something went wrong:`, err));
  } catch (err) {
    console.error("Something went wrong:", err);
  } finally {
    // Disconnect from the Golem Network.
    // This will clear the rental pools and finalize and pay all rentals that were created within the Golem Network
    await glm.disconnect();
  }
})().catch(console.error);

To execute the script, run:

npm start

You can find an explanation of the structure of the typical requestor script here.

The standard quickstart example has been altered with the following modifications:

• payment: { network: 'holesky', }, indicates that we would like to run the task on the testnet.

• it also utilizes a unique app-key stored in the YAGNA_APPKEY variable.

The JS SDK consists of the following components:

@golem-sdk/golem-js - a JavaScript API for developers allowing them to connect to their Golem nodes and manage their distributed, computational loads through Golem Network.

GitHub Repo Documentation

@golem-sdk/cli - a companion tool for the Golem SDK. It facilitates a fast start with Golem Network by creating a new template for new applications, assisting with manifest creation for outbound networking, and lets you interactively test your custom image in the fastest way possible all without coding.

GitHub Repo Documentation

@golem-sdk/react - a set of React hooks for working with the Golem Network.

GitHub Repo Documentation

Documentation

Examples

API Reference

tesseract-ocr-golem - a golem-js based library for running Tesseract OCR jobs on the Golem Network.

GitHub Repo

react-image-classifier - a reference implementation of a React app using Golem underneath

GitHub Repo

music-on-golem - a reference implementation of a next.js app that uses Golem to generate music. The project contains everything you'd find in a typical full-stack application, including a database, design system, authentication, and more.

GitHub Repo

Yagna - the foundational service that allows users to connect with and interact with the Golem Network.

Gvmkit-build - a tool designed to create custom images for virtual machines on provider nodes within the Golem Network. It specifically converts Dockerfiles into Golem-compatible VM images, known as GVMI.

You can find a list of available instructions for Golem tools: yagna and gvmkit-build.

Golem Registry - a repository of already built images that can be utilized by Golem Network users is here.