Blok SDK

A TypeScript SDK for building decentralized applications with blockchain-backed profiles, file storage, and social features.

Features

• 🔐 Wallet Management - Easy MetaMask integration
• 👤 Decentralized Profiles - Create and manage on-chain user profiles
• 📁 File Storage - Upload files to IPFS with blockchain verification
• 💬 Social Posts - Create, update, and delete posts with IPFS + blockchain
• ⛓️ Blockchain Integration - All data secured on-chain with smart contracts

Installation

npm install @dot-blok/sdk

Quick Start

import { BlokClient } from '@dot-blok/sdk';

// Initialize the SDK
const blok = new BlokClient({
  apiKey: 'your-api-key'
});

// Connect wallet
await blok.connectWallet();

// Create a profile
const profile = await blok.profile.create({
  handle: 'myusername',
  displayName: 'My Name',
  bio: 'Hello world!',
  avatar: avatarFile, // File object
  twitter: '@myhandle',
  github: 'myusername',
  website: 'https://example.com'
});

API Reference

Wallet

connectWallet()

Connect to user's MetaMask wallet.

const { address, signer } = await blok.connectWallet();

disconnectWallet()

Disconnect the current wallet.

blok.disconnectWallet();

Profile

profile.get(address?: string)

Fetch a user profile by wallet address. If no address is provided, fetches the connected wallet's profile.

const profile = await blok.profile.get('0x123...');

Returns:

{
  handle: string;
  displayName: string;
  bio: string;
  avatar: string; // IPFS URL
  twitter: string;
  github: string;
  website: string;
  createdAt: number;
  walletAddress: string;
}

profile.create(data: CreateProfileInput)

Create a new on-chain profile.

const result = await blok.profile.create({
  handle: 'johndoe',           // required, 3-20 alphanumeric + underscore
  displayName: 'John Doe',     // optional
  bio: 'Web3 developer',       // optional
  avatar: file,                // optional File object
  twitter: '@johndoe',         // optional
  github: 'johndoe',           // optional
  website: 'https://john.dev'  // optional
});

Returns:

{
  success: boolean;
  txHash: string;
  profile: ProfileData;
}

profile.update(data: UpdateProfileInput)

Update an existing profile.

const result = await blok.profile.update({
  displayName: 'John D.',
  bio: 'Updated bio',
  avatar: newFile, // or existing IPFS CID string
  twitter: '@newhandle',
  github: 'newusername',
  website: 'https://newsite.com'
});

Files

files.getMyFiles()

Retrieve all files uploaded by the connected wallet.

const files = await blok.files.getMyFiles();

Returns:

Array<{
  id: number;
  cid: string;
  name: string;
  type: string;
  size: number | string;
  timestamp: number;
  deleted: boolean;
  owner: string;
}>

files.uploadFile(file: File)

Upload a file to IPFS and store metadata on-chain.

const result = await blok.files.uploadFile(file);

Returns:

{
  success: boolean;
  fileCid: string;
  metadataCid: string;
  fileUrl: string;
  txHash: string;
}

files.deleteFile(fileId: number)

Mark a file as deleted both in the database and on-chain.

const result = await blok.files.deleteFile(1);

Returns:

{
  success: boolean;
  txHash: string;
  message: string;
}

Social

social.getPosts()

Fetch all active posts.

const posts = await blok.social.getPosts();

social.createPost(content: string, imageFile?: File)

Create a new post with optional image.

const result = await blok.social.createPost(
  'Hello, Web3!',
  imageFile // optional
);

Returns:

{
  postCid: string;
  txHash: string;
}

social.updatePost(id: number, content: string, imageFile?: File)

Update an existing post.

const result = await blok.social.updatePost(
  1,
  'Updated content',
  newImageFile // optional
);

social.deletePost(id: number)

Delete a post.

const result = await blok.social.deletePost(1);

Returns:

{
  success: boolean;
  message: string;
}

Error Handling

All SDK methods throw errors that should be caught and handled:

try {
  await blok.profile.create({ handle: 'myhandle' });
} catch (error) {
  console.error('Profile creation failed:', error.message);
}

Requirements

• MetaMask browser extension or compatible Web3 wallet
• Active internet connection for IPFS uploads
• Valid API key from Blok platform
• Wallet with sufficient funds for gas fees

TypeScript Support

The SDK is written in TypeScript and includes full type definitions out of the box.

License

MIT

Support

For issues, questions, or feature requests, please visit our GitHub repository.