Golem JavaScript API
Table of contents
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.end();
})();
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. Goth framework is used for this purpose.
To enable E2E testing, you need to ensure that python -m goth
is executable. Therefore, you must first install Goth according to the instructions described in the readme of the project.
NodeJS
npm run test:e2e
# or
yarn test:e2e
Cypress
npm run test:cypress
# or
yarn test:cypress
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. For example:
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
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:
- 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