UBNet Browser SDK

The browser SDK is loaded from /ubnet.js. The loader retrieves the tracked runtime modules under /ubnet/ and exposes window.UBNet.

Load and create a client

<script src="https://my.eth-ub.net/ubnet.js"></script>
<script>
  const ubnet = window.UBNet.createClient({
    apiBase: "https://my.eth-ub.net",
    walletProvider: window.ethereum
  });
</script>

apiBase may be an absolute HTTP(S) URL, a same-origin path, or empty for the current origin. Cross-origin sites still require backend CORS permission.

Global SDK

Client object

{
  apiBase,
  api,
  cache,
  posts,
  lists,
  profiles,
  uploads,
  chats,
  nfts,
  reservedSubdomains,
  domainRegistration,
  support,
  events,
  configure,
  version,
  versions
}

Low-level transport and cache

Posts

Validated category input

function normalizePostCategory(raw) {
  const clean = String(raw || "").trim().toLowerCase();
  if (!/^[a-z0-9][a-z0-9_-]{0,119}$/.test(clean)) {
    throw new Error("Choose a category using lowercase letters, numbers, dashes, or underscores.");
  }
  return { name: clean };
}

async function createTextPost(ubnet, wallet, form) {
  const category = normalizePostCategory(form.category.value);
  const content = form.content.value.trim();
  if (!content) throw new Error("Write some content before posting.");

  return ubnet.posts.create(wallet, {
    categories: [category],
    content,
    publicationStatus: form.visibility.value === "private" ? "offline" : "published"
  });
}

No category fallback exists. Omitting categories throws post_categories_required. Post edits reject category changes with post_categories_immutable.

Post with URL or CID media

await ubnet.posts.create(wallet, {
  categories: [{ name: "project-update" }],
  content: "Read the full article.",
  mediaValue: "https://example.com/article"
});

await ubnet.posts.create(wallet, {
  categories: [{ name: "audio" }],
  content: "Listen to the full recording.",
  mediaValue: resolved.cid,
  thumbnailUrl: customThumbnail,
  cidMetadata: resolved
});

cidMetadata should identify audio, video, or image content. An explicit thumbnailUrl overrides a thumbnail included in the CID metadata. Post edits accept content and visibility only.

Lists

Cursor pagination and infinite scrolling

const postPager = {
  cursor: null,
  loading: false,
  finished: false,
  seen: new Set(),
  controller: null
};

function postId(post) {
  return String(post.root_id || post.latest_id || post.spasm_id || "");
}

async function loadMorePosts(filters = {}) {
  if (postPager.loading || postPager.finished) return [];
  postPager.loading = true;
  const requestedCursor = postPager.cursor;
  const controller = new AbortController();
  postPager.controller = controller;

  try {
    const page = await ubnet.api.request(
      "/api/posts/feed",
      { signal: controller.signal },
      { query: { ...filters, limit: 10, cursor: requestedCursor } }
    );

    const added = [];
    for (const post of page.feed || []) {
      const id = postId(post);
      if (!id || postPager.seen.has(id)) continue;
      postPager.seen.add(id);
      added.push(post);
    }

    const nextCursor = page.next_cursor || null;
    const madeProgress = added.length > 0 && nextCursor !== requestedCursor;
    postPager.finished = !madeProgress || !nextCursor || page.has_more === false;
    postPager.cursor = postPager.finished ? null : nextCursor;
    return added;
  } catch (error) {
    if (error?.name === "AbortError") return [];
    throw error;
  } finally {
    if (postPager.controller === controller) postPager.controller = null;
    postPager.loading = false;
  }
}

IntersectionObserver with manual fallback

const sentinel = document.querySelector("#posts-sentinel");
const loadButton = document.querySelector("#load-more-posts");

async function appendNextPostPage() {
  const posts = await loadMorePosts({ keyword: searchInput.value });
  renderPosts(posts);
  loadButton.disabled = postPager.loading || postPager.finished;
}

