Editing a Universal Profile

End-to-end tutorial for updating LSP-3 profile metadata with images, links, tags, and 3D avatars stored permanently on Cascade.

What you will build

A small web flow that, given a connected Universal Profile, uploads a profile image at multiple resolutions, an optional background image, an optional 3D avatar, plus the LSP-3 JSON itself to Cascade, encodes a hash-bound LSP-2 VerifiableURI, and writes it to the user's UP. Once the transaction confirms, the profile renders correctly on universalprofile.cloud, universaleverything.io, and the Universal Profile Browser Extension, with no reader-side awareness that Cascade is involved.

Prerequisites

A Universal Profile on Lukso mainnet (chain ID 42) or testnet (chain ID 4201). If you don't have one, install the Universal Profile Browser Extension and create one. The wallet wiring shown below targets mainnet by default; swap lukso for luksoTestnet if you're on testnet.
A cascade-api bearer token. The public deployment lives at https://api.lumera.help; request a key from the operator. Self-hosters can run the backend without auth.
Node.js 20+.

Install

npm install @erc725/erc725.js @lumera-protocol/data-provider-cascade viem

Architecture

browser
  │
  ├─ viem + window.lukso ────────── setData on UP ──→ Lukso L1
  │
  └─ POST /api/upload (Next.js Route Handler)
            │
            └─ @lumera-protocol/data-provider-cascade
                    │   Authorization: Bearer $CASCADE_API_TOKEN
                    │
                    └─ POST {CASCADE_API_URL}/upload (cascade-api)
                              │
                              ├─ MsgRequestAction → Lumera L1 (pays ulume)
                              └─ stream bytes → Cascade Supernodes (RaptorQ)

Two halves: the Lukso half (browser ↔ Lukso L1, signed by the UP browser extension) and the Cascade half (browser → your server → cascade-api). The two halves only meet in setData, where you write the cascade-api URL into LSP-3.

Step 1: Build the LSP-3 JSON

LSP-3 is a fixed shape. The schema lives in @erc725/erc725.js/schemas/LSP3ProfileMetadata.json.

lib/lsp3.ts

type ImageEntry = {
  width: number;
  height: number;
  url: string;
  verification?: { method: "keccak256(bytes)"; data: `0x${string}` };
};
 
type AvatarEntry = {
  url: string;
  fileType: string;
  verification: { method: "keccak256(bytes)"; data: `0x${string}` };
};
 
export type LSP3ProfileJSON = {
  LSP3Profile: {
    name: string;
    description: string;
    links: { title: string; url: string }[];
    tags: string[];
    profileImage: ImageEntry[];
    backgroundImage: ImageEntry[];
    avatar: AvatarEntry[];
  };
};

Every asset entry uses the same verification: { method, data } shape; the only structural difference is that profileImage[] and backgroundImage[] carry width/height (so readers can pick a resolution), while avatar[] carries fileType (so renderers can pick .vrm, .glb, .gltf etc.).

Some older tutorials show avatar[] entries as { hashFunction, hash, fileType, url }. That predates the current LSP-3 spec and the schemas shipped with @erc725/erc725.js ≥ 0.21, both of which use verification. New code should use verification.

Step 2: Resize images client-side

A typical reader (e.g. universalprofile.cloud) wants to render the profile image at multiple sizes: thumbnail in chat lists, medium in profile cards, large on the profile page. LSP-3 supports this natively as an array.

lib/resize.ts

export async function resizeImage(
  file: File,
  sizes: number[],
  mime: "image/jpeg" | "image/png" = "image/jpeg",
): Promise<{ width: number; height: number; blob: Blob }[]> {
  const bitmap = await createImageBitmap(file);
  const minSrc = Math.min(bitmap.width, bitmap.height);
  const sx = (bitmap.width - minSrc) / 2;
  const sy = (bitmap.height - minSrc) / 2;
 
  const out: { width: number; height: number; blob: Blob }[] = [];
  for (const size of sizes) {
    if (size > minSrc) continue; // do not upscale
    const canvas = document.createElement("canvas");
    canvas.width = canvas.height = size;
    const ctx = canvas.getContext("2d")!;
    ctx.imageSmoothingQuality = "high";
    ctx.drawImage(bitmap, sx, sy, minSrc, minSrc, 0, 0, size, size);
    const blob = await new Promise<Blob>((resolve) =>
      canvas.toBlob((b) => resolve(b!), mime, 0.92),
    );
    out.push({ width: size, height: size, blob });
  }
  // Always include source resolution if it's not redundant with a target.
  if (!sizes.some((s) => Math.abs(s - minSrc) <= 32)) {
    out.push({ width: minSrc, height: minSrc, blob: await sourceCenterCrop(bitmap, sx, sy, minSrc, mime) });
  }
  return out;
}

