react-native-sia

The Sia Storage SDK for React Native. Upload, download, and share encrypted, erasure-coded data on the Sia network from iOS and Android.

Install

npm install react-native-sia

iOS — install the pod:

cd ios && pod install

Android — nothing extra; the Gradle plugin links the library automatically.

Quick start

import {
  initSia,
  AppKey,
  Builder,
  generateRecoveryPhrase,
} from 'react-native-sia'
import { Linking } from 'react-native'

await initSia()

// A 32-byte identifier unique to your app. Not secret, but should be stable.
const appId = new Uint8Array(32).fill(2).buffer

const builder = new Builder('https://sia.storage', {
  id: appId,
  name: 'My App',
  description: 'An app on Sia',
  serviceUrl: 'https://myapp.com',
  callbackUrl: 'myapp://callback',
  logoUrl: 'https://myapp.com/logo.png',
})

const phrase = generateRecoveryPhrase()
await builder.requestConnection()
await Linking.openURL(builder.responseUrl())  // user approves in the browser
await builder.waitForApproval()
const sdk = await builder.register(phrase)

// Persist the app key to the Keychain / Keystore.
const appKeyBytes = sdk.appKey().export_()    // 32 bytes

Reconnecting a returning user:

const builder = new Builder(indexerUrl, appMeta)
const sdk = await builder.connected(new AppKey(savedAppKeyBytes))
if (!sdk) {
  // app key isn't authorized for this indexer — restart the approval flow.
}

Upload

sdk.upload consumes a Reader — an object with read(): Promise<ArrayBuffer> that yields chunks and returns an empty buffer at EOF.

import { PinnedObject } from 'react-native-sia'

function bufferReader(data: ArrayBuffer, chunkSize = 256 * 1024) {
  let offset = 0
  return {
    async read() {
      if (offset >= data.byteLength) return new ArrayBuffer(0)
      const end = Math.min(offset + chunkSize, data.byteLength)
      const chunk = data.slice(offset, end)
      offset = end
      return chunk
    },
  }
}

const object = await sdk.upload(new PinnedObject(), bufferReader(data), {})
await sdk.pinObject(object)

object.id() is the content hash. object.size(), object.encodedSize(), object.slabs(), and object.metadata() round out what you can read back.

For many small files, share slabs via uploadPacked:

const packed = await sdk.uploadPacked({})
await packed.add(bufferReader(fileA))
await packed.add(bufferReader(fileB))
for (const obj of await packed.finalize()) await sdk.pinObject(obj)

Download

const object = await sdk.object(key)
const download = sdk.download(object, {})

const chunks: ArrayBuffer[] = []
while (true) {
  const chunk = await download.read()
  if (chunk.byteLength === 0) break
  chunks.push(chunk)
}

Share

const validUntil = new Date(Date.now() + 7 * 24 * 60 * 60 * 1000)
const url = sdk.shareObject(object, validUntil)

// On the receiving side:
const shared = await sdk.sharedObject(url)
const dl = sdk.download(shared, {})

API

Top-level

initSia()	Initialize. Call once before anything else.
generateRecoveryPhrase()	New 12-word BIP-39 phrase.
validateRecoveryPhrase(phrase)	Throws on invalid.
encodedSize(size, dataShards, parityShards)	Encoded size after erasure coding.
setLogger(logger, level)	Receive SDK logs ('trace' | 'debug' | 'info' | 'warn' | 'error').

Builder

new Builder(indexerUrl, appMeta) — appMeta is { id: ArrayBuffer (32 bytes), name, description, serviceUrl, logoUrl?, callbackUrl? }.

connected(appKey)	Reconnect with a saved AppKey → Sdk | null.
requestConnection()	Start the approval flow.
responseUrl()	URL to show the user.
waitForApproval()	Resolves once the user approves.
register(mnemonic)	Finish onboarding with a recovery phrase → Sdk.

Sdk

Returned from Builder.register() or Builder.connected().

appKey()	The AppKey for this session.
upload(object, reader, options)	Upload from a Reader. Pass new PinnedObject() for new uploads, or an existing object to append.
uploadPacked(options)	PackedUpload for batching small files into shared slabs.
download(object, options)	Returns a Download.
object(key)	Fetch metadata for an object.
pinObject(object) / deleteObject(key)	Pin / delete.
updateObjectMetadata(object)	Push local metadata changes to the indexer.
objectEvents(cursor, limit)	Paginated object change feed.
shareObject(object, validUntil) / sharedObject(url)	Create / consume share URLs.
hosts()	List usable hosts.
slab(id)	Slab metadata.
pruneSlabs()	Unpin slabs no longer referenced by any object.
account()	Account info.

AppKey

new AppKey(key) — 32-byte ArrayBuffer. Get it via sdk.appKey().export_() and store securely (Keychain / Keystore).

export_() · sign(message) · publicKey() · verifySignature(message, signature)

PinnedObject

new PinnedObject() for new uploads, sdk.object(key) to load one, or PinnedObject.open(appKey, sealed) to unseal one.

id() · size() · encodedSize() · slabs() · metadata() · updateMetadata(bytes) · createdAt() · updatedAt() · seal(appKey)

Download

From sdk.download(). read() returns the next chunk; an empty ArrayBuffer signals EOF.

read() · cancel()

PackedUpload

From sdk.uploadPacked().

add(reader) · finalize() · cancel() · remaining() · length() · slabs()

Reader

The callback interface passed to upload and PackedUpload.add. Implement read(): Promise<ArrayBuffer> — return chunks until you're done, then return an empty ArrayBuffer.

License

MIT