const observer = new IntersectionObserver((entries) => {
  if (entries.some((entry) => entry.isIntersecting)) {
    appendNextPostPage().catch(showError);
  }
}, { rootMargin: "520px 0px" });

if (sentinel) observer.observe(sentinel);
loadButton?.addEventListener("click", () => {
  appendNextPostPage().catch(showError);
});

Keep the button visible for retry and keyboard accessibility even when automatic loading is enabled.

Profiles and follows

Follow button must wait for confirmed state

async function loadConfirmedFollowingSet(viewerWallet) {
  let cursor = null;
  const followed = new Set();

  for (let page = 0; page < 10; page += 1) {
    const result = await ubnet.profiles.following(viewerWallet, { limit: 200, cursor });
    for (const row of result.following || []) {
      if (row.following_wallet) followed.add(row.following_wallet.toLowerCase());
    }
    cursor = result.next_cursor || null;
    if (!cursor || result.has_more === false) {
      return { confirmed: true, followed };
    }
  }

  return { confirmed: false, followed };
}

function followButtonState(targetWallet, confirmedState) {
  const target = targetWallet.toLowerCase();
  if (confirmedState.followed.has(target)) return "following";
  if (!confirmedState.confirmed) return "checking";
  return "not-following";
}

// Only show Follow when state === "not-following".
// Use a disabled Checking button or hide the control while state === "checking".

Named profiles

await ubnet.profiles.save(wallet, {
  profile_name: "business-profile",
  display_name: "Acme Corporation",
  bio: "Business profile"
});

const business = await ubnet.profiles.get(wallet, {
  profile: "business-profile"
});

Profile names are normalized to lowercase, must start with a letter or number, may contain lowercase letters, numbers, dashes, and underscores, and may be at most 64 characters.

Uploads

Chats and messaging v2

The UBNet web client implements its crypto layer in frontend/src/services/crypto.ts, with usage references in frontend/src/components/MessagingKeyControls.tsx, frontend/src/services/messagingKeySync.ts, and frontend/src/pages/ChatPage.tsx. The helper names below must come from your compatible crypto module; they are not methods on window.UBNet.

Wait until messaging is indexed

async function waitForIndexedMessagingKey(
  ubnet,
  wallet,
  expectedPublicKey,
  { timeoutMs = 60000, intervalMs = 1000, requireBackup = true } = {}
) {
  const deadline = Date.now() + timeoutMs;

  while (Date.now() <= deadline) {
    const profile = await ubnet.chats.messagingProfile(wallet);
    if ((profile.encryption_public_key || "") !== expectedPublicKey) {
      await new Promise((resolve) => setTimeout(resolve, intervalMs));
      continue;
    }

    if (!requireBackup) return;
    const backup = await ubnet.chats.messagingKeyBackup(wallet);
    if ((backup.messaging_key_backup?.public_key || "") === expectedPublicKey) return;
    await new Promise((resolve) => setTimeout(resolve, intervalMs));
  }

  throw new Error("Messaging key event was accepted but not indexed in time.");
}

One-time setup: enable messaging

// These helper names match frontend/src/services/crypto.ts.
const publicKey = await generateMessagingKeyPair(wallet);
const recoveryBackup = await createWalletRecoveryMessagingKeyBackup(wallet, window.ethereum);

await ubnet.chats.enableMessaging(wallet, {
  encryption_public_key: publicKey,
  messaging_key_backup: recoveryBackup
});

await waitForIndexedMessagingKey(ubnet, wallet, publicKey);
clearPendingMessagingKeyMaterial(wallet);

Do not send the private JWK to UBNet. enableMessaging() receives only the public key and already protected recovery data.

Restore and unlock on another browser

const backupResponse = await ubnet.chats.messagingKeyBackup(wallet);
const backup = backupResponse.messaging_key_backup;
if (!backup) throw new Error("No messaging recovery backup exists.");

await restoreMessagingKeyFromWalletRecoveryBackup(wallet, backup, window.ethereum);