The detail to internalise: always include the source resolution as a final variant (unless it would be redundant with a target). Otherwise users uploading a 700×700 photo with targets [256, 512, 1024] get only one variant, which is a bad surprise.

Step 3: Upload to Cascade through your Route Handler

Server-side: a thin proxy that owns the bearer token and calls @lumera-protocol/data-provider-cascade.

app/api/upload/route.ts

import { NextResponse } from "next/server";
import { CascadeUploader } from "@lumera-protocol/data-provider-cascade";
 
export const runtime = "nodejs";
export const maxDuration = 120; // cascade upload is 30-60s typical
 
export async function POST(req: Request): Promise<Response> {
  const uploader = new CascadeUploader({
    backendUrl: process.env.CASCADE_API_URL,    // default: https://api.lumera.help
    bearerToken: process.env.CASCADE_API_TOKEN, // required
  });
 
  const form = await req.formData();
  const file = form.get("file");
  if (!(file instanceof File)) {
    return NextResponse.json({ error: "Missing 'file' field" }, { status: 400 });
  }
 
  const { url, hash, meta } = await uploader.uploadWithMetadata(file);
  // url:  https://api.lumera.help/download/<action_id>
  // hash: 0x<keccak256 of file bytes>
  // meta: { action_id, tx_hash, block_height, task_id, filename, size_bytes }
  return NextResponse.json({ url, hash, meta });
}

