@golem-sdk/golem-js

Golem JavaScript API

Table of contents

• Golem JavaScript API
  • Table of contents
  • What's Golem and golem-js?
  • Golem application development
    • Installation
    • Building
    • Usage
      • Node.js context
      • Web Browser context
    • Testing
    • Running unit tests
    • Running E2E tests
      • Prerequisites
      • Test Environment Preparation
        • Build Docker Containers
        • Start Docker Containers
        • Fund the Requestor
        • Install and Build the SDK
      • Execute the E2E Tests
      • Execute the cypress Tests
    • Contributing
  • Controlling interactions and costs
    • Mid-agreement payments to the Providers for used resources
    • Limit price limits to filter out offers that are too expensive
    • Work with reliable providers
  • See also

What's Golem and golem-js?

The Golem Network fosters a global group of creators building ambitious software solutions that will shape the technological landscape of future generations by accessing computing resources across the platform. Golem Network is an accessible, reliable, open access and censorship-resistant protocol, democratizing access to digital resources and connecting users through a flexible, open-source platform.

@golem-sdk/golem-js is the JavaScript API that allows developers to connect to their Golem nodes and manage their distributed, computational loads through Golem Network.

Golem application development

For a detailed introduction to using Golem and @golem-sdk/golem-js to run your tasks on Golem please consult our quickstart section.

Installation

@golem-sdk/golem-js is available as a NPM package.

You can install it through npm:

npm install @golem-sdk/golem-js

or by yarn:

yarn add @golem-sdk/golem-js

Building

To build a library available to the NodeJS environment:

npm run build
# or
yarn build

This will generate production code in the dist/ directory ready to be used in your nodejs or browser applications.

Usage

Hello World

import { TaskExecutor } from "@golem-sdk/golem-js";

(async function main() {
  const executor = await TaskExecutor.create("9a3b5d67b0b27746283cb5f287c13eab1beaa12d92a9f536b747c7ae");
  await executor.run(async (ctx) => console.log(await ctx.run("echo 'Hello World'")).stdout);
  await executor.shutdown();
})();

Node.js context

Web Browser context

For more detailed usage examples and tutorials, see the Java Script API section of the Golem Network Docs

Testing

Running unit tests

To run unit tests, you can simply execute the command:

npm run test:unit
# or
yarn test:unit

Running E2E tests

Both test cases for the NodeJS environment and the browser (cypress) require preparation of a test environment of the Golem Network with Providers and all the necessary infrastructure.

Prerequisites

1. Ensure you have docker and docker-compose installed in your system.
2. Your Linux environment should have nested virtualization enabled.

Test Environment Preparation

Follow these steps to prepare your test environment:

Build Docker Containers

First, build the Docker containers using the docker-compose.yml file located under tests/docker.

Execute this command to build the Docker containers:

docker-compose -f tests/docker/docker-compose.yml build

Start Docker Containers

Then, launch the Docker containers you've just built using the same docker-compose.yml file.

Execute this command to start the Docker containers:

docker-compose -f tests/docker/docker-compose.yml down && docker-compose -f tests/docker/docker-compose.yml up -d

Fund the Requestor

The next step is to fund the requestor.

docker exec -t docker_requestor_1 /bin/sh -c "/golem-js/tests/docker/fundRequestor.sh"

Install and Build the SDK

Finally, install and build the golem-js SDK in the Docker container

Run this chain of commands to install and build the SDK and prepare cypress.

docker exec -t docker_requestor_1 /bin/sh -c "cd /golem-js && npm i && npm run build && ./node_modules/.bin/cypress install"

Execute the E2E Tests

With your test environment set up, you can now initiate the E2E tests. Run the following command to start:

docker exec -t docker_requestor_1 /bin/sh -c "cd /golem-js && npm run test:e2e"

Execute the cypress Tests

First make sure that the webserver that's used for testing is running, by running the command

