permanence-lib

permanence-lib is the JavaScript/TypeScript SDK for talking to Permanence from your own code.

1. Install

yarn add permanence-lib ethers
# or
npm install permanence-lib ethers

Requires ethers@^6.4.0.

2. Quick start (Node)

import { createChunkStorageClient } from 'permanence-lib';
import { JsonRpcProvider, Wallet } from 'ethers';

const provider = new JsonRpcProvider(process.env.RPC_URL!);
const wallet = new Wallet(process.env.PRIVATE_KEY!, provider);

const client = createChunkStorageClient({
  signer: wallet,
  contractAddress: process.env.CHUNK_STORAGE_ADDRESS!,
});

// upload a file/buffer
const { contentId } = await client.upload(Buffer.from('hello world'));

// later: download by contentId
const data = await client.download(contentId);
console.log(data.toString()); // "hello world"

Function names above are representative of the public API exposed by the library; check the actual exported functions for your installed version.

3. Main concepts

• Client – created with a signer and contract address; used for all operations.
• upload(input) – takes a Buffer, Uint8Array, or similar and returns { contentId, tx }.
• download(contentId) – returns the original bytes for a given content ID.
• Node helpers – if you prefer file-path based helpers, import from:
  • permanence-lib/storage-node
  • permanence-lib/upload-node

4. Minimal Node file upload example

import { readFileSync, writeFileSync } from 'fs';
import { createChunkStorageClient } from 'permanence-lib';
import { JsonRpcProvider, Wallet } from 'ethers';

async function main() {
  const provider = new JsonRpcProvider(process.env.RPC_URL!);
  const wallet = new Wallet(process.env.PRIVATE_KEY!, provider);

  const client = createChunkStorageClient({
    signer: wallet,
    contractAddress: process.env.CHUNK_STORAGE_ADDRESS!,
  });

  const fileBytes = readFileSync('photo.png');
  const { contentId } = await client.upload(fileBytes);
  console.log('Uploaded contentId:', contentId);

  const downloaded = await client.download(contentId);
  writeFileSync('photo-downloaded.png', downloaded);
}

main().catch(console.error);