Server-Hosted Skynet Usage

Overview

Most of this documentation assumes you're interacting with Skynet from a client-side, browser context, using skynet-nodejs. This guide will walk you through some of the main considerations of interacting with Skynet from a server-side context.
If you are working with us as a partner, please reach out to [email protected] (Discord dghelm#8125) for a promo code for a free elevated tier account.
If you're migrating from siasky.net, you might start with reading Moving Off of Siasky.net.
Previous versions of this page recommended mixing skynet-js and skynet-nodejs usage in a single project. We now suggest developers only use one or the other, depending on how their code will be run.

Skynet SDK Capabilities

Currently, only our NodeJS SDK has all the features addressed in this article.
SDK
Skyfile Upload
Skyfile Download
MySky + DACs
Large File Upload (tus)
Registry Access
Resolver Skylink Set
Portal Account
File Pinning
go-skynet
Looking to contribute? Many of these features are thin abstractions over our HTTP APIs. Take a look at open issues in the Python SDK and Go SDK.

File Uploads

skynet-js currently only supports browser uploads. You will want to upload files using one of our other SDK or CLI tools (ie @skynetlabs/skynet-nodejs).
The node SDK has been updated to support large file uploads in version 2.1.0. The tus protocol will automatically be used for any file >40MB.

File Persistence

In a browser context, cookies containing encrypted JWTs are used for linking file uploads to your portal account. This is needed for pinning files >90 days or accessing account-only portals.
If your upload method does not support cookies and your file needs to persist longer than 90 days, you will want to upload your file using a Skynet API Key or your encrypted JSON Web Token (located in the skynet-jwt cookie.

Using your Skynet API Key with skynet-nodejs

To use a Skynet API Key, you will specify a skynetApiKey when you initialize your client.
1
const { SkynetClient } = require('@skynetlabs/skynet-nodejs');
2
3
const client = new SkynetClient('https://skynetfree.net', {skynetApiKey: SKYNET_API_KEY});
Copied!

Obtaining your Skynet API Key

Private API keys for interacting with portals will be officially released in April 2022, and using JWTs will be deprecated.
Currently, no UI exists in the portal dashboard for creating new API keys for your account. If you wish to manually create one, visit your account dashboard page, and run the following in your browser's developer tools console:
1
fetch("/api/user/apikeys", {method: "POST", headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({public:"false"})}).then((r) => r.json()).then(console.log)
Copied!
Then, copy the key field from the response. You can generate additional Skynet API Keys, but you cannot view this key again.
Access to this key allows full access to your portal account. It should be kept private. Do not share it or commit it to your repo. This feature is still experimental and the scope of permissions granted may change before a full release.

Using your JWT with skynet-nodejs

To use your account JWT, you will specify a customCookie when you initialize your client.
1
const { SkynetClient } = require('@skynetlabs/skynet-nodejs');
2
3
const client = new SkynetClient('https://siasky.net', {customCookie: SKYNET_JWT});
Copied!
Do not commit the value of SKYNET_JWT to the repo and be sure the value is formatred to be begins with skynet-jwt=.
We do not suggest trying to set customCookie in skynet-js since browsers will not include this cookie header in browser requests.

Obtaining your JWT

Currently, we don't yet support API keys for accounts, so you need to obtain the value for your JSON web token.
  1. 1.
    First, login to your account at https://account.siasky.net/
  2. 2.
    Press F12 to open your developer tools, select the “Application” tab
  3. 3.
    In the bar at left, under “Storage”, find “account.siasky.net” under “Cookies”
  4. 4.
    Locate the item named “skynet-jwt” and copy-paste its value, but make sure the string is prefixed with skynet-jwt=.
To pin a skylink, first initialize your Skynet Client to use your JWT. After initializing the client with a custom cookie, call client.pinSkylink(skylink);

Cookie / JWT Expiration

JWTs expire after 720 hours and we have no tooling to detect if your JWT is expired. We don’t currently support API Keys, so please reach out to our team if you want a longer expiration time on your JWT.

Resolver Skylink Creation

One common use-case for server-side applications is to upload files that are pointed to using a resolver skylink, so that the data can be consumed using a consistent URL.
Here is a code example:
1
const { SkynetClient, genKeyPairFromSeed } = require("@skynetlabs/skynet-nodejs");
2
const { SKYNET_JWT, SECRET_SEED } = require './consts';
3
4
const portal = 'https://siasky.net';
5
const client = new SkynetClient(portal, { customCookie: SKYNET_JWT })
6
7
// Setup Keys for Read/Write of Mutable Data
8
const { privateKey, publicKey } = genKeyPairFromSeed( SECRET_SEED );
9
const dataKey = 'nameForRegistryEntry';
10
11
// skylink to point to with resolver skylink
12
const skylink = "sia://MABdWWku6YETM2zooGCjQi26Rs4a6Hb74q26i-vMMcximQ";
13
14
// Set Registry Entry to point at our Skylink
15
await client.db.setDataLink(privateKey, dataKey, skylink);
16
17
// Get the resolver skylink that represents the registry entry
18
const resolverSkylink = await client.registry.getEntryLink(publicKey, dataKey);
19
20
// Get the URL for the resolver skylink, at `siasky.net`
21
const resolverSkylinkUrl = await client.getSkylinkUrl(resolverSkylink);
Copied!