docker exec -t -d docker_requestor_1 /bin/sh -c "cd /golem-js/examples/web && node app.mjs"

Now you're ready to start the cypress tests by running the command

docker exec -t docker_requestor_1 /bin/sh -c "cd /golem-js && npm run test:cypress -- --browser chromium"

Contributing

It is recommended to run unit tests and static code analysis before committing changes.

yarn lint
# and
yarn format

Controlling interactions and costs

The Golem Network provides an open marketplace where anyone can join as a Provider and supply the network with their computing power. In return for their service, they are billing Requestors (users of this SDK) according to the pricing that they define.

As a Requestor, you might want to:

• control the limit price so that you're not going to over-spend your funds
• control the interactions with the providers if you have a list of the ones which you like or the ones which you would like to avoid

To make this easy, we provided you with a set of predefined market proposal filters, which you can combine to implement your own market strategy (described below).

Mid-agreement payments to the Providers for used resources

When you obtain resources from the Provider and start using them, the billing cycle will start immediately. Since reliable service and payments are important for all actors in the Golem Network, the SDK makes use of the mid-agreement payments model and implements best practices for the market, which include:

• responding and accepting debit notes for activities that last longer than 30 minutes
• issuing mid-agreement payments (pay-as-you-go)

By default, the SDK will:

• accept debit notes sent by the Providers each 2 minutes
• issue a mid-agreement payment each 12 hours

You can learn more about the mid-agreement and other payment models from the official docs.

These values are defaults and can be influenced by the following settings:

• DemandOptions.expirationSec
• DemandOptions.debitNotesAcceptanceTimeoutSec
• DemandOptions.midAgreementPaymentTimeoutSec

If you're using TaskExecutor to run tasks on Golem, you can pass them as part of the configuration object accepted by TaskExecutor.create. Consult JS API reference for details.

Limit price limits to filter out offers that are too expensive

import { TaskExecutor, ProposalFilters } from "@golem-sdk/golem-js";

const executor = await TaskExecutor.create({
  // What do you want to run
  package: "golem/alpine:3.18.2",

  // How much you wish to spend
  budget: 0.5,
  proposalFilter: ProposalFilters.limitPriceFilter({
    start: 1,
    cpuPerSec: 1 / 3600,
    envPerSec: 1 / 3600,
  }),

  // Where you want to spend
  payment: {
    network: "polygon",
  },
});

To learn more about other filters, please check the API reference of the market/strategy module

Work with reliable providers

The getHealthyProvidersWhiteList helper will provide you with a list of Provider ID's that were checked with basic health-checks. Using this whitelist will increase the chance of working with a reliable provider. Please note, that you can also build up your own list of favourite providers and use it in a similar fashion.

import { TaskExecutor, ProposalFilters, MarketHelpers } from "@golem-sdk/golem-js";

// Prepare the price filter
const acceptablePrice = ProposalFilters.limitPriceFilter({
  start: 1,
  cpuPerSec: 1 / 3600,
  envPerSec: 1 / 3600,
});

// Collect the whitelist
const verifiedProviders = await MarketHelpers.getHealthyProvidersWhiteList();

// Prepare the whitelist filter
const whiteList = ProposalFilters.whiteListProposalIdsFilter(verifiedProviders);

const executor = await TaskExecutor.create({
  // What do you want to run
  package: "golem/alpine:3.18.2",

  // How much you wish to spend
  budget: 0.5,
  proposalFilter: async (proposal) => (await acceptablePrice(proposal)) && (await whiteList(proposal)),

  // Where you want to spend
  payment: {
    network: "polygon",
  },
});

See also

• Golem, a global, open-source, decentralized supercomputer that anyone can access.
• Learn what you need to know to set up your Golem requestor node:
  • Requestor development: a quick primer
  • Quick start
• Have a look at the most important concepts behind any Golem application: Golem application fundamentals
• Learn about preparing your own Docker-like images for the VM runtime
• Write your own app with JavaScript API