if (!await hasLocalMessagingPrivateKey(wallet)) {
  throw new Error("Restore or replace the messaging key on this browser.");
}
if (!isMessagingUnlocked(wallet)) {
  await unlockMessagingKey(wallet, window.ethereum);
}

Send a direct encrypted message

const recipientWallet = "0x...";
const { chat_id } = await ubnet.chats.directId(wallet, recipientWallet);
const recipient = await ubnet.chats.messagingProfile(recipientWallet);

if (!recipient.messaging_enabled || !recipient.encryption_public_key) {
  throw new Error("Recipient has not enabled encrypted messaging.");
}

const senderPublicKey = await getLocalMessagingPublicKey(wallet);
const encrypted = await encryptDmMessage(
  wallet,
  recipient.encryption_public_key,
  "Hello"
);

await ubnet.chats.send(wallet, {
  messaging_protocol: "ubnet-e2ee-v2",
  is_group: false,
  chat_id,
  participants: [wallet, recipientWallet],
  sender_public_key: senderPublicKey,
  recipient_public_key: recipient.encryption_public_key,
  ciphertext: encrypted.ciphertext,
  iv: encrypted.iv,
  encoding: "aes-gcm-v2",
  encrypted: true
});

Create a group and send a group message

const participants = [wallet, "0x...", "0x..."];
const chatId = `group:${crypto.randomUUID()}`;

await ubnet.chats.createGroup(wallet, {
  chat_id: chatId,
  title: "Project group",
  participants
});

const recipients = await Promise.all(participants.map(async (participantWallet) => {
  if (participantWallet.toLowerCase() === wallet.toLowerCase()) {
    return { wallet: participantWallet, publicKey: await getLocalMessagingPublicKey(wallet) };
  }
  const profile = await ubnet.chats.messagingProfile(participantWallet);
  return { wallet: participantWallet, publicKey: profile.encryption_public_key };
}));

if (recipients.some((recipient) => !recipient.publicKey)) {
  throw new Error("Every group member must enable encrypted messaging.");
}

const senderPublicKey = await getLocalMessagingPublicKey(wallet);
const encrypted = await encryptGroupMessage(wallet, recipients, "Hello group");

await ubnet.chats.send(wallet, {
  messaging_protocol: "ubnet-e2ee-v2",
  is_group: true,
  chat_id: chatId,
  participants,
  sender_public_key: senderPublicKey,
  ciphertext: encrypted.ciphertext,
  iv: encrypted.iv,
  encoding: "group-aes-gcm-v2",
  encrypted_keys: encrypted.encrypted_keys,
  encrypted: true
});

Encrypt the group AES key separately for every intended reader, including the sender. Each encrypted_keys entry must contain wallet, ciphertext, iv, and encoding: "aes-key-wrap-ecdh-v2".

Read and decrypt messages

const page = await ubnet.chats.messages(chatId, wallet, { limit: 50, cursor: null });

for (const message of page.messages) {
  if (message.encoding === "aes-gcm-v2") {
    const otherPublicKey =
      message.sender_wallet.toLowerCase() === wallet.toLowerCase()
        ? message.recipient_public_key
        : message.sender_public_key;
    const plaintext = await decryptDmMessage(wallet, otherPublicKey, message.ciphertext, message.iv);
  }

  if (message.encoding === "group-aes-gcm-v2") {
    const plaintext = await decryptGroupMessage(
      wallet,
      message.sender_public_key,
      message.encrypted_keys,
      message.ciphertext,
      message.iv
    );
  }
}

Messaging calls

NFTs, names, support, and public events

Use ubnet.events.list({ category: "example-category", latest: true, wallet }) for filtered discovery. Supported query fields are limit, cursor, action, author, wallet, category, category_mode, schema_name, schema_version, post_type, source_instance_host, and latest=true.

Generated bundle output

Tracked SDK source modules live under frontend/public/ubnet/. The frontend build generates:

frontend/public/ubnet.bundle.js
frontend/public/sdk/v1/ubnet.bundle.js