uploadWithMetadata() is a Lumera-specific extension that returns the cascade-api raw response (tx_hash, block_height, action_id, etc.) on top of the standard { url, hash } shape. If you only need the standard shape (for instance, you're swapping out an existing @lukso/data-provider-pinata call), use uploader.upload(file) instead and get back { url, hash }.

Step 4: Encode the LSP-2 `VerifiableURI`

erc725.js knows the byte layout. Pass the JSON object and its URL; it computes the hash and stitches the bytes together.

lib/encode.ts

import { ERC725 } from "@erc725/erc725.js";
import LSP3ProfileSchema from "@erc725/erc725.js/schemas/LSP3ProfileMetadata.json" with { type: "json" };
 
export function encodeLSP3Profile(
  profileAddress: `0x${string}`,
  json: object,
  url: string,
): { key: `0x${string}`; value: `0x${string}` } {
  const erc725 = new ERC725(
    LSP3ProfileSchema,
    profileAddress,
    process.env.NEXT_PUBLIC_LUKSO_RPC!,
  );
  const encoded = erc725.encodeData([
    { keyName: "LSP3Profile", value: { json, url } },
  ]);
  return {
    key: encoded.keys[0] as `0x${string}`,
    value: encoded.values[0] as `0x${string}`,
  };
}

Behind the scenes, erc725.js produces:

keys[0] = 0x5ef83ad9559033e6e941db7d7c495acdce616347d28e90c7ce47cbfcfcad3bc5 (the LSP3Profile data key, a constant)
values[0] = 0x00006f357c6a0020<keccak256(JSON.stringify(json))><url-bytes>

The 0x6f357c6a is the keccak256(utf8) method ID. The 0x0020 is the hash length (32 bytes).

Step 5: `setData` on the Universal Profile

lib/wallet.ts

import { createWalletClient, custom, parseAbi } from "viem";
import { lukso, luksoTestnet } from "viem/chains";
 
const UP_ABI = parseAbi([
  "function setData(bytes32 dataKey, bytes dataValue) external payable",
]);
 
export async function setUPData(
  upAddress: `0x${string}`,
  key: `0x${string}`,
  value: `0x${string}`,
): Promise<`0x${string}`> {
  const client = createWalletClient({
    chain: lukso, // or luksoTestnet for chain ID 4201
    transport: custom(window.lukso!), // UP browser extension
  });
  return client.writeContract({
    account: upAddress, // the UP itself; the extension routes through the controller
    address: upAddress,
    abi: UP_ABI,
    functionName: "setData",
    args: [key, value],
  });
}

The Universal Profile Browser Extension exposes the UP address as the connected account. When you writeContract with account: upAddress, the extension automatically routes the transaction through the controller key (an EOA the user holds) into the UP. You do not interact with LSP6KeyManager directly.

Putting it together

app/page.tsx (excerpt)

async function onSubmit() {
  // 1) Profile image: resize variants + always include source resolution.
  const profileImage = [];
  if (profileFile) {
    const variants = await resizeImage(profileFile, [256, 512, 1024]);
    for (const v of variants) {
      const r = await uploadToCascade(v.blob, `profile-${v.width}.jpg`);
      profileImage.push({
        width: v.width,
        height: v.height,
        url: r.url,
        verification: { method: "keccak256(bytes)", data: r.hash },
      });
    }
  }
 
  // 2) Background image (uploaded as-is).
  const backgroundImage = [];
  if (backgroundFile) {
    const r = await uploadToCascade(backgroundFile, backgroundFile.name);
    backgroundImage.push({
      width: backgroundDims.w,
      height: backgroundDims.h,
      url: r.url,
      verification: { method: "keccak256(bytes)", data: r.hash },
    });
  }
 
  // 3) Avatar (3D model or image fallback).
  const avatar = [];
  if (avatarFile) {
    const r = await uploadToCascade(avatarFile, avatarFile.name);
    avatar.push({
      url: r.url,
      fileType: detectFileType(avatarFile), // "vrm", "glb", "png", ...
      verification: { method: "keccak256(bytes)", data: r.hash },
    });
  }
 
  // 4) Build LSP-3 JSON, upload it to Cascade.
  const profile = buildProfile({ name, description, links, tags, profileImage, backgroundImage, avatar });
  const jsonResult = await uploadJSONToCascade(profile, `${account}-lsp3.json`);
 
  // 5) Encode VerifiableURI and setData on the UP.
  const { key, value } = encodeLSP3Profile(account, profile, jsonResult.url);
  const tx = await setUPData(account, key, value);
  console.log("setData tx:", tx);
}

For a 1024×1024 source image with a background and a VRM avatar, that's 5 to 6 Cascade uploads per save (3 profile-image variants + 1 background + 1 avatar + 1 JSON), each one its own on-chain action on Lumera, each one billed once and stored forever.

How retrieval works

Reading is the inverse, and crucially, standard Lukso clients don't need a Cascade-aware reader. Any HTTPS-fetching reader works against the cascade-api gateway URL.

lib/read.ts

import { ERC725 } from "@erc725/erc725.js";
import LSP3ProfileSchema from "@erc725/erc725.js/schemas/LSP3ProfileMetadata.json" with { type: "json" };
 
const erc725 = new ERC725(
  LSP3ProfileSchema,
  profileAddress,
  "https://rpc.mainnet.lukso.network",
);
 
const data = await erc725.fetchData("LSP3Profile");
console.log(data.value);
// {
//   LSP3Profile: {
//     name: "Alice",
//     profileImage: [
//       { width: 256, height: 256, url: "https://api.lumera.help/download/15823", verification: { ... } },
//       { width: 512, height: 512, url: "https://api.lumera.help/download/15824", verification: { ... } },
//       ...
//     ],
//     ...
//   }
// }

fetchData does four things in one call: pulls the on-chain bytes, decodes the VerifiableURI, fetches the JSON via HTTPS, and verifies the keccak256 hash matches the on-chain commitment. If the hash doesn't match, it throws. Per-image verification is the caller's responsibility.

Lessons from the reference implementation

Multi-resolution profile images are a meaningful Cascade load. A single profile-image upload can be 3-4 variants if the source is large enough. It exercises the cascade-api fully and matches what readers actually want.
Avatars are the killer storage demo. A VRM file is typically 5-30 MB; that's exactly the kind of asset where pin-loss on IPFS would actually hurt. Cascade's pay-once-store-forever model directly addresses it.
Always include source resolution as a fallback variant. Targets that exceed the source are skipped by the resize step; without a source-resolution fallback, a 400px upload would only produce one variant.
Keep the bearer token server-side. Move the upload through a Next.js Route Handler. Server-side concurrency will be the eventual bottleneck before client-side will.
The on-chain footprint per save is one setData call. The total work the user signs is exactly one transaction on Lukso, regardless of how many Cascade uploads happened.